# @ecopages/dev-toolbar 中文文档

规范地址：https://npmcn.com/package/%40ecopages/dev-toolbar/

版本：0\.7\.1
npm 元数据更新时间：2026-11-12T23:40:30.592Z
中文译文更新时间：2026-11-13T06:17:27.827Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：184 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.22\.0 \|\| \>=26\.0\.0
- 运行依赖：3 个
- 首次发布：2026-07-21T22:06:01.373Z
- 最新版本发布：2026-11-12T23:40:30.241Z
- 近 30 天下载量：2686（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

Ecopage 开发工具栏

## 安装

```sh
npm install @ecopages/dev-toolbar
```

也可以使用：`pnpm add @ecopages/dev-toolbar`、`yarn add @ecopages/dev-toolbar`、`bun add @ecopages/dev-toolbar`

## README

# @ ecopages/ dev-toolbar (翻译)

Ecopages 的只开发浏览器工具栏. 挂载期间 `ecopages dev` 并且不运送生产建筑.

面向用户的文件 : [Dev 工具栏](https://ecopages.dev/docs/core/dev-toolbar) (平生,显生,内生应用).

## 安装

将软件包添加到您的应用程序中并从配置中选择 :

```ts
import { defineConfig } from '@ecopages/core/config';
import { devToolbar } from '@ecopages/dev-toolbar/config';

export default defineConfig({ devToolbar: devToolbar() });
```

```bash
pnpm add -D @ecopages/dev-toolbar
```

期间 `ecopages dev`,核心捆绑您的配置软件包 `/_dev_toolbar.js` 并输入 Deps 面板的 dev 列表。 在工具栏客户端更改后重新启动 Dev 服务器 .

`@ecopages/dev-toolbar` 映射本地浏览器捆绑的核心显示合同( n)`src/api/manifest-contract.ts`; 保持同步通过 `manifest-contract.test.ts`。 。 。 .

禁用每个工程 `devToolbar: { enabled: false }`,或每个进程 `ECOPAGES_DEV_TOOLBAR=false`。 。 。 .

## 内建的应用程序

-   **构建错误** – 在 HMR 错误上自动打开, 显示隐形模式, 列出不同的消息为文本, 并显示一个错误计数徽章; 任何非 error HMR 事件清除消息和徽章
-   **导航** ——路由计时归档,初始载荷,客户端导航延迟,HMR状态,和页面集成(由核心导航协调员报告的当前所有者) `#__ECO_DEV_NAV_TELEMETRY__` 内 `document.head` (与 `data-eco-persist`并揭露 `window.__ECO_DEV_NAV_TELEMETRY__` 用于机器/AI调试
-   **选项** —页面浏览器 Graph access/chunk 资产,销售商 URL,懒惰的负载提示
-   **群岛** - 检查印有邮票的岛屿主机 `data-eco-island`,包括允许的安全部门改革 `<eco-island>` 主机; 重复组件实例独立显示和水合状态报告 `hydrated` (通过) `data-eco-hydrated` 或经核实的组件更新完成, `registered` (关于有待更新的自定义要素),或 `ssr-only`
-   **A11y (英语)** ——轴心审计(内置倒计时检查)和页内要闻
-   **设置** ——码头放置(上,下,左,右),隐形模式,以及文档链接

## 带上您的 Dev 工具栏

核心在 `/_dev_toolbar.js` 并注入 `#__ECO_DEV_MANIFEST__` 每页。 你的软件包拥有码头UI和面板.

替换此引用工具栏:

1.  创建客户端软件包,导出浏览器靴子模块(布局相同于 `@ecopages/dev-toolbar`) (中文(简体) ).
2.  设定 `devToolbar.package` 内 `eco.config.ts` (使用时 `defineDevTool` 从 `@ecopages/core/client` bYO 软件包.
3.  叉或复制此软件包, 如果您想要 Radiant 面板, 显示阅读器, 和隐形码头行为 .

`@ecopages/dev-toolbar` 是参考执行.

自定义客户端可以声称 HMR 运行时间可取消 `ecopages:build-error` 窗口事件( e)`detail: { message: string }`与同步 `preventDefault()` 以压制页面回落。 听着 `ecopages:build-error-clear` 重置错误。 在登记听众后, 发送 `ecopages:build-error-request` 如果挂起时间较晚, 将重放活动信件 。 核心导出名称和有效载荷类型 `@ecopages/core/client`;参考客户端在本地镜像事件名称,用于浏览器捆绑. 未声明错误仍然使用倒计时. 卸载时删除听众 .

## 参考工具栏内部

`window.__ECO_DEV_TOOLBAR_APPS__` 是本套件内用于实验性额外码头应用的可选注册. 没错 **没有** 支持的 Ecopages 扩展 API - 应用程序作者应当替换 `devToolbar.package` 换句话说.

## 软件包布局

-   `src/bootstrap.ts` ——向 CSS 输入工具栏 `document.head`、靴子导航遥测和挂载 `eco-dev-toolbar`; 重新装入安全遥测所有权防止 HMR 捆绑再评价添加重复的文档收听器
-   `src/runtime/navigation-events.ts` ——共享核心的导航生命周期事件名称和一个DOM监听器跨工具栏应用程序,在最终订阅者卸载时删除
-   `src/runtime/navigation-telemetry.ts` ——读取当前所有者来自 `getOwnerState()` 因此, 浏览器和React 路由器的所有权被一致报告
-   `src/shell/eco-dev-toolbar.tsx` —— Radiant光-DOM主机(JSX) `render()`,无阴影根;面板定位为纯 CSS
-   `src/shell/motion.ts` - WAAPI关于隐形码头的动议只披露;面板显示/隐藏为CSS
-   `src/apps/*-panel.tsx` - Radiant JSX小组(导航、船底、岛屿、a11y、设置)
-   `src/api/manifest-contract.ts` – 浏览器- 核心 dev 显示合同的本地镜像
-   `src/api/build-error-contract.ts` ——浏览器-本地事件名称对照公共核心构建出错合同进行核对
-   `src/api/dev-manifest.ts` - 内部DOM读取/写入 `#__ECO_DEV_MANIFEST__`
-   `src/api/types.ts` ——工具栏应用程序主机合同
-   `src/shell/` ——自定义元素主机,SVG图标,样式,以及 `ensureDevToolbarStyles()` (BYO工具栏的可选 CSS 覆盖)

## 常见问题

### @ecopages/dev-toolbar 是什么？

Ecopage 开发工具栏

### 如何安装 @ecopages/dev-toolbar？

在项目目录运行 npm install @ecopages/dev-toolbar，或使用 pnpm add / yarn add / bun add。

### @ecopages/dev-toolbar 支持 TypeScript 吗？

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

### @ecopages/dev-toolbar 支持 ESM 还是 CommonJS？

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

### @ecopages/dev-toolbar 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.22\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ecopages/dev-toolbar 可以商用吗？

@ecopages/dev-toolbar 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ecopages/dev-toolbar 的下载量有多少？

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

### @ecopages/dev-toolbar 还在维护吗？

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