OfficeCLI 内容控件Content Controls完全指南用 CLI 与 Python SDK 构建 Word 可填写表单【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI导读本文以 OfficeCLI 仓库中的 examples/word/content-controls.md 为核心骨架系统讲解如何用 OfficeCLI 的add/set/get/query命令操作 docx 的sdtStructured Document Tag结构化文档标签即 Word 内容控件属性面把普通 Word 文档改造成带可填写表单区域的员工信息录入表单。读完本文你将掌握 8 种内容控件文本框、下拉列表、组合框、日期选择器、图片占位符、富文本、分组、复选框的创建参数、共享属性、锁定语义以及创建后如何修改与回读验证——既能直接用命令行完成也能通过officecli-sdkPython 包以编程方式批量生成。什么是sdt内容控件就是 Word 的表单字段在 OOXML 文档模型中内容控件对应的 XML 元素是w:sdtStructured Document Tag。Word 把它渲染为一个有边界、被当作单一可填写区域的灰色框用户点击后即可输入或选择而整个区域在逻辑上是一个整体方便后续做数据绑定、模板替换与自动化处理。OfficeCLI 在 docx 中把内容控件建模为sdt节点其完整的属性定义见 schemas/help/docx/sdt.json。sdt有两种层级块级block-level添加在/body下包裹整个段落本文示例即为此类行内inline添加在/body/p[N]下包裹段落内的 runs例如段落中间的Video [sdt] a powerful…。sdt的别名是contentcontrol两种写法均可。在源码中块级与行内分别由SdtBlock与SdtRun承载见 WordHandler.Add.Misc.csisInline parent is Paragraph。快速上手创建、查询、读取一个内容控件一个块级sdt被添加到/body下之后可以通过稳定的带sdtId路径/body/sdt[sdtIdN]回读位置路径/body/sdt[N]同样可用officecli add file.docx /body --type sdt --prop typetext --prop aliasFull Name officecli query file.docx sdt # list every control with its props officecli get file.docx /body/sdt[1] # read one controls property bagquery sdt一行输出一个控件及其全部属性get读取单个控件的完整属性包。一个需要特别牢记的约束内容控件的type在创建后不可更改。text/richtext/dropdown/combobox/date/picture/group/checkbox都可以在 add 时直接创建而buildingBlockGallery构建基块库与repeatingSection重复节两种类型尚未在 add 时实现——需要先在 Word 中创建这类控件再用 CLI 编辑。这与 Schema 中type属性add: true, set: false的定义以及源码 WordHandler.Add.Misc.cs 中supportedSdtTypes白名单text/plaintext/richtext/rich/dropdown/dropdownlist/combobox/combo/date/datepicker/group/picture/checkbox一致传入白名单之外的类型会抛出NotSupportedException提示请在 Word 中创建控件后通过 CLI 编辑。兼容性提示源码还保留了sdttype、controltype两个旧别名与规范键type等价name可作alias的别名choices可作items的别名方便自然拼写。重新生成示例文档本示例由三个文件协同工作examples/word/content-controls.py —— 通过officecli Python SDK构建文档examples/word/content-controls.sh ——CLI 孪生脚本产出随仓库分发的.docxexamples/word/content-controls.docx —— 生成结果一份小型员工入职表单。重新生成cd examples/word pip install officecli-sdk python3 content-controls.py # 或: bash content-controls.sh # → content-controls.docxSDK 驱动方式基于officecli-sdk包sdk/python启动一个常驻resident进程通过管道发送命令当包未 pip 安装时脚本会回退到仓库内的 SDK 副本见 content-controls.py 的ImportError处理。SDK 侧的核心写法是with officecli.create(FILE, --force) as doc:配合doc.batch([...])批量提交命令每个命令是一条{command: add, parent: /body, type: sdt, props: {...}}字典。需要留意content-controls.sh故意不设置set -e——与 SDK 孪生脚本的doc.batch一样它容忍前向兼容性的UNSUPPORTED props警告officecli 退出码 2继续构建以产出完整文档。8 种内容控件一览#类型用途类型专属属性1text(plainText)单行文本字段text初始/占位内容2dropdown单选、禁止自由输入items、dropDown.lastValue3combobox单选或自由输入itemsdisplay\|value形式、comboBox.lastValue4date日历选择器format、date.fullDate/calendar/lid/storeMappedDataAs5picture图片插入占位符—6richtext支持格式化的多 run 字段text7group锁定分组包装器—8checkbox复选框开关☒/☐checkedtrue/false共享属性每个控件类型都可用所有内容控件共享一套基础属性。以最典型的文本控件为例officecli add file.docx /body --type sdt --prop typetext \ --prop aliasFull Name \ # Word 中显示的人类可读标签 --prop tagfullName \ # 机器可读的数据绑定键 --prop text[Enter full legal name] \ # 初始 / 占位内容 --prop lockunlocked \ # unlocked | contentLocked | sdtLocked | sdtContentLocked --prop placeholderTextDefaultPlaceholder # docPart 库引用各共享属性的语义依据 schemas/help/docx/sdt.jsonaliasWord 界面上显示的名称对应w:alias。tag数据绑定用的机器可读键对应w:tag常用于后续与 XML 数据存储关联。text占位/初始内容读取回读时为拼接后的文本。placeholderText占位内容的 docPart 库引用写入w:placeholderw:docPart w:val...//w:placeholder。注意它与text是两回事placeholderText引用 Word 内置的占位符部件名称示例中为DefaultPlaceholder而text是真正写入的初始文本。placeholder布尔为true表示控件当前正显示其占位文本写入w:showingPlcHdr/。lock锁定语义对应w:lock元素unlocked默认完全开放contentLocked冻结内容回读时editablefalsesdtLocked禁止删除该控件sdtContentLocked上述两者兼备。id只读回读键OOXML 的SdtId值即稳定路径中sdtId的来源。editable只读回读键false当且仅当lock为contentLocked或sdtContentLocked。源码 WordHandler.Add.Misc.cs 显示lock还接受更宽松的别名content/sdt/both/none分别映射到四个锁定值非法值直接抛出ArgumentException。各类型专属属性详解2 3. dropDown / comboBox选择列表# dropDown只能选择禁止自由输入 officecli add file.docx /body --type sdt --prop typedropdown \ --prop aliasDepartment --prop tagdepartment \ --prop itemsSales,Engineering,Human Resources,Finance,Operations \ --prop dropDown.lastValueEngineering # comboBox同样可选但用户还可以输入列表中不存在的值。 # items 支持 display|value 形式当存储值与显示标签不同时使用。 officecli add file.docx /body --type sdt --prop typecombobox \ --prop aliasOffice Location --prop tagoffice \ --prop itemsNew York|NYC,London|LON,Singapore|SIN,Remote|REMOTE \ --prop comboBox.lastValueLONitems逗号分隔的选项列表每个条目要么是display要么是display|value显示标签与存储值分离。对应的 OOXML 是w:listItem w:displayText... w:value.../列表由源码ParseSdtItems解析生成WordHandler.Add.Misc.cs。dropDown.lastValue/comboBox.lastValue当前选中的存储值分别写入w:dropDownList w:lastValue.../与w:comboBox w:lastValue.../。在 Schema 中两者语义一致set会整体替换选项列表并保留lastValue见 schemas/help/docx/sdt.json 中items的说明。提示若选项条目多、含逗号或管道符CLI 中务必用引号包裹整个items值避免 shell 拆分。4. date日历选择器officecli add file.docx /body --type sdt --prop typedate \ --prop aliasStart Date --prop tagstartDate \ --prop formatyyyy-MM-dd \ --prop date.fullDate2026-02-01T00:00:00Z \ --prop date.calendargregorian --prop date.liden-US \ --prop date.storeMappedDataAsdateTimeformat显示掩码对应w:dateFormat w:val.../。源码显示若省略则默认yyyy-MM-ddWordHandler.Add.Misc.cs。date.fullDate实际选中的日期值ISO-8601 UTC对应w:fullDate与显示掩码是两个独立概念——一个控制显示格式一个记录真实取值。date.calendar日历系统w:calendar如gregorian公历、hijri伊斯兰历、japan日本和历。date.lid语言区域 IDw:lid如en-US影响选择器的本地化显示。date.storeMappedDataAsXML 映射时的存储类型w:storeMappedDataAs可取dateTime/date/text。5. picture图片占位符officecli add file.docx /body --type sdt --prop typepicture \ --prop aliasProfile Photo --prop tagphotopicture类型的控件在 Word 中显示为图片插入占位符用户在 Word 里点击后可从本地插入图片。OOXML 层面它对应sdtPr中一个空的w:picture/标记源码 WordHandler.Add.Misc.cs。alias/tag等共享属性照常生效。6. richText格式化富文本字段officecli add file.docx /body --type sdt --prop typerichtext \ --prop aliasReviewer Notes --prop tagnotes \ --prop textManager may add formatted commentary here. \ --prop lockcontentLockedrichtext允许在控件内部进行加粗、变色等多 run 格式化编辑。OOXML 层面它没有专属的类型元素——sdtPr中缺省w:text/即表示富文本源码注释Rich text has no specific type element (absence of w:text means rich text)见 WordHandler.Add.Misc.cs。此处lockcontentLocked冻结内容回读时editablefalse适合审阅者只能看不能改的场景。7. group锁定分组包装器officecli add file.docx /body --type sdt --prop typegroup \ --prop aliasApproval Block --prop tagapproval \ --prop textApproved by HR — signature on file. \ --prop locksdtContentLockedgroup把一组内容包装成单个单元整体作为一个控件对待。OOXML 层面对应sdtPr中空的w:group/标记源码 WordHandler.Add.Misc.cs。这里配合locksdtContentLocked实现既禁止删除该控件也禁止编辑其内容的双重保护——适合审批签章块这类需要完整保真的区域。8. checkbox真正的 Word 复选框控件这是与普通文本字符最不同的一个类型OfficeCLI 能生成Word 原生复选框内容控件而不仅仅是一个 ☒/☐ 字符。checkedtrue渲染 ☒U2612checkedfalse渲染 ☐U2610)选中状态作为w14:checkbox标记存储在控件的sdtPr中。get读取时会返回typecheckbox和checked。officecli add file.docx /body --type sdt --prop typecheckbox \ --prop aliasApproved --prop taghrApproved \ --prop checkedtrue源码实现值得关注WordHandler.Add.Misc.cs 与BuildSdtCheckBox通过BuildSdtCheckBox构造w14:checkbox标记包含 checked 标志以及选中/未选中两种盒形字符状态字符使用MS Gothic字体承载2612/2610字形当未显式提供text时控件的内容 run 会自动以盒形字符播种☒/☐复选框控件本身没有w:text/元素w:text的存在意味着纯文本控件因此内容区域允许直接渲染盒形符号。创建后修改setalias、tag、lock、text都是可设置settable的。而类型专属属性dropDown.lastValue、comboBox.lastValue、items、format、date.*、placeholderText是add/get-only的——创建时设置、get时回读但不能通过set修改officecli set file.docx /body/sdt[2] --prop aliasHome Department --prop locksdtLocked上例把第 2 个控件Department 下拉列表的 Word 标签改为 Home Department并锁定为sdtLocked禁止删除。这与 Schema 中每个属性的add/set/get能力标记一一对应如type为add:true, set:false而alias/tag/lock/text为set:true参见 schemas/help/docx/sdt.json。例外checked与format、items在 Schema 中标为set: truechecked的set会重绘盒形字符。实际以officecli help docx sdt的完整清单为准——文档明确提示Full list:officecli help docx sdt。检查与回读验证生成文档后用query和get验证每个控件的规范属性是否按预期回读officecli query content-controls.docx sdt # one line per control officecli get content-controls.docx /body/sdt[1]示例文档content-controls.docx的实际回读输出节选/body/sdt[sdtId1] (sdt) [Enter full legal name] aliasFull Name tagfullName lockunlocked typetext editabletrue placeholderTextDefaultPlaceholder /body/sdt[sdtId2] (sdt) aliasHome Department tagdepartment locksdtLocked typedropdown itemsSales,Engineering,Human Resources,Finance,Operations dropDown.lastValueEngineering /body/sdt[sdtId4] (sdt) aliasStart Date tagstartDate typedate formatyyyy-MM-dd date.fullDate2026-02-01T00:00:00Z date.calendargregorian date.liden-US date.storeMappedDataAsdateTime /body/sdt[sdtId6] (sdt) Manager may add formatted commentary here. aliasReviewer Notes tagnotes lockcontentLocked typerichtext editablefalse要点稳定路径用sdtIdid是只读回读键构成/body/sdt[sdtIdN]的稳定寻址位置路径/body/sdt[N]也可用但插入/删除其他控件后位置会漂移sdtId更稳健。editable是lock的镜像lockcontentLocked或sdtContentLocked时editablefalse其余为true——它和id一样是只读的不能通过set写入。SDK 侧的完整往返验证参见 content-controls.py循环对/body/sdt[1]到/body/sdt[8]逐个get打印type/alias/tag/lock/checked最后在一个全新进程中执行officecli validate content-controls.docx校验文档合法性。源码视角sdt的底层实现与往返保障从源码结构看OfficeCLI 对内容控件做了相当完整的读写一致保障值得作为理解其能力的注脚创建入口所有add --type sdt含别名contentcontrol统一派发到AddSdtWordHandler.Add.Misc.cs。该方法除构建标准控件外还提供sdtXml载体通道——dump 出的复杂块级内容控件如带锚定文本框和 Logo 图片的封面页可整体原样注入并在段落宿主下自动切换为SdtRun行内形态。嵌套保护AddSdt在写入前会向上遍历祖先链若发现外层是纯文本控件sdtPr/w:text/直接拒绝嵌套——因为外层将内容标记为纯文本嵌套 SDT 会产生 Word 拒绝接受的 OOXML错误 0x422。往返保真在批量发射端WordBatchEmitter.Resources.cs 的SdtTypedEmitKeys白名单type/alias/tag/lock/text/checked/items/dropDown.lastValue/comboBox.lastValue/format/date.*/placeholder/placeholderText等规范键被逐一转发确保dump → batch循环不丢失控件类型与选中状态行内 SDT 还按源文档 rank 排序发射避免内容控件在段落中的顺序被打乱WordBatchEmitter.Paragraph.cs。完整示例员工入职表单的构建脉络把以上知识点串起来content-controls.py或等价的content-controls.sh构建的content-controls.docx是一份完整的员工入职表单按顺序包含标题 副标题Title/Subtitle样式段落Full name——typetext占位文本[Enter full legal name]placeholderTextDefaultPlaceholderDepartment——typedropdown5 个部门选项dropDown.lastValueEngineeringPrimary office——typecomboboxdisplay|value形式的 4 个办公地选项comboBox.lastValueLONStart date——typedateformatyyyy-MM-dddate.fullDate2026-02-01T00:00:00ZProfile photo——typepicture图片占位符Reviewer notes——typerichtextlockcontentLocked冻结内容Approval——typegrouplocksdtContentLocked双重锁定HR approved——typecheckboxcheckedtrue渲染 ☒创建后通过set把第 2 个控件改名为 Home Department 并加sdtLocked演示创建后可修改。这份表单覆盖了内容控件在真实人事/审批场景中的典型用法数据录入文本、日期、受控选择下拉、组合框、富文本批注、图片上传占位、分组保护与布尔审批。读者可直接把content-controls.py的sdt()/para()辅助函数作为模板替换属性即可生成自己的表单文档。【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OfficeCLI 内容控件（Content Controls）完全指南：用 CLI 与 Python SDK 构建 Word 可填写表单
OfficeCLI 内容控件Content Controls完全指南用 CLI 与 Python SDK 构建 Word 可填写表单【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI导读本文以 OfficeCLI 仓库中的 examples/word/content-controls.md 为核心骨架系统讲解如何用 OfficeCLI 的add/set/get/query命令操作 docx 的sdtStructured Document Tag结构化文档标签即 Word 内容控件属性面把普通 Word 文档改造成带可填写表单区域的员工信息录入表单。读完本文你将掌握 8 种内容控件文本框、下拉列表、组合框、日期选择器、图片占位符、富文本、分组、复选框的创建参数、共享属性、锁定语义以及创建后如何修改与回读验证——既能直接用命令行完成也能通过officecli-sdkPython 包以编程方式批量生成。什么是sdt内容控件就是 Word 的表单字段在 OOXML 文档模型中内容控件对应的 XML 元素是w:sdtStructured Document Tag。Word 把它渲染为一个有边界、被当作单一可填写区域的灰色框用户点击后即可输入或选择而整个区域在逻辑上是一个整体方便后续做数据绑定、模板替换与自动化处理。OfficeCLI 在 docx 中把内容控件建模为sdt节点其完整的属性定义见 schemas/help/docx/sdt.json。sdt有两种层级块级block-level添加在/body下包裹整个段落本文示例即为此类行内inline添加在/body/p[N]下包裹段落内的 runs例如段落中间的Video [sdt] a powerful…。sdt的别名是contentcontrol两种写法均可。在源码中块级与行内分别由SdtBlock与SdtRun承载见 WordHandler.Add.Misc.csisInline parent is Paragraph。快速上手创建、查询、读取一个内容控件一个块级sdt被添加到/body下之后可以通过稳定的带sdtId路径/body/sdt[sdtIdN]回读位置路径/body/sdt[N]同样可用officecli add file.docx /body --type sdt --prop typetext --prop aliasFull Name officecli query file.docx sdt # list every control with its props officecli get file.docx /body/sdt[1] # read one controls property bagquery sdt一行输出一个控件及其全部属性get读取单个控件的完整属性包。一个需要特别牢记的约束内容控件的type在创建后不可更改。text/richtext/dropdown/combobox/date/picture/group/checkbox都可以在 add 时直接创建而buildingBlockGallery构建基块库与repeatingSection重复节两种类型尚未在 add 时实现——需要先在 Word 中创建这类控件再用 CLI 编辑。这与 Schema 中type属性add: true, set: false的定义以及源码 WordHandler.Add.Misc.cs 中supportedSdtTypes白名单text/plaintext/richtext/rich/dropdown/dropdownlist/combobox/combo/date/datepicker/group/picture/checkbox一致传入白名单之外的类型会抛出NotSupportedException提示请在 Word 中创建控件后通过 CLI 编辑。兼容性提示源码还保留了sdttype、controltype两个旧别名与规范键type等价name可作alias的别名choices可作items的别名方便自然拼写。重新生成示例文档本示例由三个文件协同工作examples/word/content-controls.py —— 通过officecli Python SDK构建文档examples/word/content-controls.sh ——CLI 孪生脚本产出随仓库分发的.docxexamples/word/content-controls.docx —— 生成结果一份小型员工入职表单。重新生成cd examples/word pip install officecli-sdk python3 content-controls.py # 或: bash content-controls.sh # → content-controls.docxSDK 驱动方式基于officecli-sdk包sdk/python启动一个常驻resident进程通过管道发送命令当包未 pip 安装时脚本会回退到仓库内的 SDK 副本见 content-controls.py 的ImportError处理。SDK 侧的核心写法是with officecli.create(FILE, --force) as doc:配合doc.batch([...])批量提交命令每个命令是一条{command: add, parent: /body, type: sdt, props: {...}}字典。需要留意content-controls.sh故意不设置set -e——与 SDK 孪生脚本的doc.batch一样它容忍前向兼容性的UNSUPPORTED props警告officecli 退出码 2继续构建以产出完整文档。8 种内容控件一览#类型用途类型专属属性1text(plainText)单行文本字段text初始/占位内容2dropdown单选、禁止自由输入items、dropDown.lastValue3combobox单选或自由输入itemsdisplay\|value形式、comboBox.lastValue4date日历选择器format、date.fullDate/calendar/lid/storeMappedDataAs5picture图片插入占位符—6richtext支持格式化的多 run 字段text7group锁定分组包装器—8checkbox复选框开关☒/☐checkedtrue/false共享属性每个控件类型都可用所有内容控件共享一套基础属性。以最典型的文本控件为例officecli add file.docx /body --type sdt --prop typetext \ --prop aliasFull Name \ # Word 中显示的人类可读标签 --prop tagfullName \ # 机器可读的数据绑定键 --prop text[Enter full legal name] \ # 初始 / 占位内容 --prop lockunlocked \ # unlocked | contentLocked | sdtLocked | sdtContentLocked --prop placeholderTextDefaultPlaceholder # docPart 库引用各共享属性的语义依据 schemas/help/docx/sdt.jsonaliasWord 界面上显示的名称对应w:alias。tag数据绑定用的机器可读键对应w:tag常用于后续与 XML 数据存储关联。text占位/初始内容读取回读时为拼接后的文本。placeholderText占位内容的 docPart 库引用写入w:placeholderw:docPart w:val...//w:placeholder。注意它与text是两回事placeholderText引用 Word 内置的占位符部件名称示例中为DefaultPlaceholder而text是真正写入的初始文本。placeholder布尔为true表示控件当前正显示其占位文本写入w:showingPlcHdr/。lock锁定语义对应w:lock元素unlocked默认完全开放contentLocked冻结内容回读时editablefalsesdtLocked禁止删除该控件sdtContentLocked上述两者兼备。id只读回读键OOXML 的SdtId值即稳定路径中sdtId的来源。editable只读回读键false当且仅当lock为contentLocked或sdtContentLocked。源码 WordHandler.Add.Misc.cs 显示lock还接受更宽松的别名content/sdt/both/none分别映射到四个锁定值非法值直接抛出ArgumentException。各类型专属属性详解2 3. dropDown / comboBox选择列表# dropDown只能选择禁止自由输入 officecli add file.docx /body --type sdt --prop typedropdown \ --prop aliasDepartment --prop tagdepartment \ --prop itemsSales,Engineering,Human Resources,Finance,Operations \ --prop dropDown.lastValueEngineering # comboBox同样可选但用户还可以输入列表中不存在的值。 # items 支持 display|value 形式当存储值与显示标签不同时使用。 officecli add file.docx /body --type sdt --prop typecombobox \ --prop aliasOffice Location --prop tagoffice \ --prop itemsNew York|NYC,London|LON,Singapore|SIN,Remote|REMOTE \ --prop comboBox.lastValueLONitems逗号分隔的选项列表每个条目要么是display要么是display|value显示标签与存储值分离。对应的 OOXML 是w:listItem w:displayText... w:value.../列表由源码ParseSdtItems解析生成WordHandler.Add.Misc.cs。dropDown.lastValue/comboBox.lastValue当前选中的存储值分别写入w:dropDownList w:lastValue.../与w:comboBox w:lastValue.../。在 Schema 中两者语义一致set会整体替换选项列表并保留lastValue见 schemas/help/docx/sdt.json 中items的说明。提示若选项条目多、含逗号或管道符CLI 中务必用引号包裹整个items值避免 shell 拆分。4. date日历选择器officecli add file.docx /body --type sdt --prop typedate \ --prop aliasStart Date --prop tagstartDate \ --prop formatyyyy-MM-dd \ --prop date.fullDate2026-02-01T00:00:00Z \ --prop date.calendargregorian --prop date.liden-US \ --prop date.storeMappedDataAsdateTimeformat显示掩码对应w:dateFormat w:val.../。源码显示若省略则默认yyyy-MM-ddWordHandler.Add.Misc.cs。date.fullDate实际选中的日期值ISO-8601 UTC对应w:fullDate与显示掩码是两个独立概念——一个控制显示格式一个记录真实取值。date.calendar日历系统w:calendar如gregorian公历、hijri伊斯兰历、japan日本和历。date.lid语言区域 IDw:lid如en-US影响选择器的本地化显示。date.storeMappedDataAsXML 映射时的存储类型w:storeMappedDataAs可取dateTime/date/text。5. picture图片占位符officecli add file.docx /body --type sdt --prop typepicture \ --prop aliasProfile Photo --prop tagphotopicture类型的控件在 Word 中显示为图片插入占位符用户在 Word 里点击后可从本地插入图片。OOXML 层面它对应sdtPr中一个空的w:picture/标记源码 WordHandler.Add.Misc.cs。alias/tag等共享属性照常生效。6. richText格式化富文本字段officecli add file.docx /body --type sdt --prop typerichtext \ --prop aliasReviewer Notes --prop tagnotes \ --prop textManager may add formatted commentary here. \ --prop lockcontentLockedrichtext允许在控件内部进行加粗、变色等多 run 格式化编辑。OOXML 层面它没有专属的类型元素——sdtPr中缺省w:text/即表示富文本源码注释Rich text has no specific type element (absence of w:text means rich text)见 WordHandler.Add.Misc.cs。此处lockcontentLocked冻结内容回读时editablefalse适合审阅者只能看不能改的场景。7. group锁定分组包装器officecli add file.docx /body --type sdt --prop typegroup \ --prop aliasApproval Block --prop tagapproval \ --prop textApproved by HR — signature on file. \ --prop locksdtContentLockedgroup把一组内容包装成单个单元整体作为一个控件对待。OOXML 层面对应sdtPr中空的w:group/标记源码 WordHandler.Add.Misc.cs。这里配合locksdtContentLocked实现既禁止删除该控件也禁止编辑其内容的双重保护——适合审批签章块这类需要完整保真的区域。8. checkbox真正的 Word 复选框控件这是与普通文本字符最不同的一个类型OfficeCLI 能生成Word 原生复选框内容控件而不仅仅是一个 ☒/☐ 字符。checkedtrue渲染 ☒U2612checkedfalse渲染 ☐U2610)选中状态作为w14:checkbox标记存储在控件的sdtPr中。get读取时会返回typecheckbox和checked。officecli add file.docx /body --type sdt --prop typecheckbox \ --prop aliasApproved --prop taghrApproved \ --prop checkedtrue源码实现值得关注WordHandler.Add.Misc.cs 与BuildSdtCheckBox通过BuildSdtCheckBox构造w14:checkbox标记包含 checked 标志以及选中/未选中两种盒形字符状态字符使用MS Gothic字体承载2612/2610字形当未显式提供text时控件的内容 run 会自动以盒形字符播种☒/☐复选框控件本身没有w:text/元素w:text的存在意味着纯文本控件因此内容区域允许直接渲染盒形符号。创建后修改setalias、tag、lock、text都是可设置settable的。而类型专属属性dropDown.lastValue、comboBox.lastValue、items、format、date.*、placeholderText是add/get-only的——创建时设置、get时回读但不能通过set修改officecli set file.docx /body/sdt[2] --prop aliasHome Department --prop locksdtLocked上例把第 2 个控件Department 下拉列表的 Word 标签改为 Home Department并锁定为sdtLocked禁止删除。这与 Schema 中每个属性的add/set/get能力标记一一对应如type为add:true, set:false而alias/tag/lock/text为set:true参见 schemas/help/docx/sdt.json。例外checked与format、items在 Schema 中标为set: truechecked的set会重绘盒形字符。实际以officecli help docx sdt的完整清单为准——文档明确提示Full list:officecli help docx sdt。检查与回读验证生成文档后用query和get验证每个控件的规范属性是否按预期回读officecli query content-controls.docx sdt # one line per control officecli get content-controls.docx /body/sdt[1]示例文档content-controls.docx的实际回读输出节选/body/sdt[sdtId1] (sdt) [Enter full legal name] aliasFull Name tagfullName lockunlocked typetext editabletrue placeholderTextDefaultPlaceholder /body/sdt[sdtId2] (sdt) aliasHome Department tagdepartment locksdtLocked typedropdown itemsSales,Engineering,Human Resources,Finance,Operations dropDown.lastValueEngineering /body/sdt[sdtId4] (sdt) aliasStart Date tagstartDate typedate formatyyyy-MM-dd date.fullDate2026-02-01T00:00:00Z date.calendargregorian date.liden-US date.storeMappedDataAsdateTime /body/sdt[sdtId6] (sdt) Manager may add formatted commentary here. aliasReviewer Notes tagnotes lockcontentLocked typerichtext editablefalse要点稳定路径用sdtIdid是只读回读键构成/body/sdt[sdtIdN]的稳定寻址位置路径/body/sdt[N]也可用但插入/删除其他控件后位置会漂移sdtId更稳健。editable是lock的镜像lockcontentLocked或sdtContentLocked时editablefalse其余为true——它和id一样是只读的不能通过set写入。SDK 侧的完整往返验证参见 content-controls.py循环对/body/sdt[1]到/body/sdt[8]逐个get打印type/alias/tag/lock/checked最后在一个全新进程中执行officecli validate content-controls.docx校验文档合法性。源码视角sdt的底层实现与往返保障从源码结构看OfficeCLI 对内容控件做了相当完整的读写一致保障值得作为理解其能力的注脚创建入口所有add --type sdt含别名contentcontrol统一派发到AddSdtWordHandler.Add.Misc.cs。该方法除构建标准控件外还提供sdtXml载体通道——dump 出的复杂块级内容控件如带锚定文本框和 Logo 图片的封面页可整体原样注入并在段落宿主下自动切换为SdtRun行内形态。嵌套保护AddSdt在写入前会向上遍历祖先链若发现外层是纯文本控件sdtPr/w:text/直接拒绝嵌套——因为外层将内容标记为纯文本嵌套 SDT 会产生 Word 拒绝接受的 OOXML错误 0x422。往返保真在批量发射端WordBatchEmitter.Resources.cs 的SdtTypedEmitKeys白名单type/alias/tag/lock/text/checked/items/dropDown.lastValue/comboBox.lastValue/format/date.*/placeholder/placeholderText等规范键被逐一转发确保dump → batch循环不丢失控件类型与选中状态行内 SDT 还按源文档 rank 排序发射避免内容控件在段落中的顺序被打乱WordBatchEmitter.Paragraph.cs。完整示例员工入职表单的构建脉络把以上知识点串起来content-controls.py或等价的content-controls.sh构建的content-controls.docx是一份完整的员工入职表单按顺序包含标题 副标题Title/Subtitle样式段落Full name——typetext占位文本[Enter full legal name]placeholderTextDefaultPlaceholderDepartment——typedropdown5 个部门选项dropDown.lastValueEngineeringPrimary office——typecomboboxdisplay|value形式的 4 个办公地选项comboBox.lastValueLONStart date——typedateformatyyyy-MM-dddate.fullDate2026-02-01T00:00:00ZProfile photo——typepicture图片占位符Reviewer notes——typerichtextlockcontentLocked冻结内容Approval——typegrouplocksdtContentLocked双重锁定HR approved——typecheckboxcheckedtrue渲染 ☒创建后通过set把第 2 个控件改名为 Home Department 并加sdtLocked演示创建后可修改。这份表单覆盖了内容控件在真实人事/审批场景中的典型用法数据录入文本、日期、受控选择下拉、组合框、富文本批注、图片上传占位、分组保护与布尔审批。读者可直接把content-controls.py的sdt()/para()辅助函数作为模板替换属性即可生成自己的表单文档。【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考