# @eqtylab/explorer 中文文档

规范地址：https://npmcn.com/package/%40eqtylab/explorer/

版本：0\.22\.0
npm 元数据更新时间：2026-11-13T22:40:00.530Z
中文译文更新时间：2026-11-13T23:06:26.292Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eqtylab/explorer
原文对照：https://npmcn.com/package/%40eqtylab/explorer/?lang=original
源码仓库：https://github.com/eqtylab/explorer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：50.4 MB，366 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：18 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2026-01-28T15:53:13.707Z
- 最新版本发布：2026-11-13T22:40:00.347Z
- 近 30 天下载量：2998（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

EQTYLab 探索器(承诺:0a51443)

## 安装

```sh
npm install @eqtylab/explorer
```

也可以使用：`pnpm add @eqtylab/explorer`、`yarn add @eqtylab/explorer`、`bun add @eqtylab/explorer`

## README

# EQTYLab 探索器

探索数据行和计算完整性的可视化工具. EQTYlab生态系统的一部分,它展示了数据出地链,显示数据如何通过计算系统流动,哪些行为者参与其中,以及附上哪些核查声明.

它同时作为主机在 [探险家.eqtylab.io](https://explorer.eqtylab.io/) 并作为一个可嵌入的库,在任何一页内显示——反应与否.

## 更改日志

见 [变动情况](https://npmcn.com/package/%40eqtylab/explorer/CHANGELOG.md) 用于修改和 [捐款额](https://npmcn.com/package/%40eqtylab/explorer/CONTRIBUTING.md) pR和释放指令.

## 特征

-   **交互式图形可视化**: 使用缩放/平面控制拖放画布
-   **详细检查员**: 显示选定节点的注册、治理、存储和签名细节的侧边栏
-   **可嵌入**: 将一个脚本标签降入任意一页 `<eqty-explorer>`,在阴影根中隔离,所以两个页面都无法重塑另一个
-   **双操作模式**数字 :
    -   **外观查看器**: 上传或选择显示的样本 JSON 文件以探索
    -   **廉正处**: 查询清单的后端完整性服务

## 嵌入

探险家被设计为被投放到它无法控制的一页. 使用 `<eqty-explorer>` 定制元素,除非你有特定的理由不这样做,这是干净而简单的.

### 默认: 自定义元素

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@eqtylab/explorer/dist/standalone/explorer.js"></script>

<eqty-explorer manifest-url="/my-manifest.json" theme="auto" style="height: 600px"></eqty-explorer>
```

或者,您可以从 npm 而不是 CDN 导入自定义元素 :

```ts
import { defineExplorerElement } from "@eqtylab/explorer";

defineExplorerElement();
```

### 反应

**反应应用程序** ——使用组件,所以探险家用你的树作曲,上下文 和出错边界 :

```bash
npm install @eqtylab/explorer react react-dom
```

```tsx
import { Explorer } from "@eqtylab/explorer";
import "@eqtylab/explorer/style.css"; // required — only the CDN build self-injects

<Explorer manifest={manifestJson} theme="auto" />;
```

**你的建筑需要一个Es2022目标.** 签名验证负载 顶级 `await`维特的默认目标断然拒绝.. `esbuild` 失败 "Top-level wait 在配置的目标环境中不可用". 在维特就是 `build: { target: "es2022" }`;其他捆绑者想要自己的等同.

### 提供一份清单

通过解析对象或 JSON 字符串为 `manifest`,或URL为 `manifestUrl`· ; `manifest` 二者皆为胜. 这些道具是说探险家的唯一方法 显示 : 它没有自己的上传或明确的控制, 所以让用户打开自己的 文档,在页面中读取,并将结果通过 `manifest`设置两个显示 一个空的图表.

### 配置

| 选项 | 反应 | `<eqty-explorer>` | 默认 | 页:1 |
| --- | --- | --- | --- | --- |
| `manifest` | `manifest={obj}` | 属性、财产或子女 `<script type="application/json">` | —— 说 | 解析对象或 JSON 字符串 |
| `manifestUrl` | ✓ | `manifest-url` | —— 说 | 在挂载上抓取, 如果改变, 将再次抓取 |
| `view` | ✓ | `view` | `lineage` | `lineage`, (中文(简体) ), `table` 或者说 `text`; 仅首字母 |
| `theme` | ✓ | `theme` | `auto` | `light`, (中文(简体) ), `dark`,或跟随主机 `prefers-color-scheme` |
| `cssVars` | ✓ | 只有属性 | —— 说 | Token 超载等. `{ "--brand-lineage-explorer": "#0af" }` |
| `nodeOverrides` | ✓ | 只有属性 | —— 说 | 每个资产类型的节点外观 |
| `customIcons` | ✓ | 只有属性 | —— 说 | 图标覆盖按资产类型按键 |
| `groupNodeThreshold` | ✓ | `group-node-threshold`,或财产 | `5` | 有多少兄弟节点会崩溃成一组 |
| `selectedNodeId` | ✓ | `selected-node-id`,或财产 | —— 说 | 通过 id 选择一个节点; 当它改变时重新应用 |
| `selectedStatementId` | ✓ | `selected-statement-id`,或财产 | —— 说 | 在文本视图中显示语句, 切换到它 |
| `selectedBlobCid` | ✓ | `selected-blob-cid`,或财产 | —— 说 | 在文本视图中显示一个 blob; 如果同时设置, 语句将胜出 |
| `query` | ✓ | `query`,或财产 | —— 说 | 过滤每个视图; 当修改时重新应用 |
| `onManifestChange` | ✓ | `manifestchange` 事件 | —— 说 | 细节是 `Manifest | null` |
| `onNodeSelect` | ✓ | `nodeselect` 事件 | —— 说 | 细节是节点代号,或者 `null` 当选择被清除时 |
| `onStatementSelect` | ✓ | `statementselect` 事件 | —— 说 | 细节是语句键,或 `null` 当没有显示时 |
| `onBlobSelect` | ✓ | `blobselect` 事件 | —— 说 | 细节是Blob CID,或 `null` 当没有显示时 |
| `onQueryChange` | ✓ | `querychange` 事件 | —— 说 | 细节是应用的查询字符串, `""` 清空时 |
| `onError` | ✓ | `error` 事件 | 无论哪种方式都登录 | 无法解析的 JSON, 无法获取 |
| `portalContainer` | ✓ | 为你准备 | 共享容器 | 只有在你把重叠 某处不寻常 |
| `config`, (中文(简体) ), `vCompData` | ✓ | —— 说 | —— 说 | 只反应 — 提供预建的配置或已分解的 vComp 状态 |

属性是活的——改变一个重接.

值为对象的选项没有属性形式,因为属性只能 带一串. 在元素进入文档之前或之后将这些属性设定为属性 :

```js
const el = document.querySelector("eqty-explorer");
el.manifest = parsedObject;
el.customIcons = { dataset: "/icons/dataset.svg" };
el.cssVars = { "--brand-lineage-explorer": "#0af" };

el.addEventListener("nodeselect", (e) => console.log(e.detail)); // string | null
el.addEventListener("statementselect", (e) => console.log(e.detail)); // string | null
el.addEventListener("blobselect", (e) => console.log(e.detail)); // string | null
el.addEventListener("querychange", (e) => console.log(e.detail)); // string
el.addEventListener("manifestchange", (e) => console.log(e.detail)); // Manifest | null
el.addEventListener("error", (e) => console.error(e.detail)); // Error
```

**容器需要一个高度.** 探险家会随心所欲地填满一个容器 没有高地,你应当在控制台上警告他.

### 样式

主机和未来的代理设备在应用前可以检查查询 导出 `checkQuery(index, query)` API,使用来自 `buildQueryIndex(nodes, edges, { statements, blobs, anchors })`,每个读取 节点的元数据,证书和来自清单报表的演员. 它回来了 `{ valid, ready, errors, warnings }`,诊断有 `code` 财务报告和审定财务报表 `message`。 。 。 . 此检查不符合节点、 横行、 更新查询或更改 显示。 通过 `query` 道具或属性仅在 `valid` 这是真的. `ready` 附加排除纯文本, UI 等待 应用到 Enter; 一个空查询是有效的, 并准备就绪 。 缺少的数值 当前列表生成警告而不是取消查询; 这些警告 还在输入值时延迟自动应用。 关闭的enums 例如 `has:` 拒绝未知值。 对照同一字段进行校验 评价使用的定义和汇编逻辑,但不评价匹配.

Canonical 查询字段遵循表列名称 : `registeredBy`, (中文(简体) ), `assetType`, (中文(简体) ), `metadata.<path>`,以及 `associationType`上一个 `by`, (中文(简体) ), `type`, (中文(简体) ), `meta`, (中文(简体) ), `assoc`,以及 `association` 拼写仍然是别名。 演员选择插入 DDE 并显示名称;也可以直接查询演员姓名。 相邻术语表示 而且,优先不是,然后,然后,然后或。 括号优先于优先. 支持元数据的数字比较和数字范围; `timestamp` 是文本,包含 `after` 编号 : `before` 用于时间顺序查询的日期过滤器. `mentions:` (或 `ref:`)取出一个id,它的开始,或者一个名字,并匹配什么 关于除此以外一个节点名称的声明:输入、管理文件、 存储位置,一个操作员。 零字搜索名称,类型,演员姓名, 元数据和文本; 标识符从开始就匹配一个空字.

在文本视图中,同一查询过滤语句,读取两个字段中的一个 办法 多数人读取该语句的内容(数据或计算节点、DID或 ),根据世系观点 该节点: `name`, (中文(简体) ), `assetType`, (中文(简体) ), `is`, (中文(简体) ), `has`, (中文(简体) ), `metadata.<path>`, (中文(简体) ), `associationType`, (中文(简体) ), 世系地和空话。 这么说吧 `assetType:Model` 列出模型的 登记、元数据、签署证书、存储和治理: 线条视图显示节点后面的语句。 其他人读一下 声明本身: `statement:` (其本身类型 : `data`, (中文(简体) ), `metadata`, (中文(简体) ), `credential`, (中文(简体) ), `did`, (中文(简体) ), `actordid`, (中文(简体) ), `entity`,...;未知类型只发出警告, `registeredBy`, (中文(简体) ), `operatedBy`, (中文(简体) ), `executedOn`, (中文(简体) ), `timestamp`, (中文(简体) ), `after`, (中文(简体) ), `before` 财务报告和审定财务报表 `mentions`这些 与世系观点的答案不同: `registeredBy:alice` 列出爱丽丝 ,包括元数据,她在一个节点上添加了另一个注册的人 `statement:metadata` 列出元数据注册,而不是它们的节点 说明。 Blobs 标签列出查询匹配的blobs, 每一个响应为 它属于(作为注册的数据或元数据blob),或当它属于 属于无,按其CID,名称和路径,有列表的收藏文件. 一个小块 未列出匹配语句的引用: `is:computation` 列表 a 计算元数据blob,而不是它输入的数据. `checkQuery` 带有索引 从 `buildQueryIndex` 验证家族和表的含义.

**字体不捆绑.** `--font-sans` 决定: `TWK Lausanne`编号 :`Inter` 财务报告和审定财务报表 `--font-mono` 改为 `IBM Plex Mono`自己为那些服务 或者探险家回到 系统字体.

故意重塑样式,使用 `cssVars` 而不是样式表。 Token 覆盖工作 因为自定义属性会越过阴影边界 选择者不能.

### 演示文稿

```bash
pnpm build
pnpm demo   # then open http://localhost:4173/demo/embed.html
```

`demo/embed.html` 是故意敌对的主机页面——它重新定义了相同的 CSS 定制 勘探者使用的属性名称、样式 `main`编号 :`ul`编号 :`img` 直接定义自己的 `.flex` 课。 上面的四名探险家 覆盖了所有四个显示的来源, 对象值 属性和两个主题,每个都用阴影根. `demo/react/` 涵盖 光-DOM路径,是反应组件的. `demo/react/` 覆盖 npm 路径和对等依赖分拆 .

## 先决条件

这个项目使用 [无](https://nixos.org/) 发展环境管理。 安装 Nix, 然后 devshell 将提供所有所需的依赖 .

或者,确保您安装了 :

-   节点.js
-   小时

## 地方发展

```bash
# Enter the Nix development shell (if using Nix)
nix develop

# Install dependencies
pnpm install

# Start development server
pnpm dev
```

## 可用命令

| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 在探险家的源头启动网站的 Dev 服务器 |
| `pnpm build` | 构建所有三个目标并核实CSS范围界定 |
| `pnpm build:lib` | 构建 npm 软件包 |
| `pnpm build:standalone` | 构建 CDN 捆绑 |
| `pnpm build:site` | 构建主机站点( 需要 ) `pnpm build:lib` (第一个) |
| `pnpm check:css` | 校验已建的样式表无法逃脱其范围 |
| `pnpm demo` | 给钱吧 `demo/embed.html` 可打开 |
| `pnpm fmt` | Pretier 格式代码 |
| `pnpm format:check` | 检查代码格式 |
| `pnpm lint` | 运行 ESLint |
| `pnpm lint:fix` | 使用自动修正运行 ESLint |
| `pnpm typecheck` | 运行类型脚本类型检查 |

## 仓库布局

仓库根是 `@eqtylab/explorer` 软件包。 主办网站位于 `site/`, (中文(简体) ), 依赖于软件包的私人 pnpm 工作空间成员 `workspace:*` 财务报告和审定财务报表 进口只进口其公共入境点(eslint执行),与其他消费者一样. 网站拥有自有的染色体,显示的上传UI和样本显示于 `site/public/manifests`,包的测试也读作是固定的.

## 构建产出

工程建设了三件事.

1.  **npm 软件包** (单位:千美元)`dist/lib/`() ——作为 `@eqtylab/explorer`仅限无害环境管理,有反应 作为同伴的依赖。 样式表船与它相伴 `@eqtylab/explorer/style.css`。 。 。 .
2.  **CDN 捆绑** (单位:千美元)`dist/standalone/`)——反应和一个文件中的每个依赖,由: 单人 `<script type="module">`它注入了自己的风格。 签字核查 WebAssembly 保留一个单独的文件,并负载在先使用时.
3.  **托管网站** (单位:千美元)`site/dist/`)——网站位于 [探险家.eqtylab.io](https://explorer.eqtylab.io/). 其生产 `@eqtylab/explorer` 改为 `dist/lib` 及其范围样式表,所以部署的站点运行 和Npm的消费者一样 它只在发布时部署,就像包裹一样.

`pnpm dev` 而不是从 `src/` 热重装( 见 `vite/explorer-source.ts`),留下了两件它没有覆盖的东西.

-   **范围为CSS.** `scope-css` 在捆绑的时间运行, 因此在 dev 中, 探索者的样式表是 无法瞄准 扫描错误只出现在真正的建筑中,所以CI运行 `pnpm check:css`,以及 `pnpm build && pnpm preview` 与已建的软件包相对应.
-   **定制元素.** 网站使 `<Explorer>`,因此dev服务器从不创建 `<eqty-explorer>`。阴影根、所采纳的样式表和 per-instance 门户 集装箱包含在 `demo/embed.html`它与一个活生生的包.

## 释放

通过 GitHub Actions 自动发布,并通过将版本撞入 `package.json` 打开 `main`。 。 。 .

### 如何释放

1.  准备稳定放出部分 [变动情况](https://npmcn.com/package/%40eqtylab/explorer/CHANGELOG.md)后续 [释放指令](https://npmcn.com/package/%40eqtylab/explorer/CONTRIBUTING.md#releases)。 。 。 .
2.  弹出 `version` 内 `package.json` 在同一公关中运行 `./scripts/check-changelog.sh vX.Y.Z` 与预定版本.
3.  打开 PR 并合并到 `main`

当变化到达 `main`,则 [释放](https://npmcn.com/package/%40eqtylab/explorer/.github/workflows/release.yml) 工作流程将自动 :

-   检查稳定版本是否有匹配的更改日志标题
-   将承诺标记为 `v<version>` 并创建带有生成注释的 GitHub 释放
-   打电话 [发布](https://npmcn.com/package/%40eqtylab/explorer/.github/workflows/publish.yml) 构建和发布到 npm 的工作流程

含有连字符的版本(例如:. `0.11.0-rc1`)被标记为GitHub预放出. 请注意, npm 仍然发布在 `latest` dis.

### 版本管理

`package.json` 是该版本唯一的真理来源。 如果标签 `v<version>` 已存在,发布工作流程无所作为.

发布工作流程对照更改日志检查有效版本 包括干燥跑道。 候选人和非官方的标签跳过此支票.

也可以手动触发出版:

-   **发布** 通过 _运行工作流程_ 未出版的建筑和包装(`--dry-run` 以 默认; 未选中可发布当前版本 `package.json`(中文(简体) )
-   手动创建 GitHub 发行版, 仍会用其标签发布版本

## 应用程序配置

见 [配置文档](https://eqty-lab.readme.io/update/docs/custom-config#/) 用于定制选项.

## 添加示例说明

1.  将 JSON 文件添加到 `./site/public/manifests`
2.  更新 `manifests` 节 `./site/src/config.json`
    -   名称必须匹配没有扩展名的文件名

## 常见问题

### @eqtylab/explorer 是什么？

EQTYLab 探索器\(承诺:0a51443\)

### 如何安装 @eqtylab/explorer？

在项目目录运行 npm install @eqtylab/explorer，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @eqtylab/explorer 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eqtylab/explorer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eqtylab/explorer 可以商用吗？

@eqtylab/explorer 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @eqtylab/explorer 的下载量有多少？

根据 npm 官方下载统计，@eqtylab/explorer 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,998 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eqtylab/explorer 还在维护吗？

最新版本 0\.22\.0 发布于 2026/11/14（今天）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/01/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。