word-editor 文档

快速开始

构建并导入浏览器运行时，页面中放置 <word-editor>。元素连接到 DOM 后，使用稳定的宿主接口导入 DOCX、监听状态并保存。

<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);
  });
  editor.addEventListener("error", (event) => {
    console.error(event.detail.code, event.detail.message);
  });

  await editor.importDocument(file, { name: file.name });
  editor.insertContent("由业务系统写入", { at: "cursor" });
  const output = await editor.saveDocument();
</script>

生命周期

宿主系统负责文件存储、权限、版本和并发控制；编辑器负责 DOCX 解析、呈现、编辑和序列化。生产接入应遵循同一条生命周期。

1. 挂载把元素连接到 DOM，等待 ready。
2. 导入调用 importDocument() 或 loadBlank()，等待 loaded。
3. 编辑通过 ribbon、exec()、插入 API 或书签 API 修改内容。
4. 跟踪监听 changed，并以 editor.dirty 控制保存和离开页面提示。
5. 保存串行调用 saveDocument()，上传成功后再确认业务版本。
6. 销毁仅在宿主真正卸载编辑器时调用 destroy()。

const editor = document.querySelector("word-editor");
let saving = false;

editor.addEventListener("changed", ({ detail }) => {
  saveButton.disabled = saving || !detail.dirty;
});

async function saveToBusinessSystem(documentId, version) {
  if (saving) return;
  saving = true;
  try {
    const blob = await editor.saveDocument();
    await businessApi.putDocument(documentId, blob, {
      name: editor.documentName,
      version,
    });
  } finally {
    saving = false;
  }
}

导入、保存与导出

稳定宿主接口使用明确的业务名称；旧的 load() 和 save() 保持兼容。

const response = await fetch(`/api/documents/${documentId}`);
if (!response.ok) throw new Error(`open failed: ${response.status}`);

const blob = await response.blob();
await editor.importDocument(blob, {
  name: response.headers.get("x-document-name") || "document.docx",
});

const output = await editor.exportDocument();
await fetch(`/api/documents/${documentId}`, {
  method: "PUT",
  headers: { "Content-Type": output.type },
  body: output,
});

定点插入内容

insertContent(content, options?) 是统一插入管线。当前只接收安全纯文本；不会解析 HTML，换行会转为文档换行。

editor.insertContent("替换当前选区或写入光标处");
editor.insertContent("文档前缀", { at: "document-start" });
editor.insertContent("文档后缀", { at: "document-end" });
editor.insertContent({ type: "text", text: "签署人：王宇" }, {
  at: "bookmark",
  bookmark: "CustomerSignature",
  placement: "start",
});

书签 placement 支持 before、start、end、after，默认是 start。insertText() 与 insertTextAtBookmark() 是兼容快捷方法。

方法返回 boolean。成功接受操作返回 true；只读、受保护文档、书签不存在或当前位置不可编辑时返回 false。

书签管理与位置

书签是文档内稳定锚点，支持点书签、范围书签以及导入文档中的兼容书签。查询结果同时提供逻辑位置和当前渲染位置。

const bookmark = editor.findBookmark("CustomerSignature");
const position = editor.getBookmarkPosition("CustomerSignature");

console.log({
  type: bookmark?.type,             // "point" | "range" | "legacy"
  page: position?.start.page,       // 1-based
  blockIndex: position?.start.blockIndex,
  offsetInBlock: position?.start.offsetInBlock,
  documentOffset: position?.start.documentOffset,
  pageOffset: position?.start.pageOffset,
  viewportRect: position?.start.viewportRect,
});

editor.gotoBookmark("CustomerSignature");

完整 API

Element

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

Methods

Properties

命令

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

事件

TypeScript

构建产物会生成公共声明文件。应用可直接导入元素类和所有宿主 API 类型，不需要自行维护重复接口。

import {
  WordEditorElement,
  type WordEditorBookmarkInfo,
  type WordEditorBookmarkPosition,
  type WordEditorContentInput,
  type WordEditorDocumentExportOptions,
  type WordEditorDocumentImportOptions,
  type WordEditorDocumentInput,
  type WordEditorDocumentPosition,
  type WordEditorInsertContentOptions,
  type WordEditorSaveResult,
} from "@word-editor/word-editor";

const editor = document.querySelector<WordEditorElement>("word-editor");
if (!editor) throw new Error("word-editor is not mounted");

const options: WordEditorInsertContentOptions = {
  at: "bookmark",
  bookmark: "CustomerSignature",
  placement: "start",
};
editor.insertContent("已签署", options);

源码或私有包使用生成的 dist/index.d.ts。官网授权运行时是浏览器交付入口，不提供在线类型解析；项目编译时应依赖同版本私有包或声明产物。

字体网关

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

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

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

错误、安全与授权

错误语义

异步生命周期、导入、保存和运行时失败会抛出异常，并通过 error 事件向宿主报告。编辑类同步方法在操作不可接受时返回 false。

editor.addEventListener("error", ({ detail }) => {
  logEditorError(detail.code, detail.message, detail.detail);
  showDocumentError(detail.message);
});

try {
  await editor.importDocument(input, { name });
} catch (error) {
  showRetryAction(error);
}

if (!editor.insertContent("审批意见")) {
  showToast("当前位置不可编辑或文档为只读模式");
}

宿主安全边界

• 在服务端校验文件类型、文件大小、租户权限和病毒扫描结果；不要只信任浏览器 MIME。
• 内容插入 API 仅接受纯文本，不要把不可信 HTML 直接写入编辑器 DOM。
• 保存期间禁用重复提交；使用业务版本号或 ETag 处理并发覆盖。
• 新 Blob 成功上传并确认版本之前保留原文档，不要把本地序列化等同于远端持久化。
• 离开页面前根据 dirty 提示，并在宿主应用中记录 error 技术细节。

生产授权

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

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

部署

当前生产目标为 https://docx-editor.pages.dev。先签发并提交运行授权，再从该 commit 创建全新的干净 worktree。发布脚本会重建 runtime、复制站点和 Markdown 文档、复制授权资产与 WASM、写入 Cloudflare 控制文件、生成 release metadata，并把同 commit 的对应源码归档一起封装。完整步骤见 Deployment Guide。

# 在已提交发布 SHA 的全新 clean worktree 中
npm ci
npm run build:cloudflare
npm run deploy:cloudflare

生产运维

• 上线前验证根主页、文档页、完整 Demo、集成 Demo、授权文件、WASM MIME 和 release metadata。
• 验证导入、编辑、书签查询、四种插入目标、保存 Blob 和 ArrayBuffer 导出。
• 对变更范围执行受影响测试；涉及编辑器 runtime 时再运行浏览器端 smoke 和核心回归。
• 字体仓库、授权域名和 Cloudflare 项目名应随发布记录一起审计。
• 宿主应用应处理 changed、saved、error，并在离开页面前处理 dirty 状态。
• 监控导入失败率、保存耗时、上传失败、版本冲突和授权错误，不记录文档正文。

详细资料：部署指南 授权指南 测试指南