Docs

word-editor 文档

从 Web Component 接入、API 命令、事件订阅、字体网关、授权门禁到 Cloudflare Pages 发布，覆盖生产集成路径。

Markdown API 适合仓库内审阅和版本 diff Deployment 发布流程和 Cloudflare Pages 约束 Licensing 授权文件、域名和运行时门禁

快速开始

构建后导入浏览器运行时，页面中放置 <word-editor>，再调用 load() 或 loadBlank()。元素需要连接到 DOM 后再调用方法。

<word-editor id="editor" mode="edit" zoom="1"></word-editor>

<script type="module">
  import "/packages/word-editor/dist/index.js";

  const editor = document.querySelector("#editor");
  editor.addEventListener("ready", () => console.log("ready"));
  editor.addEventListener("changed", (event) => {
    console.log("dirty", event.detail.dirty);
  });

  await editor.load(file, file.name);
  await editor.exec("fontName", "Aptos");
  const output = await editor.save();
</script>

API Reference

Element

word-editor 是原生 Custom Element。默认包入口会自动注册，也可以从模块中手动调用 defineWordEditorElement(tagName)。

Attribute	Values	Default	说明
`mode`	`edit`, `view`	`edit`	编辑或只读查看模式，可通过 `setMode()` 同步。
`engine`	`ts`	`ts`	当前生产引擎为纯 TypeScript DOCX runtime。
`zoom`	正数	`1`	页面缩放比例，可通过 `setZoom()` 更新。
`auto-font-gateway`	boolean attribute	off	启用后台字体网关加载，不阻塞首屏文档呈现。
`font-gateway-url`	URL	默认网关	字体 manifest 地址；当前可配置为 `https://font.flyfish.group/manifest.json`。
`font-gateway-limit`	正整数	默认限制	自动加载字体数量上限，用于控制网络和内存预算。
`license-required`	boolean attribute	off	启用授权门禁；生产环境建议开启。
`license-feature`	string	runtime 默认	授权校验使用的功能名。

Methods

load(input, name?)加载 File、Blob 或 ArrayBuffer 类型的 DOCX。

loadBlank(name?)创建空白文档，默认文件名为 document.docx。

save()导出当前文档为 DOCX Blob，并触发 saved 事件。

exec(command, value?)执行 ribbon/API 命令，例如 bold、fontName、toggleRuler。

insertTable(rows?, columns?)在当前选区插入表格。

insertImage(input, options?)插入图片，支持 alt、mimeType 和最大宽度。

registerFont(font)注册单个字体源。

registerFonts(fonts)批量注册字体源。

importFont(input, options?)导入字体文件，可写入持久字体仓库。

loadFontGatewayFonts(options?)按 manifest 后台加载字体网关字体。

loadRepositoryFonts(manifestUrl?, persist?, options?)从自定义字体仓库加载字体。

listPersistedFonts()列出浏览器端已持久化字体。

clearPersistedFonts()清理浏览器端字体缓存。

setMode(mode)切换 edit 或 view。

setZoom(value)设置缩放比例。

reflowPages()请求重新分页和布局。

getRuntimeStatus()读取运行时状态、页数、字体、dirty 状态和布局信息。

destroy()销毁引擎并清空挂载点。

命令

命令由 exec(command, value?) 统一执行。格式类命令会优先作用于当前选区；视图类命令会更新对应 UI 状态。

格式

bold, italic, underline, strikeThrough, fontName, fontSizePt, foreColor, hiliteColor, removeFormat, subscript, superscript

段落与页面

justifyLeft, justifyCenter, justifyRight, justifyFull, insertOrderedList, insertUnorderedList, lineSpacing, setPageSize, setMargins, setOrientation

对象

insertTable, insertShape, insertTextBox, insertWordArt, insertSmartArt, insertChart, insertEquation, insertHyperlink, insertComment

审阅与视图

toggleTrackChanges, acceptRevision, rejectRevision, updateFields, toggleRuler, toggleNavigation, togglePageEnds, toggleGridlines, toggleDarkMode

事件

Event	detail	用途
`ready`	none	编辑器引擎已挂载。
`loaded`	`{ name, engine, pageCount, fonts, persistedFonts }`	文档加载完成，可同步标题、页数和字体状态。
`changed`	`{ dirty }`	内容发生变化或保存后 dirty 状态变化。
`saved`	`{ name, blob }`	保存完成，宿主应用可上传 Blob。
`error`	`{ code, message, detail }`	授权、加载、保存或命令异常。
`word-editor-operation`	operation commit	编辑操作桥接事件，适合审计、协作或回放。
`word-editor-action`	`{ action, ...detail }`	宿主边界动作事件，例如共享、外部服务、插件任务。
`word-editor-semantic-paste`	semantic paste payload	结构化粘贴结果和操作摘要。

字体网关

生产建议开启异步字体加载：先呈现文档，再在后台下载字体和触发布局刷新，避免首屏被字体阻塞。

<word-editor
  auto-font-gateway
  font-gateway-url="https://font.flyfish.group/manifest.json"
  font-gateway-limit="32">
</word-editor>

宿主也可以直接调用 registerFont() 或 loadRepositoryFonts() 控制字体来源、授权和缓存策略。

授权

生产构建包含 office-preview-license.json、授权运行时和 WASM 门禁。启用 license-required 后，元素挂载时会校验授权；失败时触发 error 并显示授权错误面板。

<word-editor
  license-required
  license-feature="word-editor-production">
</word-editor>

部署

当前生产目标为 https://docx-editor.pages.dev。发布脚本会重建 runtime、复制站点、复制授权资产、复制 WASM、写入 Cloudflare 控制文件、生成 release metadata，并对 JavaScript 产物做压缩混淆。

npm run build:cloudflare
npm run deploy:cloudflare

构建产物目录为 cloudflare-pages-dist，根路径是产品主页，/docs/ 是文档站，/examples/demo/ 是在线编辑器 Demo。

生产运维

上线前验证根主页、文档页、Demo、授权文件、WASM MIME、release metadata。
对变更范围执行受影响测试；涉及编辑器 runtime 时再运行浏览器端 smoke 和核心回归。
字体仓库、授权域名和 Cloudflare 项目名应随发布记录一起审计。
宿主应用应处理 changed、saved、error，并在离开页面前处理 dirty 状态。