# @chengzhiyi/pi-excalidraw 中文文档

规范地址：https://npmcn.com/package/%40chengzhiyi/pi-excalidraw/

版本：0\.1\.6
npm 元数据更新时间：2026-11-07T16:05:54.464Z
中文译文更新时间：2026-11-09T12:15:04.204Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chengzhiyi/pi-excalidraw
原文对照：https://npmcn.com/package/%40chengzhiyi/pi-excalidraw/?lang=original
项目主页：https://github.com/chengzhiyi/pi-extensions#readme
源码仓库：https://github.com/chengzhiyi/pi-extensions

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

- 包体积（解压后）：24.9 MB，432 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-25T10:31:19.010Z
- 最新版本发布：2026-11-07T16:05:54.122Z
- 近 30 天下载量：4354（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

自定义主机 v2 用于 pi- webapp 的 Excalidraw 插件

## 安装

```sh
npm install @chengzhiyi/pi-excalidraw
```

也可以使用：`pnpm add @chengzhiyi/pi-excalidraw`、`yarn add @chengzhiyi/pi-excalidraw`、`bun add @chengzhiyi/pi-excalidraw`

## README

# @chogzhiyi/pi-excalidraw (英语)

见 [前端架构和用户界面谈判](https://github.com/chengzhiyi/pi-extensions/blob/main/packages/excalidraw/FRONTEND.md) 对主机的卡, 页面级参数,生命周期/相容性以及"影子DOM"可行性探测器.

Hosted v2 Excalidraw 软件包. 从 `pi-webapp-excalidraw` 源头的图表 `d87f24e`,包括: `b01b6bb` 持久性/分组变化。 没有主机-私人导入,共享反应,直接检查点写入,工作空间文件系统访问,账户,协作,图像附件或外部嵌入.

## 在 pi-webapp 中安装和更新

这个 **官方可选插件**,作为 `@chengzhiyi/pi-excalidraw` 时间npm。 使用一个 pi-webapp 主机 **主机 v2 运行时间**: 发布或安装此软件包不会将运行时间添加到旧主机上. 特别是,一个在主机-v2迁移之前的宿主分支/放行并非仅由本套件的出版来兼容.

在兼容的主机中, 打开 **插件**,找到官员 **缩略图** 牌,选择 **安装**,则 **启用**。在安装前可以不下载编辑器或字体而列出卡片。 已发布的软件包已包含编辑器,React,字体等浏览器资产;终端用户不构建或安装此寄存器的开发依赖. 不要在主机的根目录中安装依赖性,以替代插件管理器.

使用 **检查更新** 和为独立插件更新提供更新动作。 兼容软件更新也同步已安装的官方插件;它们不会安装缺失的插件或可重新启用的已禁用插件. 没有可配置的更新政策选择器 。 版本相容性,完整性检查和成功的检查站同步仍然被激活.

打开编辑器默认推迟版本切换. 关闭并应用待更新, 或明确选择 **更新并重新打开** 在审查了本地撤销/重置历史的警告后 。 只替换插件的视图/运行时间:保留主机页面和代理会议. 不要将下载、注册标记或已上演的 npm 包解释为激活成功的证据 .

禁用或卸载保留用户工作空间 `.excalidraw` 文档和回收数据。 未保存的检查站和浏览器备份是恢复辅助工具,而不是对明确保存的工作空间文件的替换. 在升级前保存重要的图纸 。 失败的保存或生命周期确认必须浮出水面,而不是被刷新或强制覆盖所绕过.

第一个出版后文档补丁只修改了这些指令;它并不声称有新的编辑功能. 发布接受应该通过相容的主机安装两个实际npm版本并验证相相容的/即时更新行为,保存绘图数据并保留主机/会场身份. 仅凭地方档案装置并不能证明公共登记的最新情况.

## 构建和核查

使用节点24从这个包中运行(带有变换型支持的节点22也用于测试). 构建依赖性和浏览器的测试依赖性被明确固定在 package.json. React/ReactDOM,编辑码,懒散块,地块,CSS,字体和通知被运入内部 `dist`; 存在着 **没有安装运行时间依赖关系**。 。 。 .

```sh
node scripts/build.mjs
node --experimental-transform-types --test test/*.test.ts test/*.test.mjs
../../node_modules/.bin/tsc --noEmit
node test/frame.browser.mjs
node scripts/independent-build.mjs
node scripts/verify.mjs
node test/csp.browser.mjs
```

`independent-build` 复制已解析、版本检查的构建包关闭(保留嵌入版本)到 `../../artifacts/independent-build`,重建那里,检查每一个重建输入 realpath 仍然留在目录。 它不安装软件包或联系登记处. `verify` 用途 `pnpm pack`,验证每个资源摘要/大小和每个显示的条目,将精确的归档提取到固定节点模块并导入/运行其后端。 未进行 npm 安装/ 发布 。 新的注册系统安装/冻结工作空间锁文件更新不属于这种离线核查的一部分.

## 生产CSP字体政策

Excalidraw 0.18: 完整的原 WOFF2 unicode-range 分区被嵌入而不用运行 JS/WASM glyph 子集. 这保持了甘油质量和原生出口,但增加了SVG的尺寸;一个控制台信息信息使政策明确. 字体 URL 适配器去除上游 CDN回落,需要本地资产路径. 依赖设施或主机CSP均不作修改;否 `unsafe-eval` 或者说 `wasm-unsafe-eval` 需要时间。 上游漂流失败 建设审查.

`test:csp` 提取真实 `verify` tgz,检查每个表文摘要,为HTTP上的资源提供精确的制作主机-资产CSP,并练习了中文工具缩略图和本地编辑PNG/源代码下载. 它宣称字节-精确嵌入分区,浏览器字体解码,以及零页出错,CSP违规,控制台出错或外部请求. 源存储器的 `packages/excalidraw/CSP-VERIFICATION.md` 记录核查和限制(也与开发文物分开提供).

## 东道国合并合同

-   以套件名称识别此插件 。 特征是 `package.json.piWebapp`; API 2, 运行时协议 1, schema 1. 资源路径相对于软件包,包括 `./dist/`。 。 。 . `resources.json` 列出除自己之外所有已发送的文件;主机必须检查其信任的档案/包出处。 不披露任意的软件包目录 .
-   导入 `dist/runtime.js`电话 `createRuntime(ctx)`。 。 。 . `describe` 返回六个工具描述符及其 `action`; 工具和 UI 动作都输入 `invoke`. 主机用品经认证的范围和生成,使经纪人进入 **援引**,并序列化/栅栏生成变化。 不相信iframe 提供的会话/ cwd .
-   一个Schema-1 `checkpoint` 每个插件/ 工作空间/ 会话存储器的状态记录 `{drafts, focused}`. 存储修订和域修订草案是独立的. 新状态使用预期 修订 0; 第1回修改为 1. 每个引用重装状态; 写入 CAS 不自动重写 。 范围从未被编码入 ASCII 密钥 .
-   `legacy.read {}` 返回旧范围 `{drafts, focused}` 或无效。 主机解决遗留插件 ID `@pi-webapp/diagrams`,读取旧的草稿信封/焦点,并返回范围检查点。 插件在 CAS 导入前验证所有数据; 保留旧文件不动 。 无效的数据是一个错误,绝不是空状态重置 .
-   工作空间经纪人处理路径封隔/连锁防御,边框文本读取,散开,锁接,不取而代之的创建和生成的栅栏紧接在犯罪前. 插件只允许相对 `.excalidraw` 路径和发送 `expectedHash: null` 用于保存/新建文件。 它从不重复冲突 覆盖.
-   成功的工作空间承诺以及失败的状态 CAS 可以离开已执行的文件,但其检查点没有更新 。 错误被浮出水面;不要默默地重试保存或撤回索赔。 主机的散列/封列仍然具有权威性;检查/重新打开文件进行调节.
-   可选域错误序列化 `error.status` 财务报告和审定财务报表 `error.reason` 在RPC回复中(此处引入补充协议字段). `409` (一) 需要为陈旧的候选人/初始化处理; `404` + 键 `diagram_unavailable` 保持备份并停止投票. `code`编号 :`message` 保持不变并兼容.

## 框架协议

前端显示的条目都指向 `dist/frame.html`. 供应 URL 参数 `parentOrigin`, (中文(简体) ), `pluginId`, (中文(简体) ), `generation`, (中文(简体) ), `mountId`发送 `{type:'pi:hosted:connect', protocol:1, pluginId, generation, mountId}` 和一个信件端口 **来源/窗口**。错误的身份/生成/来源/来源被忽略;只有一个连接被接受。 这是域/生命周期隔离,而不是敌对的密码沙盒.

主机 RPC 方法 : `describe`, (中文(简体) ), `initialize(HostedViewMount)`, (中文(简体) ), `update`, (中文(简体) ), `flush`, (中文(简体) ), `freeze`, (中文(简体) ), `restore`, (中文(简体) ), `dispose`。会话约束在初始化后不能更改。 工具更新为 `{call:{text}, result:{blocks,isError?}, running}`; 部分参数字符串保留流缩略图。 UI 调用主机 `action {action,input}`, (中文(简体) ), `openPanel {kind,contentId,title}`,以及 `changed {dirty,busy}`; RPC 运输也支持 `sendMessage` 财务报告和审定财务报表 `abort` 没有打开另一个作曲家.

平整出每个挂起的帧而不只是控制器:每个iframe拥有自己的React/模型域. Flush 同步每个可用的脏模型,并在组成,指针交互,本土文本/多块编辑,再大小,旋转或突变时拒绝成功. 冻结返回 `{mount, undoClearedOnReopen:true}` 冲洗后; 仅恢复接受同一会话。 持续的状态和明确的浏览器备份恢复内容, **非本地撤消历史**。主机在默认情况下应该等待编辑器关闭;立即重新打开必须显示一个已取消的历史清除警告。 不要将 RPC 超时视为成功的冲出/ 冻结 .

原生菜单保留了导入/本地保存/出品/PNG,中文地块,背景/主题,组和编辑. 工作空间 Ctrl/Cmd-S 仍为单独的散列保护. 现有候选人需要明确接受/拒绝,手编辑使旧候选人无效,新的未被触及的场景只初始化一次. 原始缩略图和本地备份保留到替换/回收决定。 撤销卸载 React,取消模型定时器/预览订阅/下載 URL,并回复后关闭端口.

## 未完成的一体化接受

真正的主机启用/失效/开关/重开/热上等,经过认证的经纪人范围跨真正的主机进程隔离,磁盘-锁/同声/fincing种族行为,旧的盘上信封集合,以及实际的最终用户警告UX仍然是母机集成的责任. 测试使用真正的跨原生iframe和原生编辑器,并配有内存主机经纪人固定. 这里的浏览器覆盖不能取代主机端到端套件或详尽的PNG/菜单回归检查.

## 常见问题

### @chengzhiyi/pi-excalidraw 是什么？

自定义主机 v2 用于 pi- webapp 的 Excalidraw 插件

### 如何安装 @chengzhiyi/pi-excalidraw？

在项目目录运行 npm install @chengzhiyi/pi-excalidraw，或使用 pnpm add / yarn add / bun add。

### @chengzhiyi/pi-excalidraw 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chengzhiyi\_\_pi-excalidraw 是否存在。

### @chengzhiyi/pi-excalidraw 支持 ESM 还是 CommonJS？

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

### @chengzhiyi/pi-excalidraw 可以商用吗？

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

### @chengzhiyi/pi-excalidraw 的下载量有多少？

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

### @chengzhiyi/pi-excalidraw 还在维护吗？

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