#DocumentEditor

DocumentEditor 用于编辑需要分页的 DOCX 兼容文档、报告和长篇内容。 TipTap 负责逻辑文档与选区，A3S Office 内核负责确定性分页、文本塑形和文件语义。

长文档 DOM 测量采用协作式调度。编辑器以 32 毫秒为上限分片测量规范的顶层块，只在块之间 让出事件循环；受控文档发生变化时会中止旧任务。只有完整测量才会更新可复用分页快照， Worker/WASM 布局结果仍是最终依据。

#属性

#内容结构

#输入法与受控更新

中文、日文、韩文等组合输入在进行期间由浏览器持有。DocumentEditor 不会通过 onChange 发布拼音等预编辑文字；compositionend 后会先等待 ProseMirror 完成 DOM 结算，再一次性发布完整的最终文档。

如果宿主在组合输入期间传入另一份受控 content，编辑器会把替换延后到组合输入结算。 最终本地输入会先通知宿主，仍然有效的宿主版本随后完成协调。宿主不需要为输入法增加 专用 debounce 或事件过滤器。

#原生大小写效果

“开始”功能区的“大小写效果”菜单用一个互斥字符格式状态提供常规、全部大写和小型大写。 Cmd/Ctrl+Shift+A 切换全部大写，Cmd/Ctrl+Shift+K 切换小型大写。正文、页眉页脚、 格式刷、字符格式修订和撤销共用同一组 TipTap 命令与元数据。

编辑器不会改写语义正文。全部大写由 text-transform: uppercase 渲染，小型大写由 font-variant-caps: small-caps 渲染。DOCX 导入、导出和重新打开会保留原生 w:caps 与 w:smallCaps，包括明确重置和 w:rPrChange 中的旧格式。

包含这两种效果的段落会有意使用浏览器行测量。大写转换可能让渲染字形数量与源 UTF-16 偏移不再一一对应，小型大写也会改变字体度量；浏览器作为这些段落的最终依据可以避免错误 分页，其余符合条件的段落仍使用 Worker/WASM 塑形。

#原生分脚本字体

Writer 会分别保留 WordprocessingML 的四个 w:rFonts 字体槽：ascii、hAnsi、 eastAsia 和 cs。每个槽都独立保存准确的直接字体、可选主题引用，以及浏览器实际解析的 字体；w:hint 继续作为原生元数据保留。样式继承只负责计算有效字体，不会改写尚未修改的 直接字体或主题身份。包含多种文字的同一运行会被拆成有界 TextStyle 片段，分别处理拉丁 ASCII、高 ANSI、东亚和复杂文字；中性标点仍跟随相邻文字。

Cmd/Ctrl+D 或“开始”功能区会打开“字体高级设置”，分别提供拉丁文字、东亚文字和复杂 文字字体。拉丁文字控件会同时更新 ascii 与 hAnsi；“开始”字体选择器表达“所有文字” 意图，会同时更新四个槽。三个控件分别判断混合选区，并支持“跟随样式”。预览会按文字片段 使用对应草稿字体。字体、缩放、间距、字距调整、着重号、隐藏文字、字符边框、空心、阴影、 阳文、阴文或位置的任意组合在应用时都会恢复保存的选区，并只生成一个事务和一条撤销记录。

正文、页眉、页脚、脚注、尾注、格式刷、字符格式修订、严格或过渡 DOCX 导入、准确导出与 重开共用同一类型模型。修改一个字体槽不会破坏其他槽未修改的主题引用。重复或错位元素、 多余或伪造属性、包含子节点或文本的叶节点、未知值，以及超过 127 个字符的字体名都会安全 拒绝并进入兼容性诊断。DOM 在 data-office-script-fonts 中保存经过校验的 JSON，在 data-office-script-font-slot 中保存当前片段；CSS 只使用解析后的字体，因此浏览器字体替代 不会改写原生文件身份。

#原生 OpenType 排版

Writer 为普通文字与结构化公式共用一个封闭的 Office 2010 OpenType 模型。它会保留全部 16 种原生 w14:ligatures 组合，w14:numForm 的 default、lining 或 oldStyle 数字字形，w14:numSpacing 的 default、proportional 或 tabular 数字间距， w14:stylisticSets 的 1 到 20 规范样式集 ID，以及明确启用或重置上下文替代的 w14:cntxtAlts 值。每个属性独立继承；格式错误、重复、错位、包含子节点或文本、 越界或命名空间伪造的值都会安全拒绝。

Cmd/Ctrl+D 或“开始”功能区会打开“字体高级设置”，分别提供连字、数字字形、数字间距、 样式集和上下文替代控件。每个控件独立显示混合选区状态与“跟随样式”值。应用时只修改每个 选中运行中用户触碰过的属性，保留其他直接 OpenType 设置，恢复打开弹窗时保存的选区，并把 OpenType、分脚本字体和其他高级字符设置合并成一个事务及一条撤销记录。实时预览与正文使用 同一套规范 CSS 投影。

正文、页眉、页脚、脚注、尾注、批注、格式刷、字符格式修订与拒绝修订共用同一类型模型。 DOCX 导出会按规范顺序写出 w14 属性，声明所需命名空间与 mc:Ignorable 标记，并在重开 后保留当前值和旧值。兼容性诊断会指出不支持或无效的源值。DOM 在 data-office-opentype-features 中保存规范 JSON，CSS 通过 font-feature-settings、 font-variant-ligatures 与 font-variant-numeric 投影。启用塑形的段落使用浏览器权威 行测量，避免字形替代让源 UTF-16 偏移与分页不同步。

#原生字符间距

Writer 用一个有符号原生 w:spacing 值保存字符间距，范围为 -31,680 到 31,680 twips， 每 20 twips 等于 1 磅。Cmd/Ctrl+D 或“开始”功能区会打开“字体高级设置”，提供标准、 加宽、紧缩以及 0.05–1,584 磅的精确间距值。混合选区在用户明确选择模式之前保持不变。 应用会恢复打开弹窗时保存的选区，并只生成一条撤销记录；取消和 Escape 不修改文档， 并把焦点还给编辑器。

正文和页眉页脚编辑器共用同一条 TipTap 命令，显式零值与继承间距保持区分。格式刷、字符 格式修订、撤销、DOCX 导入、导出和重新打开，以及 w:rPrChange 中的旧格式都会保留准确 有符号值。DOM 使用 data-office-character-spacing-twips 保存原生值，CSS 只通过 letter-spacing 投影显示效果，不改写文字。排版内核会应用相同的线性字宽调整，因此符合 条件的段落仍然使用 Worker/WASM 路径。

#原生字符水平缩放

Writer 用一个 1% 到 600% 的原生 w:w 整数保存字符水平缩放。缺少该属性时仍然继承， 显式 100% 会作为直接重置保留，空的 <w:w/> 按原生规则解释为 100%。严格与过渡 WordprocessingML 共用同一个有界整数模型；格式错误、小数、重复、包含子节点、越界或 命名空间伪造的属性都会安全拒绝。

Cmd/Ctrl+D 或“开始”功能区会打开“字体高级设置”，其中“缩放”字段接受准确整数范围。 缩放、间距和基线位置分别判断混合选区；修改任意组合并应用后，会恢复保存的选区，且只 生成一个事务和一条撤销记录。字符缩放没有独立标准快捷键，因此 Writer 不会虚构一个。

正文、页眉、页脚、格式刷、字符格式修订、拒绝修订恢复、DOCX 导入/导出/重新打开以及 w:rPrChange 中的旧格式都会保留准确值。DOM 使用 data-office-character-scale-percent 保存原生值，并通过 CSS font-stretch 投影。 在 Worker/WASM 文字排版协议能够传递准确逐运行水平缩放之前，非 100% 的运行会明确使用 浏览器行测量，其余符合条件的段落仍走确定性内核路径。

#原生字距调整

Writer 用一个 0 到 3,277 半磅单位的原生 w:kern 阈值保存字距调整。 正值会在有效 w:sz 字号大于或等于阈值时启用字对调整，因此 24 表示 12 磅。显式零值表示所有字号都启用。直接属性缺失时继续按样式层级继承， 整个层级都缺失 w:kern 时则保持关闭。

共享的 Cmd/Ctrl+D “字体高级设置”弹窗提供字距调整复选框，以及 0–1,638.5 磅、按 0.5 磅递增的准确阈值。新建直接格式默认为 12 磅。缩放、 间距、字距调整、着重号和基线位置分别判断混合选区，并可在一个事务中同时提交。 取消勾选只会清除直接字距调整；应用会恢复保存的选区，并只生成一条撤销记录。 该能力没有独立标准快捷键，因此 Writer 不会虚构一个。

正文、页眉、页脚、脚注、尾注、继承样式、格式刷、字符格式修订、拒绝修订恢复、 DOCX 导入、导出、重新打开以及 w:rPrChange 中的旧格式都会保留准确半磅值。 严格与过渡文档都会安全拒绝缺值、重复、嵌套、含文本、多余属性、小数、负数、越界和 命名空间伪造。兼容性诊断会分别报告有效值和被拒绝值。

DOM 用 data-office-kerning-threshold-half-points 保存阈值，并把实际状态投影为 CSS font-kerning: normal 或 none。编辑、预览和 PDF 表面默认关闭字距调整， 再共用该投影。同一有效布尔状态会传入 Worker/WASM 文字排版，避免分页和绘制对 字对宽度产生不一致判断。

#原生东亚着重号

Writer 用一个封闭的原生 w:em 状态保存着重号：none、dot、comma、circle 或 underDot。直接属性缺失时，会继续按运行、字符样式、段落样式和文档默认值继承。 显式 none 与移除直接格式不同，它会有意覆盖并关闭继承的着重号。

共享的 Cmd/Ctrl+D “字体高级设置”弹窗提供“跟随样式”“无”“上方圆点”“上方逗号” “上方圆圈”和“下方圆点”。着重号、缩放、间距、字距调整和基线位置分别保留混合选区 状态。“跟随样式”只移除直接属性，“无”则写入原生重置值。应用会恢复保存的选区和焦点， 并把所有已修改字符属性作为一个事务和一条撤销记录提交。Writer 没有对应的独立标准 快捷键，因此命令目录不会虚构一个。

正文、页眉、页脚、脚注、尾注、继承样式、格式刷、字符格式修订、拒绝修订恢复、严格或 过渡 DOCX 导入、导出、重新打开，以及 w:rPrChange 中的旧格式都会保留准确值。缺值、未知 标记、重复或嵌套元素、带文本的叶节点、多余属性和命名空间伪造都会安全拒绝，并进入兼容性 诊断。

DOM 使用 data-office-emphasis-mark 保存状态。CSS text-emphasis-style 和 text-emphasis-position 会把效果投影为文字上方的实心圆点、逗号或空心圆圈，或者文字 下方的实心圆点。可见着重号会让段落使用浏览器权威行测量，以计入普通行框之外的字形。 只有最终计算出的标准与 WebKit 着重号样式都为空或 none 时，显式“无”才继续使用 Worker/WASM 路径，因此宿主 CSS 覆盖不会造成分页判断不一致。

#原生隐藏文字

Writer 使用一个三态 TextStyle 属性保存隐藏文字。移除直接属性后，会继续按运行、字符 样式、段落样式和文档默认值继承。true 写入原生 w:vanish；false 写入显式 w:vanish w:val="0" 重置，确保继承的隐藏格式在导出和重新打开后仍保持可见。

共享的 Cmd/Ctrl+D “字体高级设置”弹窗会分别处理隐藏文字、缩放、间距、字距调整、 着重号和基线位置。混合选区在用户修改“隐藏文字”复选框前保持不变；应用会恢复保存的 选区，并把所有已修改属性作为一个事务和一条撤销记录提交。标准 Cmd/Ctrl+Shift+H 快捷键调用同一类型化命令；TipTap 冲突的突出显示绑定已禁用。

正文、页眉、页脚、脚注、尾注、继承样式、格式刷、字符格式修订、拒绝修订恢复、严格或 过渡 DOCX 导入/导出/重新打开，以及 w:rPrChange 中的旧格式都会保留准确状态。空属性 以及小写的 1、0、on、off、true、false 会被接受；未知大小写或标记、重复、 子节点、文本、多余属性、错位元素和命名空间伪造都会安全拒绝并进入兼容性诊断。未修改的 评论 XML 只进行源保留，这一边界不表示支持富评论正文编辑。

DOM 使用 data-office-hidden-text="true|false" 保存状态。隐藏文字默认不显示；“视图” 功能区的“显示隐藏文字”只会在可编辑 Writer 表面揭示内容，并添加传统点状下划线。只读 预览和独立 PDF 捕获始终隐藏内容。包含隐藏文字的段落使用浏览器权威行测量，避免不可见 字形进入 Worker/WASM 字宽模型。

#原生空心、阴影、阳文与阴文

Writer 使用四个独立、可空的 TextStyle 属性保存原生 w:outline、w:shadow、 w:emboss 和 w:imprint。移除直接属性后，会继续按运行、字符样式、段落样式和文档 默认值继承。true 写入原生启用属性，false 写入显式 w:val="0" 重置，确保继承效果 在导出和重新打开后仍保持关闭。

空心与阴影可以同时启用。阳文与空心、阴影、阴文互斥；阴文与空心、阴影、阳文互斥。 共享的 Cmd/Ctrl+D “字体高级设置”弹窗分别保留四项的混合选区状态。启用互斥效果时， 界面会自动清除所有冲突项并把这些清除标记为已修改，因此“应用”会把完整、无冲突的结果 作为一个事务和一条撤销记录提交。Writer 没有对应的独立标准快捷键，所以命令目录不会 虚构一个。

正文、页眉、页脚、脚注、尾注、文档默认值、继承样式、格式刷、字符格式修订、拒绝修订 恢复、严格或过渡 DOCX 导入/导出/重新打开，以及 w:rPrChange 中的旧格式都会保留准确 值。空属性以及小写的 1、0、on、off、true、false 会被接受；未知大小写或 标记、重复、嵌套或带文本的叶节点、多余属性、错位元素、命名空间伪造和冲突启用组合都会 安全拒绝并进入兼容性诊断。

DOM 使用 data-office-legacy-text-outline、data-office-legacy-text-shadow、 data-office-legacy-text-emboss 和 data-office-legacy-text-imprint 保存显式 true|false 值。CSS 用有界描边投影空心，用有界偏移投影阴影，并用方向相反的明暗偏移 投影阳文与阴文。浏览器与 PDF 因此提供受控视觉近似，不声称与桌面引擎逐像素一致。这四种 效果只改变绘制，其他条件符合的段落仍走 Worker/WASM 排版路径。打开 Playground 的 “文字效果”模板即可查看四种状态，并把合法的“空心 + 阴影”组合切换为互斥效果。

#原生字符边框

Writer 使用一个类型化原生 w:bdr 值保存字符边框。模型会保留 WordprocessingML 的 25 种可见线型，以及显式 nil 和 none 重置；同时保留直接颜色或带 tint/shade 的主题 颜色、2 到 96 个八分之一磅单位的宽度、0 到 31 磅的文字间距，以及显式阴影和框架标志。 导入后的 nil 与 none 即使都不绘制，也仍然保持不同语义。

“开始”功能区的字体组提供直接“字符边框”开关。共享的 Cmd/Ctrl+D“字体高级设置”弹窗 会保持未修改的混合选区，并区分“跟随样式”“显式无边框”和可编辑边框。线型、颜色、 0.25–12 磅且以 0.125 磅递增的准确宽度、整数间距、阴影与框架，会与其他已修改字符属性 一起通过一个事务和一条撤销记录提交。格式刷复用同一个 Mark。Writer 没有对应的独立标准 快捷键，因此命令目录不会虚构一个。

文档默认值、段落和字符样式、正文、页眉、页脚、脚注、尾注、字符格式修订、严格或过渡 DOCX 导入、准确导出与重开都会保留语义值。格式错误、重复、错位、命名空间伪造、带子节点 或文本、多余属性、艺术边框、越界以及无法解析主题颜色的输入都会安全拒绝并进入兼容性 诊断。w:rPrChange 中的旧格式使用同一个有界解析与导出路径。

DOM 在 data-office-run-border 中保存校验后的 JSON，并通过 CSS 投影四边边框、间距、 阴影和跨片段克隆。可见边框和内边距会改变行内几何，因此相关段落使用浏览器权威行测量； 显式 nil 与 none 仍可走 Worker/WASM。浏览器与 PDF 的线型绘制属于有界视觉近似， OOXML 语义则保持准确。打开 Playground 的“字符边框”模板即可体验完整设置与单步撤销。

#原生字符底纹

Writer 使用一个类型化原生 w:shd 值保存字符底纹，不再把它压扁为浏览器背景色。模型会 保留 WordprocessingML 的全部图案、直接或自动前景色与背景色、彼此独立且带 tint/shade 的 themeColor 与 themeFill 引用，以及显式 nil 重置。同一主题通道同时带 tint 和 shade 时，浏览器绘制遵循原生 tint 优先级，导出仍保留两个属性。

共享的 Cmd/Ctrl+D“字体高级设置”弹窗会独立判断底纹混合状态，并区分“跟随样式”、 “显式无底纹”和可编辑底纹。图案、前景色与背景色可分别修改；解析颜色未改变时继续保留 主题身份，选择直接颜色只替换对应通道。底纹会与其他已修改字体属性通过一个事务和一条 撤销记录提交，格式刷复用同一个语义 TextStyle 值。

文档默认值、段落和字符样式、条件表格样式、正文、页眉、页脚、脚注、尾注、字符格式修订、 严格或过渡 DOCX 导入、准确导出与重开共用同一解析器。格式错误、重复、错位、命名空间 伪造、带子节点或文本、多余属性以及无法解析主题颜色的叶节点会安全闭合为显式 nil，并 进入兼容性诊断。w:rPrChange 中的旧值使用同一个有界模型。

DOM 在 data-office-run-shading 中保存校验后的 JSON。CSS 对实心、条纹、交叉、细线和 百分比图案提供有界投影，并克隆跨行片段。底纹只改变绘制，因此符合条件的段落仍走 Worker/WASM 排版。原生 w:highlight 保持为独立 Mark，并在显示时优先于底纹，但不会删除 底层底纹语义。打开 Playground 的“字符底纹”模板即可编辑完整模型并验证单步撤销。

#原生校对语言

Writer 会分别保留原生 w:lang 的三个语言槽：拉丁文字 w:val、东亚文字 w:eastAsia 与双向文字 w:bidi。原生 w:noProof 是另一项独立的三态值：移除直接值 表示跟随当前样式，false 表示显式参与校对，true 表示排除校对。它不会被压平为整个 文档共用的浏览器拼写检查开关。

“审阅”功能区在“拼写检查”旁提供“设置校对语言”。可访问弹窗接受有界 BCP 47 语言标记， 分别报告三个槽的混合状态，未修改的槽保持原值，并为每个语言槽和校对状态提供“跟随样式”。 “应用”会恢复捕获的选区与焦点，把所有已修改字段放入一个 TipTap 事务和一条撤销记录； 编辑页眉或页脚时复用同一模型。

文档默认值、段落和字符样式、正文、页眉、页脚、脚注、尾注、字符格式修订、拒绝修订恢复、 严格或过渡 DOCX 导入/导出/重开，以及 w:rPrChange 中的旧格式都会保留准确语言槽和显式 状态。格式错误、重复、错位、嵌套、带文本、多余属性、命名空间伪造、无效语言标记或无效 开关值会安全拒绝，并进入兼容性诊断。

DOM 在 data-office-proofing-languages 中保存规范语言 JSON，在 data-office-no-proof="true|false" 中保存显式状态，并投影有效的 lang 与 spellcheck 属性。有效语言还会随每个 Worker 排版运行传入 Rust/WASM，并在 RustyBuzz 塑形前写入缓冲区。 这会保留与语言相关的塑形行为，但不声称内置拼写词典、语法或翻译服务。打开 Playground 的 “校对语言”模板即可查看拉丁、东亚、双向文字、显式参与校对和排除校对示例。

#原生字符基线位置

同一个“字体高级设置”弹窗会把标准、提升或降低保存为一个有符号原生 w:position 值， 范围为 -3,168 到 3,168 个半磅单位。一个半磅单位等于 0.5 磅，因此位置值支持 0.5–1,584 磅的精确幅度。缩放、位置与间距分别判断混合选区；即使同时修改三项，应用也 只提交一个事务并生成一条撤销记录。

正文、页眉页脚、格式刷、字符格式修订以及 w:rPrChange 中的旧格式共用同一个 TipTap 属性，显式零值与继承值保持区分。过渡 DOCX 接受有符号整数；严格 DOCX 还接受能够准确 换算为半磅整数的通用度量。格式错误、重复、越界或命名空间伪造的属性都会安全拒绝。 导出和重新打开会写回准确原生值，包括 w:position w:val="0"。

DOM 使用 data-office-character-position-half-points 保存原生值，并通过 --work-document-character-position 暴露准确磅值；CSS 再以数值 vertical-align 投影。 当 w:position 与 w:vertAlign 同时存在时，原生上下标优先显示；移除上下标后，保留的 基线偏移会重新生效。在 Worker/WASM 文字排版协议能够传递逐运行基线偏移之前，这类段落 会明确回退到浏览器行测量，其余符合条件的段落仍走确定性内核路径。

#实时评论模式

传入已经初始化、带认证 Actor 且 mode: 'comment' 的 Document 协作会话，可以在不开放 正文编辑的情况下创建选区评论。审阅者可以创建线程、回复、解决或重开，并且只能删除 自己拥有的记录。线程、选区 Mark、Actor 归属和脱离锚点状态会持久化到 Yjs/Yrs；远端 审核变化不会进入本地撤销历史。浏览器、CLI/MCP 与 A3S Boot 的完整授权流程见 多人实时协作。

#实时建议模式

传入已经初始化、带认证 Actor 且 mode: 'suggest' 的 Document 协作会话，可以创建署名 插入、删除与替换建议。编辑器会强制记录文字修订，不显示普通格式、评论与最终决定控件， 并且只允许当前 Actor 撤回自己的建议。规范文字、结构、非建议格式、选项、评论和其他 Actor 的建议都保持受保护状态。

edit 参与者在修订面板中接受或拒绝建议。可见修改和一条不可变 WorkDocumentChangeDecision 会在同一个 Yjs 事务中提交。记录保留建议与决定双方的 Actor、名称和时间，并通过 content.changeDecisions 返回；第二个冲突决定会失败关闭。 A3S Boot 参考服务还会在持久化和广播之前，通过 Yrs 重复执行同一套语义授权。完整浏览器 与后端契约，以及当前原生 CLI/MCP 的限制，见 使用 suggest 模式提出修订。

#字符格式修订

开启修订后，对已有文字应用直接字符格式会创建一条 formatting 修订。有界模型覆盖粗体、 斜体、下划线、删除线、上下标、字体、字号、文字颜色、高亮、字符缩放、字符间距、字距调整阈值、着重号、隐藏文字、字符边框、空心、阴影、阳文、阴文、基线位置、全部大写、小型大写和 Word 文档网格状态。仍处于待处理插入修订中的文字继续归属于该插入，不会再嵌套一条格式修订。

修订保存准确的旧直接 Mark，同时用新 Mark 渲染选中文字。接受只移除修订包装并保留新 格式；拒绝恢复旧 Mark 并移除包装，不改变任何字符。两种操作都只产生一个事务；清除 直接格式也不会删除评论或修订 Mark。

受支持的严格或过渡 DOCX w:rPrChange 会导入为同一张审核卡，保留作者、可选日期、 当前格式和旧格式；导出时重新写成原生 w:rPrChange。不支持、格式错误、重复或命名空间 伪造的运行属性修订继续进入结构诊断，不会被误解为可编辑状态。

在协作中，修订 Mark 与接受/拒绝审计记录都通过标准 Yjs v1 更新传输。Yrs 会校验有界 格式快照并读取 formatting 决定记录；经过认证的 suggest 会话必须保留已有格式修订， 不能创建或改写它。完整边界见 同步字符格式修订与 A3S Boot 后端。在 Playground 中依次点击 体验格式修订、审阅、查看修订（2），即可审核“格式”卡。

#原生下划线格式

Writer 可以创作并重新打开全部 18 种原生 WordprocessingML 下划线值：none、single、 words、double、thick、dotted、dottedHeavy、dash、 dashedHeavy、dashLong、dashLongHeavy、dotDash、dashDotHeavy、 dotDotDash、dashDotDotHeavy、wave、wavyHeavy 和 wavyDouble。 开始功能区、选区工具栏与页眉页脚共用一个可访问的拆分控件；下划线颜色支持自动颜色、 直接 RGB，以及保留的 theme/tint/shade 身份。

Cmd/Ctrl+U 会关闭任意已启用样式，或从关闭状态启用 single； Cmd/Ctrl+Shift+D 切换 double，Cmd/Ctrl+Shift+W 切换仅字下划线。 格式刷、字符格式修订、撤销、DOCX 导出与重开都会保留准确的类型化状态，包括用于覆盖 继承格式的显式 none。

#原生删除线格式

Writer 使用一个 none | single | double 类型化 Mark 保存无删除线、单删除线与双删除线。 开始功能区、选区工具栏和页眉页脚功能区共用同一个可访问拆分控件，紧凑页眉页脚工具栏 保留直接切换按钮。正文、页眉页脚、格式刷、字符格式修订、撤销、DOCX 导出与重开都会 保留准确样式，包括用于覆盖继承格式的显式 none。

DOCX 导入会在每一层样式和直接格式中分别跟踪 w:strike 与 w:dstrike，再按双删除线 优先于单删除线的规则解析。导出会同时写入两个属性，因此从继承的双删除线切换到单删除线， 或清除任一继承状态后，重新打开文件都不会恢复过期格式。CSS 只投影实线或双线删除效果， 不会改写文字，也不会让原本符合条件的段落退出 Worker/WASM 排版路径。

传统 Office 没有为 Writer 删除线定义直接快捷键，因此命令目录不会宣传快捷键。 编辑器同时禁用 TipTap 无关的 Mod+Shift+S 绑定；请使用功能区或选区工具栏。

#段落格式修订

开启修订后，段落命令会给每个受影响的段落或标题创建独立的 paragraph-formatting 修订。有界快照覆盖对齐、文字方向、左右及首行或悬挂缩进、 段前段后间距、行距与规则、段中不分页、与下段同页、段前分页、孤行控制、同样式段落 间距、Outline Level、制表位、边框、底纹和默认折叠状态。一次跨段命令共享稳定修订 身份；未决状态下再次修改格式仍保留第一次修改前的完整快照，不会重置审核起点。

接受会保留当前段落属性，只移除审核元数据。拒绝会恢复完整旧段落属性，不改动正文或 行内 Mark。原格式命令、接受与拒绝分别形成独立撤销边界；旧快照损坏或不是规范形式时 会失败关闭，不会只恢复一部分属性。

受支持的严格或过渡 DOCX w:pPrChange 会导入为“段落格式”卡，保留作者、可选日期、 当前属性和完整的受支持旧属性快照；导出会重新生成原生 w:pPrChange，并移除全部私有 传输标记。重复、格式错误、命名空间伪造或包含不支持属性的段落属性修订继续进入结构 诊断。

节点元数据与不可变 changeKind: "paragraph-formatting" 决定记录都使用标准 Yjs v1 更新。Yrs 能读取该决定类型，让浏览器创建的修订跨重启、重复和乱序投递后继续存在， 并拒绝 suggest 更新创建或改写段落审核元数据。完整链路见 同步段落格式修订。Playground 的第二张卡就是 “段落格式”；拒绝后会恢复旧对齐、缩进、间距和行距，同时保留正文与独立的字符格式 修订。

#文档比较与合并

“审阅”功能区现在提供一级 比较文档 和 合并文档 工作流。比较会把当前受控文档 视为原稿，并把导入的 .docx、.html、.htm 或 .txt 文件视为修订稿。确定性的 分节、块对齐与词元差异会生成现有可审阅的插入、删除、字符格式和段落格式修订。所选 修订者会写入每条生成修订，文件名作为有界事务元数据保存，全部结果只通过一次受控 onChange 发布，一次撤销即可恢复比较前文档。比较成功后，“修订”窗格会自动打开， 可以继续使用现有命令逐项定位、接受或拒绝。

合并采用不同的失败关闭契约。导入的审阅副本必须已经包含修订，当前文档不能有未处理 修订，而且在不可变快照上拒绝导入副本的全部修订后，必须准确重建当前基线。当前有界 路径支持行内插入与删除、字符格式和段落格式修订，并保留当前段落身份。缺少修订、旧 格式快照损坏、基线不一致或存在结构块修订时，当前文档不会改变，并会返回本地化诊断。

每个版本最多可以比较 1,024 个块，两份文档文字合计最多 1,000,000 个字符。块对齐和 每次行内差异最多分配约 110 万个矩阵单元。两份文档必须拥有相同分节数量和页面布局 属性。未变化的复杂块可以原样通过，但发生变化的表格、列表、图片、公式、内容控件、 空结构块或其他复杂树不会被压平为容易误导的纯文字差异。任一比较输入中已有修订、 不支持的审阅标记和分节布局变化也会失败关闭。

生成的行内修订会导出为原生 w:ins 与 w:del，字符格式修订导出为 w:rPrChange，段落格式修订导出为 w:pPrChange；导出并重开后仍会保留修订者、 日期、文字和旧格式快照。浏览器新建的插入或删除段落还会使用块容器元数据，使拒绝 插入块或接受删除块时能够移除整个容器。这种容器身份尚未映射为原生段落标记修订， 因此需要准确结构接受或拒绝语义的调用方应在导出 DOCX 前先处理这些块修订。运行级 原生修订仍可重开，这项边界会被明确报告，不会被描述成完整结构比较保真。

在 Playground 中打开 文档比较 模板，选择“审阅”→ 比较文档，再导入修订 文件即可走通公开路径。聚焦组件测试、DOCX 重开、响应式 Playwright 和仅本地运行的 word-document-comparison.acl A3S Test 套件会覆盖受控发布、审核决定、焦点恢复、 可访问性以及空浏览器诊断。Actions 与 Pages 不安装或调用 A3S Test。

#DOCX 文字与文档网格保真

导入的分节布局会保留可选的 WorkDocumentGrid，包括 OOXML 网格类型和以磅为单位的行间距； 文字运行会保留明确声明的 snapToGrid。这些属性在编辑和 DOCX 导出后仍然存在；没有文档 网格的源文件不会被文档生成器补入默认网格。

对于 Word 自动行距，浏览器会把原始段落倍数与解析后字体的实测 传统 Office 行进高度组合使用。 这些渲染指标属于内部兼容数据；导出仍使用原始 OOXML 段落倍数，因此浏览器校准不会改写 文档的行距语义。

#原生可更新目录

Writer 把目录保存为可选择、不可直接改写的类型化块，不会把生成结果压成普通正文。 “引用”选项卡中的“插入或自定义目录”复用现有大纲，可选择 1 到 9 级语义标题或原生大纲 级别段落，并保留超链接、页码显示、页码右对齐，以及点线、短横线、下划线或无前导符。 每次插入或修改选项只提交一个 TipTap 事务和一条撤销记录。传统 Writer 没有为该命令定义 独立直接快捷键，因此命令目录不会虚构一个。

每个目录项保存有界标题、级别、页码和稳定目标。入选项缺少原生段落身份时，会在插入或 修改目录的同一事务中获得身份，因此插入目录不会让自身链接失效，一次撤销也会同时恢复 两项变化。页码来自 PAGE 域使用的同一套实时 Worker/WASM 分页解析器。“更新目录”会在一个 事务内从这两个来源重新生成全部目录块，因此修改标题或分页不会产生第二套标题或页码状态。 每个目录块最多缓存 512 项，超出部分会明确标记为截断，不会写入无界节点属性。

DOCX 导出会写入原生 w:sdt 目录内容控件、可更新 TOC 域、缓存目录项、内部标题书签和 所选前导符。导入与重开支持常见的 TOC \\o "1-3" \\h \\z \\u 子集、完整级别范围的 页码隐藏，以及页码不右对齐时的空格分隔。无法无损表示的自定义 \\t 样式映射、部分 页码范围、错误级别范围和其他分隔符不会被静默近似，而会进入兼容性诊断。每个导入目录 独立匹配缓存项，因此多个目录可以重复指向同一个标题。Playground 的 “可更新目录”模板可以直接验证编辑、导航、更新、导出和重开全流程。

#原生文档索引

Writer 把每个已标记索引项保存为可选择的行内原子节点，并把生成结果保存为独立、可选择且 不可直接改写的类型化块。“引用”选项卡中的“标记索引项”会读取当前选中文字，并可设置主 索引项、次索引项、交叉引用，以及当前页码的粗体或斜体意图。“插入或自定义索引”支持一到 四栏、缩进式或连续式布局、页码对齐，以及点线、短横线、下划线或无前导符。传统 Writer 没有为这些命令定义独立直接快捷键，因此命令目录不会虚构快捷键。

生成块会排序规范化后的索引项，合并同一页上的重复项，同时在合并后的页码链接中保留全部 稳定标记目标。点击页码会选中对应正文标记。页码只读取 PAGE 域使用的同一套实时 Worker/WASM 解析器，因此分页或重排不会产生第二套页码模型。标记、编辑、插入、自定义和 显式更新全部索引分别只提交一个 TipTap 事务和一条撤销记录。文档最多读取 2,048 个标记并 缓存 512 个生成行；超过任一边界时会明确显示截断，不会写入无界节点属性。

DOCX 导出会写入原生 w:fldSimple XE 项，以及包含实时 INDEX 域与 Index1/Index2 缓存行的真实 w:sdt 内容控件。主次索引项、交叉引用、页码粗体/斜体、栏数、连续式布局、 对齐和前导符可经过导出、导入、重开和第二次导出保留。导入接受可无损表示的常见 XE \\b、\\i、\\t 与 INDEX \\c、\\e、\\r 子集。索引范围、自定义索引类型、 区域设置开关、损坏字段和其他不支持的开关会明确进入兼容性诊断，不会被静默近似。 Playground 的“原生索引”模板可以直接验证标记、导航、更新、导出和重开全流程。

#内置导航

“视图”选项卡会在宽屏打开固定的标题导航，在窄屏打开可管理焦点的抽屉。 导航搜索同时覆盖标题与正文，按当前章节组织结果，高亮所有命中项，并把编辑器选区 移动到目标位置，但不会增加撤销记录。窄屏选择结果后，抽屉先关闭，再把焦点和精确 文本范围还给正文。

“页面”视图显示实时物理页面缩略图。超过 48 页时只挂载最多 24 个连续页面按钮，并在 需要时额外保留当前页和键盘游标页。物理滚动占位保持完整文档距离，Home 和 End 可以 直接到达首尾页，无需同时挂载全部页面。

标题和全文搜索集合超过 48 条后也使用同一窗口机制：最多挂载 32 个连续条目，并在窗口 外稀疏保留当前项、选中项和键盘游标项。原生滚动距离、全局列表序号、方向键遍历、 Home/End 和精确搜索选区都不会丢失。长距离搜索跳转会在选区生效的一帧内使用即时滚动， 随后恢复编辑器原有滚动样式。

#引用与题注

“引用”选项卡可以插入和更新类型化目录与原生索引，并可插入题注、交叉引用、脚注、尾注、 页码字段、日期与文献引用。 删除或移动题注会在同一事务中更新相关交叉引用：有效目标会重新编号，目标缺失时显示 Missing reference，而不是继续显示过期编号。一次撤销会同时恢复题注与引用字段。

#图片属性

选中正文图片后会打开“图片”功能区。常用环绕和对齐命令可以直接使用，“图片属性”弹窗则 统一编辑厘米宽高、每张图片独立的纵横比锁定、环绕方式、位置、文字距离和替代文字，并 适配手机视口。

一次确定只产生一条撤销记录，并且只改动用户实际编辑过的字段。导入图片的像素尺寸如果 只是以两位小数厘米显示，会原样保留。取消或 Escape 不修改文档，图片仍保持选中，键盘 焦点会回到“图片属性”按钮。

#自定义选区菜单

菜单工厂会收到不可变的选区快照，其中包含精确文本、结构化片段、前后文、全文纯文本、 同步 HTML 与当前受控内容，同时提供能检测冲突的编辑命令。

import type {
  DocumentContent,
  GetDocumentSelectionMenuItems,
} from '@a3s-lab/office/core';
import { DocumentEditor } from '@a3s-lab/office/react';

const getSelectionMenuItems: GetDocumentSelectionMenuItems = (snapshot) => [
  {
    id: 'rewrite',
    label: '润色',
    onSelect: async (context) => {
      const replacement = await rewriteWithModel({
        selection: snapshot.selection.text,
        before: snapshot.selection.beforeText,
        after: snapshot.selection.afterText,
        document: snapshot.document.text,
      });
      context.commands.replaceText(replacement);
    },
  },
];

export function Editor(props: {
  content: DocumentContent;
  onChange: (content: DocumentContent) => void;
}) {
  return (
    <DocumentEditor
      {...props}
      getSelectionMenuItems={getSelectionMenuItems}
    />
  );
}

异步操作需要返回 Promise。编辑器会在无关事务发生后重新映射原选区；如果选中的文本 本身已经变化，后续 replaceText 会返回 stale-selection，不会改错内容。

“询问 AI”这类开放操作，应先在宿主界面收集用户问题，再发出请求。Playground 的实现 会打开独立问题输入框；提交后仍可查看所附上下文，但不会用整篇上下文占满助手消息流。

#Extension

extensions 接收 TipTap Extension。数组引用应保持稳定，每个 Extension 必须使用 唯一名称。如果自定义 Node 或 Mark 需要经过 DOCX 导入导出后仍然存在，还要提供相应 文件语义。详见扩展机制。