OfficeCLI 分节实战指南：用 section 命令掌控 Word 多栏、脚注、行号与页面布局

OfficeCLI 分节实战指南用 section 命令掌控 Word 多栏、脚注、行号与页面布局【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI本节展示文档 examples/word/sections.md 是 OfficeCLI 中docx section属性面的权威实战演示它用 CLI 与 Python SDK 两套通道生成了同一个sections.docx覆盖 Word 中没有段落级或 run 级替代品的整页排版能力——多栏布局、脚注/尾注行为、分节页面设置、行号与垂直对齐。读完本文你将掌握 OfficeCLI 的 section 寻址模型/与/section[N]、四类核心命令add/query/get/set以及全部可配置属性的取值与底层 OOXML 映射可以直接把示例改造成自己的多栏杂志页、横向表格页或带行号的审阅文稿。Word 的 section 模型一段内容共享一套页面布局在 Word 的 OOXML 结构中section节是一段共享同一页面布局的内容区间页面尺寸与方向、页边距、分栏、页眉/页脚引用、行号、脚注/尾注行为以及垂直对齐方式。所有这些设置都存放在一个名为sectPrsection properties节属性的元素中。理解 OfficeCLI 的 section 操作必须先掌握两个关键事实一个.docx永远有一条最终节final section——即正文体body级别的sectPr它位于路径/。文档剩余内容都归属于这条节。每次add / --type section都会插入一个分节符section break它把此前已添加的内容收束成一个新的/section[N]这个新节携带自己的sectPr而原本打开的最终节则顺延下去承接之后添加的内容。因此构建多节文档的标准模式是add paragraphs → add section (break) → add paragraphs → add section → …这里有一个容易踩坑的反直觉点你刚添加的那个 section 拥有它上方的所有段落。这正是 sections.sh 中布局add总是出现在它作用到的段落之后的原因——先写正文再落分节符分节符回头接管上面的内容。寻址规则路径是什么支持的操作/section[N]文档中间的分节分节符段落的sectPrgetsetqueryremove/最终尾节body 级别的sectPrgetset拒绝 breaktypeofficecli add file.docx / --type section --prop typenextPage --prop columns2 officecli query file.docx section # list all sections their layout officecli get file.docx /section[1] # read one sections property bag officecli set file.docx /section[1] --prop vAligncenter最终节没有 breaktype路径/指向的尾节之后不再有内容不存在分节符类型。因此set / --prop type…会被拒绝并给出指向/section[N]的可操作错误提示——分节符类型只能在文档中间的分节上设置。这条约束在源码中也有明确体现WordHandler.Set.SectionLayout.cs 对 body 级路径的type/break键直接抛出带指引的ArgumentException。复现示例CLI 与 Python SDK 双通道生成同一文档本节展示由三个文件协同工作sections.sh — 直接用officecli CLI构建文档sections.py — SDK 孪生实现officecli Python SDK生成同一份文档sections.docx — 生成出的成品文档sections.md — 本文对应的展示说明。重新生成cd examples/word bash sections.sh # CLI # or pip install officecli-sdk python3 sections.py # SDK twin # → sections.docx一个值得注意的工程细节sections.sh有意省略了set -e。这与 SDK 孪生实现中的doc.batch行为一致——它容忍向前兼容的UNSUPPORTED props警告此时 officecli 返回退出码 2继续构建出完整的文档而不是中途失败。这对依赖老版本 CLI 跑新属性的 CI 场景非常实用。SDK 侧的实现要点见 sections.py它用para()/section()/footnote()/endnote()四个小工厂函数构造批量指令再通过doc.batch([...])一次性提交其中section()就是向/路径发出{command: add, parent: /, type: section, props: ...}。整个文档只打开一个 resident 进程所有写入通过管道发送最后doc.send({command: save})落盘并用officecli validate校验。实战一双栏排版 页脚脚注nextPage 分节第一个示例构造一个报刊式双栏版心A4 纵向、两栏等宽、栏间 1cm 沟槽、脚注采用小写罗马数字并在每页重新计数。officecli add file.docx / --type section \ --prop typenextPage \ --prop pageWidth21cm --prop pageHeight29.7cm --prop orientationportrait \ --prop marginTop2.54cm --prop marginBottom2.54cm \ --prop marginLeft2.54cm --prop marginRight2.54cm \ --prop marginHeader1.25cm --prop marginFooter1.25cm \ --prop columns2 --prop columnSpace1cm \ --prop titlePagetrue \ --prop footnotePr.numFmtlowerRoman --prop footnotePr.numRestarteachPage \ --prop footnotePr.numStart1 --prop footnotePr.pospageBottom参数语义columns2将正文拆成两栏等宽排版columnSpace是栏间沟槽宽度。add还支持合并写法--prop columns2,1cm栏数加空格一并给出。栏宽的计算规则是(页面宽度 - 左右页边距 - 栏间距) / 栏数。正文要写足够多第一栏填满到底边距后文本才会折入第二栏分栏效果才可见——这正是示例在分节符前堆了 8 段正文的原因。脚注挂在正文段落上按footnotePr.pos指定的位置渲染此处为pageBottom页脚officecli add file.docx /body/p[3] --type footnote --prop textSee note.titlePagetrue为该节启用独立的首页页眉/页脚在 OOXML 中写入w:titlePg/。从 schemas/help/docx/section.json 可以看到完整枚举footnotePr.pos支持pageBottom默认、beneath正文之下与sectEnd节末footnotePr.numRestart支持continuous/eachSect/eachPage。实战二横向单栏 垂直居中 行号第二个示例演示页级布局随节切换的能力同一文档中这一节横向、单栏、非对称页边距、内容垂直居中并开启连续行号——典型的法律文书/手稿审阅版式。officecli add file.docx / --type section \ --prop typenextPage \ --prop orientationlandscape \ --prop pageWidth29.7cm --prop pageHeight21cm \ --prop marginTop2cm --prop marginBottom2cm \ --prop marginLeft3cm --prop marginRight1.5cm \ --prop columns1 \ --prop vAligncenter \ --prop lineNumberscontinuous --prop lineNumberCountBy5 \ --prop lineNumberDistance288 \ --prop pageNumFmtdecimal --prop pageStart1参数语义orientationlandscape会交换页面几何——所以pageWidth/pageHeight要相应地对调29.7cm × 21cm。实际上源码会自动修正不匹配的组合在 WordHandler.Set.SectionLayout.cs 中设置orientation时若宽高比例与方向矛盾会自动交换pgSz的宽高。vAligncenter让较短的正文块垂直居中于页面高度支持top/center/both/bottom四档both表示两端对齐撑满页高。源码中甚至宽容地接受centre/middle拼写见 WordHandler.Set.SectionLayout.cs。lineNumberscontinuous配合lineNumberCountBy5表示每 5 行标一个行号lineNumberDistance288是行号列与正文之间的沟槽宽度单位是twips1 英寸 1440 twips288 twips ≈ 0.5cm。pageNumFmt设置页码格式decimal十进制pageStart设置该节页码起始值。行号的重启模式还有restartPage每页重启与restartSection每节重启或者直接给一个正整数等价于设置countBy并隐含连续模式。实战三连续分节双栏 文末尾注第三个示例引入typecontinuous连续分节符它不弹出新页面就在当前页内切换版式是通栏标题 分栏正文这类杂志结构的经典做法。officecli add file.docx / --type section \ --prop typecontinuous \ --prop orientationportrait \ --prop pageWidth21cm --prop pageHeight29.7cm \ --prop columns2 --prop columnSpace0.8cm \ --prop endnotePr.numFmtupperRoman --prop endnotePr.numRestarteachSect \ --prop endnotePr.numStart1 --prop endnotePr.posdocEnd参数语义typecontinuous与nextPage形成对比后者强制换页前者在上一节所在页面立即切换版式。连续分节符也是在单页内混合栏数的关键——通栏引言 → 连续分节进入双栏 → 再连续分节回到通栏整页一气呵成。尾注像脚注一样挂在正文段落上但收集位置由endnotePr.pos决定sectEnd节末或docEnd文档末尾此处为docEndofficecli add file.docx /body/p[9] --type endnote --prop textEnd reference.endnotePr.numFmtupperRoman大写罗马数字、numRestarteachSect每节重新计数、numStart1起始值。完整的 section 属性面下表汇总了section支持的全部属性分组完整列表见officecli help docx section分组键渲染可见分节符类型typenextPage/continuous/evenPage/oddPage/nextColumn是页面/栏流向页面设置pageWidth、pageHeight、orientation、marginTop/Bottom/Left/Right/Header/Footer/Gutter是几何分栏columns、columnSpace是多栏流向垂直对齐vAligntop/center/both/bottom是块位置行号lineNumbers、lineNumberCountBy、lineNumberDistance是页边数字页码pageNumFmt、pageStart是域内显示首页titlePage是首页页眉/页脚脚注footnotePr.numFmt、.numRestart、.numStart、.pos是注释行为尾注endnotePr.numFmt、.numRestart、.numStart、.pos是注释行为RTLdirection、rtlGutter、textDirection是阅读顺序页面边框pgBorders[.top/left/bottom/right/offsetFrom/zOrder/display]是边框纸张来源paperSrc.first、paperSrc.other否打印机纸盒只读回读headerRef[.default/first/even]、footerRef[…]、colSpaces、columns.equalWidth、columns.separator—仅getget-only 键的说明columns.equalWidth与columns.separator栏间垂直分隔线会在get/dump时呈现但不能通过--prop设置——分隔线需要 raw-XML 编辑。headerRef/footerRef各节页眉/页脚部件路径与colSpaces每栏独立间距覆盖值同样只是回读便利项不是输入项。值得注意的是源码层面存在一点微妙差异WordHandler.Set.SectionLayout.cs 中确实实现了columns.equalwidth与columns.separator的 set 分支保证 dump→batch 回放不丢非等宽栏布局但 schemas/help/docx/section.json 将其声明为只读add: false, set: false, get: true展示文档也明确建议栏分隔线走 raw-XML——日常使用请以--prop之外的方式处理这两项。页面边框与纸张来源补充除展示文档之外schema 还揭示了更多可写属性pgBorders支持box四边 4pt 细线实框/none简写也支持逐边形式pgBorders.topSTYLE[;SIZE[;COLOR[;SPACE]]]SIZE 以 1/8 磅或带单位长度表示SPACE 为距页边 twips配合offsetFrompage/text、zOrderfront/back、displayallPages/firstPage/notFirstPage控制边框位置与呈现页paperSrc.first/paperSrc.other对应打印机纸盒 ID0–65535仅影响物理打印。底层实现源码中的 section 处理链路属性 Schema一切命令的来源schemas/help/docx/section.json 是 section 命令的元数据定义element为section别名sectionbreak父节点body支持add/set/get/query/remove全部五类操作位置寻址支持[/section[N], /body/sectPr[N]]两种写法长度属性的输入非常宽容接受裸 twips 整数也接受2cm/0.5in/24pt等带单位写法经ParseTwips解析而回读统一规范为cm经FormatTwipsToCm。每个属性还标注了enforcement等级strict严格校验、非法值报错与report宽松、仅提示。几个高频属性的取值细节均以 schema 为准typenextPage/continuous/evenPage/oddPage/nextColumn别名覆盖next/newPage/page/even/odd/column等另有属性别名breakpageNumFmt除decimal/lowerRoman/upperRoman/lowerLetter/upperLetter外还支持hindiNumbers阿拉伯文文档常用的 ٠١٢٣ Indic-Arabic 数字、arabicAlpha、arabicAbjad、chineseCounting、japaneseCounting、koreanCounting、ideographDigital等本地化格式directionltr/rtl写入w:bidi/rtlGutter右侧装订线textDirection东亚竖排流向lrTb/tbRl/btLr等六种共同构成 RTL/竖排文档的节级支持pageStart可用none/off清除vAlign可用none/off清除marginGutter对应 pgMar 的gutter装订线宽度。Set 端节级布局的统一分派WordHandler.Set.SectionLayout.cs 是节布局属性的集中实现TrySetSectionLayout从中可以读到大量硬性约束与设计取舍分栏数 1–45columns.count/columns解析后必须落在1..45区间这是 OOXMLCT_Columns/num的MaxInclusive45限制L22-L33、L314-L334简写columns支持3或3,720720 twips ≈ 1.27cm 沟槽未显式给出沟槽时默认720等宽栏是隐式的只要w:col子元素没有显式宽度OOXML 规范就默认等宽因此源码刻意不自动盖章equalWidth以保证 dump→batch 回放保留源文件的原生形状orientation 自动换宽高如前所述设置方向时若宽高与方向矛盾会自动交换L293-L311缺省几何回退到 A4 默认值11906 × 16838twips见 WordPageDefaults.cs210mm × 297mm 1440 twips/inch脚注/尾注三路共用TrySetFootnoteEndnoteNumProps是静态方法被 body 级set /、分节级set /section[N]与add section三条路径共用L702-L781容器w:footnotePr/w:endnotePr按CT_SectPr模式顺序插在w:type之前rank 2/3set / --prop type…被拦截并给出指引L445-L451这正是展示文档强调的最终节没有分节符类型的代码级保障此外还支持chapStyle/chapSep章节页码前缀、lineNumberStart起始行号、formProt表单保护、noEndnote抑制节末尾注以及revision.*sectPrChange格式修订标记。Add 端分节符就是带 sectPr 的段落从 WordHandler.Add.Structure.cs 可以看到AddSection的实现本质分节符是一个在断点位置插入的段落其段落属性里挂着一个SectionProperties。新节不显式指定orientation时不会继承 body 尾节的横向标志避免把末节方向串到中间节几何默认回退 A4empty/bare 模式的节dump 回放场景则不盖章w:type忠实保留源文件没有分节符类型的原生形状。Get/Query 端寻址、回读与规范化WordHandler.Query.cs 中/section[N]的解析支持大小写不敏感且支持/section[last()]定位最后一节FindSectionProperties收集的是段落级 sectPr中间节 body 级 sectPr尾节若文档完全没有 sectPr 则补一个隐式节L1277-L1297。回读时get输出 schema 规范键columns/columnSpace长度统一FormatTwipsToCm为带单位 cm非等宽栏则输出逗号分隔的colWidths/colSpaces列表L1181-L1198。验证与回读检查生成结果文档生成后用一组只读命令核对每个节的布局officecli query sections.docx section # list every section layout officecli get sections.docx /section[1] # two-column footnotePr.* officecli get sections.docx /section[2] # landscape vAlign line nums officecli get sections.docx /section[3] # continuous endnotePr.* officecli get sections.docx / # final trailing section回读规范化normalization值得注意长度值回读为带单位的 cm如21cm枚举值回读为其 OOXML 内部文本如lowerRoman、center——这与 schema 中readback字段的声明完全一致。sections.py的收尾部分还演示了 SDK 侧的回读验证sections.py对四个路径逐一doc.send({command: get, ...})从format字典中抽取type/orientation/columns/footnotePr.numFmt/endnotePr.numFmt/lineNumbers等键打印再通过独立的officecli validate sections.docx进程做整体校验。小结OfficeCLI 的docx section属性面把 Word 中最整页级的排版能力——分栏、脚注/尾注、横向切换、行号、垂直对齐、页码格式、RTL 与页面边框——浓缩为一行行可复现的--prop命令。理解先写段落、后落分节符分节符拥有上方内容的构建模式以及/section[N]与/的寻址分工就能用同一份脚本自由拼装任意复杂的多节文档。深入 schemas/help/docx/section.json 与 WordHandler.Set.SectionLayout.cs 的源码还可以进一步掌握每个属性的取值边界与 OOXML 映射为自定义模板和批量文档流水线提供精确控制。【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考