# @alwith/module-editor 中文文档

规范地址：https://npmcn.com/package/%40alwith/module-editor/

版本：0\.6\.1
npm 元数据更新时间：2026-11-04T03:23:58.609Z
中文译文更新时间：2026-11-06T18:53:57.972Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40alwith/module-editor
原文对照：https://npmcn.com/package/%40alwith/module-editor/?lang=original
项目主页：https://github.com/ALwith-ai/alwith-modules#readme
源码仓库：https://github.com/ALwith-ai/alwith-modules

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

- 包体积（解压后）：3.4 MB，287 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：utif ^3\.1\.0，xlsx ^0\.20\.3，katex ^0\.19\.1，react ^19\.3\.1，shiki ^4\.5\.0，dompurify ^3\.4\.17，react-dom ^19\.3\.1，pdfjs-dist ^6\.4\.299，docx-preview ^0\.4\.1，lucide-react ^1\.61\.0，react-player ^3\.4\.0，monaco-editor ^0\.57\.0，@milkdown/core ^7\.22\.2，@milkdown/prose ^7\.22\.2，@milkdown/utils ^7\.22\.2，@tauri-apps/api ^3\.0\.0-alpha\.3，x-data-spreadsheet ^1\.1\.9，@alwith/module-chat ^0\.6\.0，@milkdown/preset-gfm ^7\.22\.2，audiomotion-analyzer ^4\.5\.4，@milkdown/plugin-math ^7\.5\.9，@milkdown/plugin-history ^7\.22\.2，@milkdown/preset-commonmark ^7\.22\.2
- 首次发布：2026-10-22T10:35:24.160Z
- 最新版本发布：2026-11-04T03:23:58.263Z
- 近 30 天下载量：2453（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

文档状态、保存、标签和可扩展预览。 软件包不依赖于文件树包,会话商店或Tauri.

## 安装

```sh
npm install @alwith/module-editor
```

也可以使用：`pnpm add @alwith/module-editor`、`yarn add @alwith/module-editor`、`bun add @alwith/module-editor`

## README

# @ alwis/模块编辑器

文档状态、保存、标签和可扩展预览。 软件包不依赖于文件树包,会话商店或Tauri.

```tsx
import { createEditorController, EditorWorkbench, imagePreview } from "@alwith/module-editor"
import "@alwith/module-editor/styles.css"
const editor = createEditorController({ fs, confirmClose, reportError })
await editor.open("/project/readme.md")
<EditorWorkbench controller={editor} previews={[imagePreview]}
  onError={reportError} />
```

## 生命周期和安全

稳定文档ID在路径变化后幸存. 一个FS实例序列化保存,移动,删除,关闭并重新加载. 目录移动重置后人路径 。 当确认返回被取消时, 脏文件否决删除 。 批准删除时会暂时锁定他们的文档,直到本地操作完成或失败为止. 自定义引擎必须尊重 `readOnly`。失败保存会保持肮脏状态;磁盘版本的不匹配永远不会默默地覆盖磁盘。 当保存/重载等待时, I/O 无法静默关闭或替换更新的编辑 .

打电话 `requestClose(id)` 关闭标签并 `prepareShutdown()` 在离开工作空间/应用程序之前。 二者能还假相. `dispose()` 只发布订阅;它不以用户的名义询问、保存或丢弃。 如果需要,主机负责崩溃恢复/草稿持久性;此发布在切换项目时保留了内存中的草稿,而不是跨进程崩溃.

UTF-8和BOM标记的UTF-16 LE/BE严格解码. 无效的字节仍然是二进制/只读 。 保存保留BOM和一文档的新行会. 文本不是从错误的字节来猜测的 。 默认文件大小限制为 16 MiB; 通过 `maxFileBytes` 对于支持不同限制的适配器。 清洁文件有LRU限制(默认为12);脏文件不会被逐出.

`saveAs` 使用只创建写入 。 主机获得一个目的地并允许访问;它决不能假定任意路径是可写入的. `onOpenExternal` 是需要其他应用程序格式的主机动作.

## 制作和扩展

`/core` 包含没有反应。 根导出 `EditorWorkbench`, (中文(简体) ), `PreviewProvider`, (中文(简体) ), `TextEditorProps` 财务报告和审定财务报表 `imagePreview`。预览是命令的:第一个提供商 `supports(document)` 返回为真实,使文档成为真实。 文本文件可以在编辑和预览之间切换. SVG/HTML不是由内置图像预览执行. HTML/PDF/office/media services属于具有所需要沙盒和资源处理功能的明确可选提供者;不支持的二进制不解码为可编辑文本.

默认文本渲染器是一个文本区域. `/monaco` 出口 `createMonacoEngine(monaco, controller)`: 摩纳哥是一个可选的对等点,从未被默认条目加载. 东道主进口摩纳哥懒散并配置工人。 引擎通过文档ID保留了撤销/模型并查看状态,释放了已关闭的模型并提供 `dispose`。主机提供轻/暗主题。 U使用摩纳哥来进行代码/Markdown编辑并注入其共享的Markdown渲染器进行预览.

所有工具栏文字均由 `EditorLabels`;主题颜色使用语义CSS变量. 主机可能提供 `renderTextEditor`, (中文(简体) ), `requestSaveAs`, (中文(简体) ), `onOpenExternal`,并任意预览提供者。 业务 HTML/Drive/账户/会话集成留在主机.

见 `examples/files/editor-only.tsx` 财务报告和审定财务报表 `combined.tsx` 为独立和有组成的消费者服务.

`compactToolbar` 保持文件路径可见并移动编辑器动作到 溢出菜单; `actionsLabel` 将其触发器本地化。 默认工具栏仍然保留 其他主机不变. 标签接受音轨板和以隐藏方式滚动的轮盘 滚动条; 激活文档使其标签查看 。 预览滚动条 使用基于主机前缘符的薄而低相通的拇指.

## 可选本地预览

`@alwith/module-editor/previews` 出口 `createPreviewProviders(host)`。将此条目懒易地装入并导入 `@alwith/module-editor/previews/styles.css` 与工作台样式表并列。 PDF,OOXML Word,电子表格,Markdown,HTML,音频/视频和TIFF解码器在选择提供者时独立加载. 这些可移植取景器从AL With Desktop中被减少;账户,协作和本地文件系统集成仍然留在主机中.

电子表格预览需要SetJS CE0.20.3或兼容的更新型的0.20.x发布. 公众npm `xlsx` 包件留在旧的0.18.5分发上;从 [《日记》正式分发](https://docs.sheetjs.com/docs/getting-started/installation/nodejs/) 并执行软件包管理锁文件 :

```sh
bun add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
```

东道方用品 `pdfWorkerSrc` 财务报告和审定财务报表 `resolveResource(documentPath, reference)`返回时 `{ bytes, mimeType, path }`。对照所提供基准路径解析引用,返回条形资源路径并强制执行主机的文件系统权限. `parseSpreadsheet(bytes, signal)` 可以委托ShetJS为工人解码;通过终止或取消工人名誉取消. `labels` 财务报告和审定财务报表 `imageLabels` 将控件本地化. `openExternal` 处理遗留问题 `.doc`编号 :`.dot` 文件和不支持的媒体编码器.

HTML 使用一个不透明的沙盒,其脚本已启用,没有父访问,导航权限或网络请求. 相对样式表, CSS 资产和文字 JavaScript 导入在渲染前解决. 远程 HTTPS 资产需要明确 `allowRemoteResources: true`;特权计划与平原HTTP仍被封锁. 计算出的资源路径和循环本地脚本依赖无法在渲染前解决. 预览自有对象URL在替换/卸载时发布;资源加载和生成的内容被限制.

Markdown使用桌面的"Milkdown CommunityMark/GFM"预设,并带有大纲和格式化控制. 它通过工作本克的文档上下文同步地发布编辑,从不直接写出文件. 程序替换人员保持其清洁状态。 设定 `autoSaveDelay` 以解析主机的保存动作,或让它未设定为手动保存。 主机仍然对只读状态,脏态,保存失败和外部变化具有权威性.

## 本地电子表格解析

Tauri 插件 `alwith-editor` (crates.io) 接受主机授权的文件 字节并转发到私有本地编辑器库, 此库中载有 软件包下 `native/<os>-<cpu>/`。在构建时与 `stageNativeModule` 从 `@alwith/module-desktop-shell/stage`,以 `.plugin(alwith_editor::init(Config { development_directory }))`, (中文(简体) ), 赠款 `alwith-editor:default`,然后通过 `@alwith/module-editor/commands`. 钙 和解析器执行被载入本地图书馆;没有额外的进程 介绍.

`parse_spreadsheet(bytes, extension)` 返回带有绝对单元格的已键入的工作表 坐标,去迭代样式,合并单元格,数字值和日期时代. 桌面和 U 使用相同的解析器 。 XLSX 样式包括字体,颜色,填充, 边框、对齐和数字格式代码。 其他格式使用可获取的卡胺 元数据; CSV 仍然是文本。 输入上限为 16 MiB; 预览限制为 2 000 行和200栏及工作表报告 `truncated` 当超过。 他们的分页明显显示一个部分 预览及其限制.

`/spreadsheet` 输出共享 `SpreadsheetView` 财务报告和审定财务报表 `workbookSheets` 适配器. 数字格式使用SeetJS SSF(包括1904年的epoch),而不是自定义物质. 帆布渲染器支持左/中/右和上/中/下对齐; 不支持的对齐报告错误, 而不是默默地放弃格式 . 图案填充、对角边框、文本旋转、有条件的格式和正本 本渲染器不复制行/列尺寸. 隐藏边框子类型 使用渲染器的虚线;这是只读取的预览,而不是像素-等同的Excel.

## 常见问题

### @alwith/module-editor 是什么？

文档状态、保存、标签和可扩展预览。 软件包不依赖于文件树包,会话商店或Tauri\.

### 如何安装 @alwith/module-editor？

在项目目录运行 npm install @alwith/module-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.3\.1）、react-dom（^19\.3\.1）、lucide-react（^1\.61\.0）、@tauri-apps/api（^3\.0\.0-alpha\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alwith/module-editor 支持 TypeScript 吗？

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

### @alwith/module-editor 支持 ESM 还是 CommonJS？

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

### @alwith/module-editor 可以商用吗？

@alwith/module-editor 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @alwith/module-editor 的下载量有多少？

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

### @alwith/module-editor 还在维护吗？

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