OfficeCLI docx 文档级格式化实战：基于 `document` 容器（路径 `/`）配置页面、docDefaults、主题与 CJK 排版

CLIAI 应用MCP 服务【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址https://gitcode.com/GitHub_Trending/of/OfficeCLI点击查看免费下载本文以 OfficeCLI 官方示例 examples/word/document-formatting.md 为骨架深入讲解 docx 中document这一只读容器地址为/的完整属性面文档元数据、页面设置、docDefaults 默认格式、主题调色板、CJK 网格与排版、字体嵌入以及显示/打印/隐私开关。文章配套 document-formatting.py 与 document-formatting.sh 两份可直接运行的生成脚本并给出对应 schemaschemas/help/docx/document.json与 Word 处理器源码WordHandler.Set.DocDefaults.cs、WordHandler.Set.DocSettings.cs级别的实现依据。读完本文你将掌握用一条officecli set命令批量配置 Word 文档全局属性的方法并理解这些属性最终写入 OOXML 的哪些部件与元素。认识document容器只读、地址为/、只能 set/get在 OfficeCLI 的 docx 属性模型中document是只读容器其位置路径固定为/。它承载的是没有段落级或 run 级等价物的文档级设置——即「这份文档整体」的属性而不是某个段落、某个 run 的属性。你不能对它执行add或removeschema 中operations: { add: false, remove: false }只能set与getget /返回整个属性包同时也会列出顶层子容器body、styles、numbering等见 schemas/help/docx/document.json 的children定义它extends _shared/root-metadata因此继承了theme.color.*、theme.font.*与extended.*等共享属性定义见 schemas/help/_shared/root-metadata.json。最基本的两条命令officecli set file.docx / --prop authorJane --prop titleQ3 Report officecli get file.docx / # 读取整个属性包示例脚本通过 sdk/pythonpip install officecli-sdk驱动启动单个常驻进程resident所有写操作通过命名管道pipe送达避免每条命令都 fork 一次进程。若 SDK 未 pip 安装脚本自动回退到仓库内的 SDK 副本sys.path.insert(0, .../sdk/python)。SDK 的本质是「把命令字典原样转发给 resident 管道」不引入第二套词汇——见 sdk/python/officecli.py 顶部注释。重新生成示例文档cd examples/word pip install officecli-sdk python3 document-formatting.py # → document-formatting.docx纯 CLI 版本则是 document-formatting.sh命令逐条对应二者产出等价文档。脚本刻意不启用set -e与 SDK 版的doc.batch一样容忍向前兼容的UNSUPPORTED props警告officecli 返回退出码 2继续构建出完整文档避免因个别未知属性中断整份文件。七组文档级属性详解以下属性全部作用于document容器路径/按功能划分为七组。1. 元数据核心 扩展属性officecli set file.docx / --prop authorJane Author --prop titleQ3 Field Report \ --prop subjectFinance --prop keywordsreport,q3,finance \ --prop descriptionQuarterly field summary. --prop lastModifiedByEditorial officecli set file.docx / --prop extended.companyAcme Corp \ --prop extended.managerDana Lead --prop extended.templateNormal.dotmauthor与creator互为别名schema 中aliases: [creator]extended.*系列写入docProps/app.xml的 Company / Manager / Template 字段见 root-metadata.json部分键是只读元数据category、revisionNumber、created、modified、protection、protectionEnforced、extended.application、extended.words等schema 中set: false仅在get时可见。例如revisionNumber来自docProps/core.xml的cp:revision保存计数器与修订追踪help docx revision是两回事。2. 页面设置写入节属性sectProfficecli set file.docx / --prop pageWidth21cm --prop pageHeight29.7cm \ --prop orientationportrait \ --prop marginTop2.54cm --prop marginBottom2.54cm \ --prop marginLeft3.18cm --prop marginRight3.18cm \ --prop marginHeader1.5cm --prop marginFooter1.75cm officecli set file.docx / --prop mirrorMarginstrue --prop gutterAtTopfalse \ --prop bookFoldPrintingfalse长度值接受cm/in/pt或裸 twips1 英寸 1440 twips1pt 20 twipsorientationlandscape会交换宽高schema 注释明确指出pageWidth/pageHeight/orientation/marginTop等是sectPr的便捷读回convenience readback主要的编辑路径是/section[N]见 schemas/help/docx/section.json。也就是说在/上设置页面几何底层同样落到正文最终节的sectPrw:pgSz、w:pgMarmirrorMargins镜像边距面向页、gutterAtTop装订线在顶部、bookFoldPrinting书籍折页打印实际写入settings.xml的对应开关元素实现于 WordHandler.Set.DocSettings.cs 的 Layout Flags 分支.sh版本还演示了marginGutter0cm装订线宽度与compatibility.mode15兼容模式标识。关于sectPrpresent示例文档刻意不演示这个裸开关。它是 dump→batch 往返的内部标记——强制正文最终节发出一个可能为空的w:sectPr/让空节属性在重建中存活get不可见、单一取值绝不是交互编辑项见 document.json 中sectPr的注释。它就像表格自动分配的id仅为保真而可设真正塑造节布局的是上文这些页面设置属性。3. docDefaults——文档级 run/段落默认值未套样式的段落会继承的默认格式。示例生成文件的正文段落不带任何 run 格式化因此渲染为 Georgia 12pt 深灰——这些值直接来自docDefaults.*而非 run 上的属性officecli set file.docx / \ --prop docDefaults.fontGeorgia --prop docDefaults.font.eastAsiaSimSun \ --prop docDefaults.fontSize12 --prop docDefaults.color2F3640 \ --prop docDefaults.alignmentleft \ --prop docDefaults.spaceAfter8pt --prop docDefaults.lineSpacing1.15x其他可用键docDefaults.bold、docDefaults.italic、docDefaults.rtl、docDefaults.font.hAnsi、docDefaults.font.complexScript、docDefaults.spaceBefore。源码级实现WordHandler.Set.DocDefaults.csdocDefaults.*写入styles.xml的w:docDefaultsrun 侧进w:rPrDefault段落侧进w:pPrDefaultdocDefaults.font一次写满四个槽位ascii/highAnsi/eastAsia/complexScriptdocDefaults.font.latin/.hAnsi/.eastAsia/.complexScript则单槽写入。特别地docDefaults.font.latin的空值会被当作「清除该槽位」——防止 dump→batch 往返时把空白模板自带的 Times New Roman 泄漏进文档代码注释 BUG-R6-05docDefaults.fontSize先经ParseFontSizeToHalfPoints统一走ParseFontSize的共享范围守卫≥0.5pt、≤4000pt再转成 OOXML 的半磅w:sz/w:szCs避免超大值溢出为负docDefaults.rtl写入pPrDefault/w:bidi/——这是 OOXML 校验器认可、Word 自己也会生成的「文档段落默认 RTL」位置旧版本曾写w:rtl/到rPrDefault该位置不被CT_RPrDefault内容模型接受读取时会静默忽略并建议用set docDefaults.rtltrue迁移一次到规范形态布尔与颜色元素通过InsertRunPropBeforeSizeElements保持w:rPrBase的 schema 子元素顺序rFonts → b → i → … → color → sz → szCs读取侧PopulateDocDefaults把w:sz半磅值换算为Npt把w:line按 LineRule 换算为Nxauto 倍数除以 240或Npt精确值除以 20把颜色经FormatHexColor输出为#RRGGBB。4. 主题——调色板与 major/minor 字体主题重映射会按引用而非按值联动所有引用主题的元素样式、图表、形状等全部随之变化。officecli set file.docx / \ --prop theme.color.accent11F6FEB --prop theme.color.accent2E3572A \ --prop theme.color.accent32DA44E --prop theme.color.hlink0969DA officecli set file.docx / \ --prop theme.font.major.latinGeorgia --prop theme.font.minor.latinCalibri \ --prop theme.font.major.eastAsiaSimHei --prop theme.font.minor.eastAsiaSimSun完整调色板键accent1..6、dk1/dk2、lt1/lt2、hlink/folHlink。.sh版本把全部 12 个色槽写满dk11A1A1A、lt1FFFFFF、dk22F3640、lt2EEF1F5、accent1..6、hlink、folHlink并同时设置theme.font.major/minor.latin/eastAsia。这些键定义于 root-metadata.json对应主题部件的a:clrScheme与a:fontSchemeget侧还有只读的theme.colorScheme、theme.fontScheme、theme.formatScheme、theme.name摘要键。示例文档中 Heading 段落使用主题 major 字体Georgia正是「按引用联动」的直观体现。5. CJK 网格与间距officecli set file.docx / \ --prop docGrid.typelines --prop docGrid.linePitch312 \ --prop charSpacingControlcompressPunctuation \ --prop autoSpaceDEtrue --prop autoSpaceDNtrue \ --prop kinsokutrue --prop overflowPuncttruedocGrid.type的合法值default/lines/linesAndChars/snapToCharsschema 与 WordHandler.Set.DocSettings.cs 一致.sh示例用linesAndCharsdocGrid.charSpace设置linesAndChars时的字符网格间距docGrid.linePitch是正的 twips 整数源码中 1直接抛错因为 0/负值会被 Word 静默当作禁用网格docGrid.charSpace则允许负整数——真实 Word 中日文紧排文档常写负值如 -2049源码注释BUG-DUMP-H88 与 CONSISTENCY(docgrid-charspace-signed)说明了此前范围校验过严破坏 CJK 文档往返的问题docGrid.*写入sectPr/w:docGridautoSpaceDE/DN中英/中数自动间距、kinsoku日文禁则处理、overflowPunct标点溢出写入pPrDefaultcharSpacingControl写入settings.xml枚举doNotCompress/compressPunctuation/compressPunctuationAndJapaneseKana注意autoSpaceDE、autoSpaceDN、kinsoku、overflowPunct在 schema 中为get: false仅可设。6. 字体嵌入officecli set file.docx / --prop embedFontstrue --prop embedSystemFontsfalse \ --prop saveSubsetFontstrue分别对应settings.xml的w:embedTrueTypeFonts、w:embedSystemFonts、w:saveSubsetFonts实现于 WordHandler.Set.DocSettings.cs 的 Font Embedding 分支。嵌入可提升跨机渲染一致性代价是文件体积增大saveSubsetFonts只嵌入文档实际用到的字形子集以控制体积。三者同样仅可设get: false。7. 显示 / 打印 / 隐私officecli set file.docx / \ --prop evenAndOddHeaderstrue --prop autoHyphenationfalse \ --prop defaultTabStop720 --prop displayBackgroundShapetrue \ --prop removePersonalInformationfalse --prop removeDateAndTimefalse \ --prop printFormsDatafalsedefaultTabStop720720 twips 0.5 in也接受0.5in这类带单位写法源码对超出short.MaxValue的值直接报错evenAndOddHeaders、autoHyphenation、trackRevisions别名trackChanges即 Word 的「修订模式」开关与revision.type编写修订数据是两回事、updateFields别名updateFieldsOnOpen让 Word 打开时重算 TOC/PAGE/SEQ 等字段缓存均在settings.xml中实现全部开关经泛型SetOnOffSettingT处理值为 true 时确保元素以 schema 正确位置存在AddChild遵循w:settings的元素顺序且大多须在w:compat之前false 时移除。完整属性面一览分组键渲染可见性元数据author、title、subject、keywords、description、lastModifiedBy、extended.company/manager/template否文件属性页面设置pageWidth、pageHeight、orientation、marginTop/Bottom/Left/Right/Header/Footer/Gutter、mirrorMargins、gutterAtTop、bookFoldPrinting是几何docDefaultsdocDefaults.font[.eastAsia/hAnsi/complexScript]、.fontSize、.color、.bold/.italic/.rtl、.alignment、.spaceBefore/.spaceAfter、.lineSpacing是无样式文本主题theme.color.accent1..6/dk1/dk2/lt1/lt2/hlink/folHlink、theme.font.major/minor.latin/eastAsia是主题元素CJK 网格docGrid.type/linePitch/charSpace、charSpacingControl、autoSpaceDE/DN、kinsoku、overflowPunct是CJK 排版字体embedFonts、embedSystemFonts、saveSubsetFonts否可移植性显示/隐私evenAndOddHeaders、autoHyphenation、defaultTabStop、displayBackgroundShape、removePersonalInformation、removeDateAndTime、printFormsData部分完整键列表可用officecli help docx document查看该帮助数据即来自 schemas/help/docx/document.json。其中extended.application、extended.words/pages/paragraphs/lines/characters/totalTime、locale、bookFoldPrintingSheets、doNotDisplayPageBoundaries、columns.*等为只读回读键。Set → Get 往返与规范化document-formatting.py在保存后用doc.send({command: get, path: /})读回容器并打印规范化键得到类似输出author Jane Author pageWidth 21cm pageHeight 29.7cm docDefaults.font Georgia docDefaults.fontSize 12pt theme.color.accent1 #1F6FEB docGrid.type lines注意get侧的规范化颜色统一补#前缀1F6FEB→#1F6FEB见 WordHandler.Set.DocDefaults.cs 的FormatHexColor字号统一加pt单位12→12pt半磅转磅长度统一以cm输出21cm与 section.json 注释中的FormatTwipsToCm行为一致行距按 LineRule 换算为1.15x或Npt。脚本最后还会用全新进程执行officecli validate document-formatting.docx做磁盘级校验确认产物合法。使用要点与边界路径语义所有文档级属性都设在/要更精细地控制某个节的页面几何应改走/section[N]add/set/get/remove全支持/上的页面属性只是对正文最终节sectPr的便捷入口enforcement 均为reportdocument容器的属性以报告式宽松校验为主未知/不支持的键会产生UNSUPPORTED props警告退出码 2而非硬失败这正是两份示例脚本刻意容忍退出码 2 的原因单位宽松长度输入接受 twips 整数或2cm/0.5in/24ptParseTwipsget输出统一规范化只读键category、revisionNumber、created/modified、protection*、extended.words/pages等仅回读不可写docGrid与 CJK 组、字体嵌入组、多数显示开关在get侧不可见set-only。小结document容器把 Word 文档级的全部「全局开关」收敛到一个路径/、一套--prop语法之下从文件元数据到页面几何从无样式文本的 docDefaults 到主题联动再到 CJK 排版与字体嵌入都能用一条set命令完成并通过get以规范化键值读回验证。配合仓库内 schemaschemas/help/docx/document.json与 Word 处理器实现WordHandler.Set.DocDefaults.cs、WordHandler.Set.DocSettings.cs你既可以按示例脚本一键生成文档也可以逐键探索其余属性把 Word 文档的全局格式化能力完整纳入 Agent 自动化流程。赞分享CLIAI 应用MCP 服务【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址https://gitcode.com/GitHub_Trending/of/OfficeCLI点击查看免费下载相关推荐OfficeCLI 实战用 document 容器一次配齐 Word 文档级格式页面、默认字体、主题、CJK 网格与元数据OfficeCLI 实战用 document 容器一次配齐 Word 文档级格式页面、默认字体、主题、CJK 网格与元数据 examples/word/d人工智能AI 应用AI 技能CLIMCP 服务AssetRipper 完整指南5 分钟把游戏二进制资产变成可用 Unity 工程AssetRipper 完整指南5 分钟把游戏二进制资产变成可用 Unity 工程 AssetRipper 是一款免费开源的 Unity 资产提取工具它把游开发工具逆向工程游戏开发大麦智能抢票工具入门一条最短路径跑通 Appium 抢票流程大麦智能抢票工具入门一条最短路径跑通 Appium 抢票流程 ticket purchase 是一个基于 Appium 的大麦网智能抢票工具替你完成搜索演出GUI 自动化RPA上一篇Core Data性能调优通过Moody项目学习内存管理与响应式优化下一篇在Windows上轻松安装Android应用APK-Installer使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考