API Reference

完整 Web Component API

以当前生成的 TypeScript 声明为准，逐项说明 <word-editor> 的属性、方法参数、默认值、返回值、事件和命令。业务集成优先使用 importDocument()、insertContent()、书签 API、saveDocument() 与 exportDocument()。

注册与构造

`defineWordEditorElement(tagName?)`

defineWordEditorElement(tagName?: string): void

参数	类型	默认值	说明
`tagName`	`string`	`"word-editor"`	合法的自定义元素名称，必须包含连字符。

`new WordEditorElement(options?)`

程序化创建编辑器。创建后必须连接到 DOM，才可以调用依赖引擎的方法。

constructor(options?: WordEditorOptions)

`options` 字段	类型	默认值	说明
`mode`	`"edit" \| "view"`	`"edit"`	编辑或只读查看模式。
`engine`	`"ts"`	`"ts"`	文档引擎。当前只支持纯 TypeScript 引擎。
`locale`	`string`	`undefined`	保留的本地化配置；当前构造器不投影该字段。
`readonly`	`boolean`	`undefined`	保留字段；当前运行时请使用 `mode: "view"` 或 `setMode("view")`。
`zoom`	`number`	`1`	正数缩放比例。无效值读取时回退为 1。
`fonts`	`WordEditorFontSource[]`	`[]`	引擎挂载后立即注册的字体源。
`fontGateway`	`WordEditorFontGatewayAutoOptions \| false`	`undefined`	字体网关配置；传 `false` 明确禁用。

`connectedCallback()`

浏览器生命周期回调。元素连接到 DOM 时自动挂载引擎；宿主不要手动调用。

`disconnectedCallback()`

浏览器生命周期回调。元素移出 DOM 时自动销毁当前引擎；宿主不要手动调用。

`attributeChangedCallback(name, oldValue, newValue)`

浏览器生命周期回调。观察属性变化时自动同步模式、缩放、字体网关和授权状态。

参数	类型	说明
`name`	`string`	发生变化的观察属性名。
`oldValue`	`string \| null`	变化前的属性值。
`newValue`	`string \| null`	变化后的属性值。

Element Attributes

Attribute	值	默认值	说明
`mode`	`edit \| view`	`edit`	切换编辑和只读模式，与 `setMode()` 同步。
`engine`	`ts`	`ts`	选择引擎。改变该属性会重新挂载引擎。
`zoom`	正数文本	`1`	页面缩放比例，与 `setZoom()` 同步。
`auto-font-gateway`	boolean attribute	关闭	文档可用后自动在后台加载字体网关。
`font-gateway-url`	URL	`https://font.flyfish.group/manifest.json`	启用自动网关时使用的字体 manifest。
`font-gateway-limit`	正整数	`48`	一次自动加载的字体数量上限。
`license-required`	boolean attribute	关闭	挂载引擎前要求有效运行授权。
`license-feature`	`string`	运行时默认功能名	授权校验使用的功能标识。

只读 Properties

Property	类型	说明
`dirty`	`boolean`	当前文档是否存在尚未序列化的修改。
`documentName`	`string \| undefined`	当前文档名称；尚未加载文档时为 `undefined`。
`mode`	`"edit" \| "view"`	当前模式。
`engineKind`	`"ts"`	当前引擎类型。
`zoom`	`number`	当前正数缩放比例；属性值无效时返回 1。

文档导入、保存与导出

`importDocument(input, options?)`

Promise<void>

推荐的统一 DOCX 导入入口。成功后触发 loaded，并把 dirty 重置为 false。

参数	类型	默认值	说明
`input`	`File \| Blob \| ArrayBuffer \| Uint8Array`	必填	完整 DOCX 二进制。`Uint8Array` 会复制为独立 ArrayBuffer。
`options`	`WordEditorDocumentImportOptions \| string`	`{}`	对象形式为推荐接口；字符串形式兼容旧的文件名传参。
`options.name`	`string`	输入文件名或引擎默认名	界面显示及后续保存使用的 DOCX 名称。

`load(input, name?)`

Promise<void>

兼容加载入口。新宿主优先使用 importDocument()。

参数	类型	默认值	说明
`input`	`File \| Blob \| ArrayBuffer`	必填	DOCX 数据。
`name`	`string`	输入文件名或引擎默认名	文档显示名称。

`loadBlank(name?)`

Promise<void>

创建空白 DOCX。

参数	类型	默认值	说明
`name`	`string`	`"document.docx"`	新文档名称。

`saveDocument()`

Promise<Blob>

推荐保存入口。序列化当前 DOCX，返回 MIME 为 DOCX 的 Blob，并触发 saved。

`save()`

Promise<Blob>

saveDocument() 的兼容底层入口。

`exportDocument(options?)`

Promise<Blob | ArrayBuffer>

参数	类型	默认值	说明
`options.output`	`"blob" \| "array-buffer"`	`"blob"`	决定返回 Blob，或返回适合二进制传输的 ArrayBuffer。TypeScript 会根据字面量推导返回类型。

内容、表格与图片

`insertContent(content, options?)`

boolean

统一安全纯文本插入入口。不会解析 HTML，换行会转换为文档换行。

参数	类型	默认值	说明
`content`	`string \| { type: "text"; text: string }`	必填	要插入的纯文本内容。
`options.at`	`"cursor" \| "document-start" \| "document-end" \| "bookmark"`	`"cursor"`	插入目标。cursor 会替换当前选区或写入光标处。
`options.bookmark`	`string`	无	`at: "bookmark"` 时必填；接受书签名称或 OOXML ID。
`options.placement`	`"before" \| "start" \| "end" \| "after"`	`"start"`	使用哪个书签边界插入。

操作被接受返回 true；只读、受保护、书签不存在或位置不可编辑时返回 false。

`insertText(text)`

boolean

参数	类型	说明
`text`	`string`	在当前光标插入或替换当前选区的纯文本。

`insertTable(rows?, columns?)`

Promise<void>

参数	类型	默认值	有效范围	说明
`rows`	`number`	`2`	1 至 20，取整并钳制	表格行数。
`columns`	`number`	`2`	1 至 12，取整并钳制	表格列数。

`insertImage(input, options?)`

Promise<void>

参数	类型	默认值	说明
`input`	`File \| Blob \| ArrayBuffer`	必填	图片二进制。
`options.name`	`string`	输入文件名	图片资源名称。
`options.mimeType`	`string`	输入 MIME 或自动推断	如 `image/png`。
`options.alt`	`string`	空	图片替代文本。
`options.maxWidthPx`	`number`	按页面可用宽度	显示宽度上限，单位 CSS px。

`exec(command, value?)`

Promise<void>

参数	类型	默认值	说明
`command`	`WordEditorCommand \| string`	必填	命令名称。完整内置命令见本页命令表。
`value`	`string`	`undefined`	命令的可选值；格式和支持值取决于命令。

书签方法

`listBookmarks()`

WordEditorBookmarkInfo[]

返回全部点、范围和兼容书签，包含当前逻辑与视觉位置。

`hasBookmark(name)`

boolean

name: string 为书签名称或 OOXML ID；存在返回 true。

`findBookmark(name)`

WordEditorBookmarkInfo | undefined

name: string 为书签名称或 OOXML ID；不存在返回 undefined。

`getBookmarkPosition(name)`

WordEditorBookmarkPosition | undefined

name: string 为书签名称或 ID。每次调用重新计算 start/end；缩放、编辑或分页后应重新查询。

`gotoBookmark(name)`

boolean

name: string 为书签名称或 ID。滚动并选择书签成功时返回 true。

`addBookmark(name?)`

string | undefined

name?: string 是期望名称；省略时自动生成，重名时生成唯一名称。成功返回最终名称，当前位置不可用时返回 undefined。

`deleteBookmark(name)`

boolean

name: string 为名称或 ID。只删除书签标记，不删除内容；成功返回 true。

`insertTextAtBookmark(name, text)`

boolean

参数	类型	说明
`name`	`string`	书签名称或 OOXML ID。
`text`	`string`	在书签 start 边界插入的纯文本。

字体注册与字体网关

`registerFont(font)`

Promise<void>

font: WordEditorFontSource。注册单个字体源，字段见公共类型。

`registerFonts(fonts)`

Promise<void>

fonts: WordEditorFontSource[]。按数组批量注册字体。

`importFont(input, options?)`

Promise<WordEditorFontSource>

参数	类型	默认值	说明
`input`	`File \| Blob \| ArrayBuffer`	必填	字体二进制。
`options.family`	`string`	从文件名推断	字体族名称。
`options.fileName`	`string`	输入文件名	持久化记录中的文件名。
`options.weight`	`string`	字体记录默认值	CSS FontFace weight。
`options.style`	`string`	字体记录默认值	CSS FontFace style。
`options.license`	`string`	`"user-provided"`	宿主提供的来源或授权元数据。

`loadPersistedFonts()`

Promise<WordEditorFontSource[]>

读取浏览器字体仓库并安装可用字体，无参数。

`listPersistedFonts()`

Promise<Array<{ id; family; fileName; license? }>>

列出持久化字体元数据，不返回字体二进制。

`clearPersistedFonts()`

Promise<void>

清空浏览器端持久化字体记录，无参数。

`loadRepositoryFonts(manifestUrl?, persist?, options?)`

Promise<WordEditorFontSource[]>

参数	类型	默认值	说明
`manifestUrl`	`string`	`../../assets/fonts/local-fonts.json`	字体 manifest URL。
`persist`	`boolean`	`true`	是否保存到浏览器字体仓库。
`options.families`	`Iterable<string>`	全部	只加载指定字体族。
`options.limit`	`number`	仓库默认	最大加载数量。

`loadFontGatewayFonts(options?)`

Promise<WordEditorFontSource[]>

`options` 字段	类型	默认值	说明
`manifestUrl`	`string`	`https://font.flyfish.group/manifest.json`	字体 manifest URL。
`families`	`Iterable<string>`	全部	指定字体族过滤器。
`limit`	`number`	`96`	手动调用时的最大加载数量；自动网关默认上限为 48。
`persist`	`boolean`	`false`	是否持久化。
`background`	`boolean`	`false`	是否按后台加载策略执行。
`awaitFontFaces`	`boolean`	等于 `background`	后台手动加载默认等待 FontFace；首屏自动网关会显式设为 false。

模式、缩放与运行时

`setMode(mode)`

mode: "edit" | "view"。同步元素属性与引擎模式，返回 void。

`setEngine(engine)`

engine: "ts"。设置引擎属性并重新挂载，返回 void。

`setZoom(value)`

value: number 为正数缩放比例，例如 1、1.1、1.25。同步属性与页面布局，返回 void。

`reflowPages()`

请求按当前页面、字体和视口状态重新分页，无参数，返回 void。

`getRuntimeStatus()`

Promise<WordEditorRuntimeStatus | undefined>

返回引擎、文档、页数、字体、布局、修订、历史和创作状态快照，无参数。

`destroy()`

销毁引擎并清空组件挂载点，无参数。重新使用时应重新挂载元素或触发引擎创建。

事件

事件通过 addEventListener() 订阅。内部协作事件使用 bubbles: true 和 composed: true 穿过 Shadow DOM。

事件	`event.detail`	触发时机
`ready`	无	编辑引擎挂载完成。
`loaded`	`WordEditorLoadResult`	文档加载或空白文档创建完成。
`changed`	`{ dirty: boolean }`	文档修改状态变化，包括保存后重置。
`saved`	`WordEditorSaveResult`	DOCX 序列化完成；不代表业务服务器已保存。
`error`	`WordEditorErrorDetail`	授权、加载、保存、命令或运行时失败。
`word-editor-operation`	operation commit	编辑操作提交，可用于审计或协作。
`word-editor-action`	`{ action: string; ...detail }`	共享、插件或外部流程等宿主动作。
`word-editor-semantic-paste`	semantic paste payload	结构化粘贴完成。

`exec()` 命令与 value

接受 `value` 的常用命令

命令	`value` 格式	省略时
`fontName`	字体族，如 `Aptos`	`Calibri`
`fontSize`	CSS font-size 字符串	由当前格式决定
`fontSizePt`	正数字符串，单位 pt	11
`foreColor`	CSS 颜色	`#111827`
`hiliteColor`	CSS 颜色	`#fff59d`
`formatBlock`	`p \| h1 \| h2 \| h3` 等块样式	`p`
`find`	搜索文本	搜索框当前值
`replace` / `replaceAll`	替换文本	替换框当前值
`setPageSize`	`a4 \| letter \| legal`	`a4`
`setMargins`	`normal \| narrow \| wide`	`normal`
`setOrientation`	`portrait \| landscape`	在纵向与横向间切换
`insertTable`	`ROWSxCOLUMNS`，如 `3x4`	`2x3`
`insertTableRow` / `insertTableColumn`	`before \| after`	`after`
`insertShape`	`rect \| roundRect \| ellipse \| triangle \| diamond \| rightArrow \| line`	`roundRect`
`insertHyperlink`	初始 URL	打开空链接对话框
`insertComment`	初始批注文本	打开空批注对话框
`insertFootnote` / `insertEndnote`	注释文本	创建空注释
`insertCitation` / `insertBibliography` / `insertCaption` / `insertCrossReference` / `insertBookmark`	对应内容或标识	由命令对话框或内部默认值决定
`insertOnlineVideo`	视频 URL	打开输入流程
`insertEquation` / `insertFraction` / `insertRadical` / `insertScript` / `insertIntegral` / `insertMatrix`	公式内容或结构初始值	插入默认结构
`insertWordArt` / `insertSmartArt` / `insertChart`	样式、布局或图表类型	使用内置默认值
`showNotes`	`footnote \| endnote`	显示可用注释
`toggleShading`	CSS 颜色	切换默认底纹

不需要 `value` 的内置命令

历史与格式

bold, italic, underline, strikeThrough, undo, redo, removeFormat, increaseFont, decreaseFont, subscript, superscript, textEffects

段落与列表

justifyLeft, justifyCenter, justifyRight, justifyFull, insertUnorderedList, insertOrderedList, multilevelList, toggleChecklist, increaseIndent, decreaseIndent, setTextDirectionLtr, setTextDirectionRtl, toggleFormattingMarks, sortParagraphs, lineSpacing, toggleBorders

页面与视图

pageBreak, toggleNavigation, toggleRuler, togglePageEnds, toggleGridlines, toggleSnapToGrid, toggleColumns, toggleLineNumbers, togglePageBorder, togglePageColor, toggleDarkMode

表格

deleteTableRow, deleteTableColumn, mergeCellRight, splitCell, sortTableAscending, sortTableDescending, autoFitTable, distributeTableRows, distributeTableColumns

对象与引用

insertTextBox, insertInkStroke, insertToc, deleteToc, insertTableOfFigures, insertPageNumber, insertSymbol, insertEmoji, updateFields

审阅

toggleTrackChanges, toggleHeaderFooterEditing, acceptRevision, rejectRevision, acceptAllRevisions, rejectAllRevisions, previousComment, nextComment, previousRevision, nextRevision, deleteComment, toggleMarkupView, toggleRevisionFilter

公共 TypeScript 类型

`WordEditorFontSource`

字段	类型	必填	说明
`family`	`string`	是	字体族名称。
`src` / `source`	`string`	二选一或使用 blob	CSS FontFace source，如 url(...) 或 local(...); source 是别名。
`blob`	`Blob \| ArrayBuffer`	否	宿主提供的字体二进制。
`descriptors`	`FontFaceDescriptors`	否	浏览器 FontFace 描述符。
`weight` / `style`	`string`	否	字体粗细和样式。
`display`	`auto \| block \| swap \| fallback \| optional`	否	字体显示策略。
`license`	`string`	否	来源或授权元数据。
`fileName` / `id`	`string`	否	文件和持久化记录标识。
`persisted` / `persist`	`boolean`	否	当前持久化状态或持久化请求。

`WordEditorBookmarkInfo` 与位置

字段	类型	说明
`name` / `id`	`string`	书签名称与 OOXML ID。
`hidden`	`boolean`	是否为隐藏书签。
`type`	`point \| range \| legacy`	点、范围或兼容书签。
`text`	`string`	当前书签范围文本。
`page`	`number`	从 1 开始的当前页码。
`position.start` / `position.end`	`WordEditorDocumentPosition`	起点与终点位置。
`story`	`"body"`	当前位置 API 作用于正文 story。
`blockIndex`	`number`	从 0 开始的正文块索引。
`blockId`	`string \| undefined`	可用时返回稳定块标识。
`offsetInBlock`	`number`	从 0 开始的块内 UTF-16 偏移。
`documentOffset`	`number`	从 0 开始的正文 UTF-16 偏移，不含页眉页脚。
`pageOffset`	`{ x; y } \| undefined`	相对渲染页的 CSS px 坐标。
`viewportRect`	`WordEditorViewportRect \| undefined`	查询时相对浏览器视口的 x/y/width/height/top/right/bottom/left。

结果与状态类型

类型	字段
`WordEditorLoadResult`	`name`, `engine`, 可选 `pageCount`, `fonts`, `persistedFonts`, `fontFallbacks`, `fontCoverage`, `specCoverage`
`WordEditorSaveResult`	`name: string`, `blob: Blob`
`WordEditorErrorDetail`	`code: string`, `message: string`, `detail?: unknown`
`WordEditorRuntimeStatus`	`engine`, `implementation`, `wasmRequired`, 可选 ready/dirty/documentName/pageCount/fonts/fontCoverage/specCoverage/compatibilityProfile/layout/trackChangesEnabled/history/authoring，以及扩展字段。

错误与返回约定

元素必须先连接到 DOM；否则依赖引擎的方法会抛出错误。
importDocument()、保存、字体与异步命令失败时 Promise reject，并可能触发 error。
insertContent()、书签修改和导航方法使用 boolean 或 undefined 表达不可执行，不把正常业务拒绝当异常。
saved 只表示 DOCX 序列化完成；远端上传、权限和版本冲突由宿主处理。
pageOffset 与 viewportRect 是瞬时视觉坐标，布局变化后必须重新查询。

权威来源

签名以包内 dist/index.d.ts 与 dist/element/WordEditorElement.d.ts 为准。本文档的回归测试会检查公开方法、命令联合类型和关键参数，防止页面落后于代码。

完整 Web Component API

注册与构造

defineWordEditorElement(tagName?)

new WordEditorElement(options?)

connectedCallback()

disconnectedCallback()

attributeChangedCallback(name, oldValue, newValue)

Element Attributes

只读 Properties

文档导入、保存与导出

importDocument(input, options?)

load(input, name?)

loadBlank(name?)

saveDocument()

save()

exportDocument(options?)

内容、表格与图片

insertContent(content, options?)

insertText(text)

insertTable(rows?, columns?)

insertImage(input, options?)

exec(command, value?)

书签方法

listBookmarks()

hasBookmark(name)

findBookmark(name)

getBookmarkPosition(name)

gotoBookmark(name)

addBookmark(name?)

deleteBookmark(name)

insertTextAtBookmark(name, text)

字体注册与字体网关

registerFont(font)

registerFonts(fonts)

importFont(input, options?)

loadPersistedFonts()

listPersistedFonts()

clearPersistedFonts()

loadRepositoryFonts(manifestUrl?, persist?, options?)

loadFontGatewayFonts(options?)

模式、缩放与运行时

setMode(mode)

setEngine(engine)

setZoom(value)

reflowPages()

getRuntimeStatus()

destroy()

事件

exec() 命令与 value

接受 value 的常用命令

不需要 value 的内置命令

历史与格式

段落与列表

页面与视图

表格

对象与引用

审阅

公共 TypeScript 类型

WordEditorFontSource

WordEditorBookmarkInfo 与位置

结果与状态类型

错误与返回约定

`defineWordEditorElement(tagName?)`

`new WordEditorElement(options?)`

`connectedCallback()`

`disconnectedCallback()`

`attributeChangedCallback(name, oldValue, newValue)`

`importDocument(input, options?)`

`load(input, name?)`

`loadBlank(name?)`

`saveDocument()`

`save()`

`exportDocument(options?)`

`insertContent(content, options?)`

`insertText(text)`

`insertTable(rows?, columns?)`

`insertImage(input, options?)`

`exec(command, value?)`

`listBookmarks()`

`hasBookmark(name)`

`findBookmark(name)`

`getBookmarkPosition(name)`

`gotoBookmark(name)`

`addBookmark(name?)`

`deleteBookmark(name)`

`insertTextAtBookmark(name, text)`

`registerFont(font)`

`registerFonts(fonts)`

`importFont(input, options?)`

`loadPersistedFonts()`

`listPersistedFonts()`

`clearPersistedFonts()`

`loadRepositoryFonts(manifestUrl?, persist?, options?)`

`loadFontGatewayFonts(options?)`

`setMode(mode)`

`setEngine(engine)`

`setZoom(value)`

`reflowPages()`

`getRuntimeStatus()`

`destroy()`

`exec()` 命令与 value

接受 `value` 的常用命令

不需要 `value` 的内置命令

`WordEditorFontSource`

`WordEditorBookmarkInfo` 与位置