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点击查看免费下载导读本文以 examples/word/content-controls.md 为核心深入讲解 OfficeCLI 对 Word内容控件Content ControlsOOXML 中即结构化文档标签sdt的完整支持从 CLI 一行命令创建八大类型控件到属性读取、创建后修改与回读校验并配以 Python SDK 脚本与源码级实现佐证。读完你可以在不安装 Office 的情况下用 OfficeCLI 程序化生成、查询和维护带可填写表单域的.docx文档例如员工入职信息表、审批单等典型场景。一、什么是sdtWord 眼中的可填写表单域在 OOXML 的 WordprocessingML 命名空间里内容控件content control对应的底层元素是w:sdtStructured Document Tag结构化文档标签。它把文档中的一块区域圈起来让 Word 把这整块区域当作一个独立的可填写表单域用户可以点击灰色框并输入、选择或勾选而文档结构始终作为一个整体被处理。OfficeCLI 中它对应sdt元素别名contentcontrol其属性契约定义在 schemas/help/docx/sdt.json 中。按放置层级分为两种形态块级block-level挂在/body下包裹一个或多个段落是表单控件最常见的形式行内inline挂在/body/p[N]下包裹 runs例如表格单元格内的小控件。块级sdt添加于/body回读时的稳定路径是/body/sdt[sdtIdN]基于 OOXMLw:sdtId属性生成见源码NextSdtId()的分配逻辑位置式路径/body/sdt[N]同样可用officecli add file.docx /body --type sdt --prop typetext --prop aliasFull Name officecli query file.docx sdt # 列出每个控件及其属性 officecli get file.docx /body/sdt[1] # 读取单个控件的属性包从源码结构看WordHandler.Query.cs查询系统还为嵌套场景生成了全祖先路径如表格内的tbl/tr/tc/sdt并支持按属性过滤例如sdt[tagpartyA]。一个关键限制类型在创建后不可更改type决定控件的底层 OOXML 结构w:sdtPr内的类型子元素因此创建之后无法更改。add时支持以下八种类型#类型用途类型专属属性1textplainText单行纯文本输入text初始/占位内容2dropdown单选下拉禁止自由输入items、dropDown.lastValue3combobox下拉可选或自由输入itemsdisplay\|value、comboBox.lastValue4date日历日期选择器format、date.fullDate/calendar/lid/storeMappedDataAs5picture图片插入占位符—6richtext支持富文本的多 run 字段text7group锁定分组包裹—8checkbox复选框开关☒/☐checkedtrue/false而buildingBlockGallery文档部件库与repeatingSection重复节未在 add 时实现——这类控件需要先在 Word 中手工创建再用 CLI 编辑。这与 schemas/help/docx/sdt.json 中type属性addtrue / setfalse的枚举定义以及 WordHandler.Add.Misc.cs 中supportedSdtTypes白名单校验完全一致遇到不支持的sdtType会直接抛出SDT type ... is not implemented. Supported: ...异常。二、共享属性每个控件类型都有的属性包无论哪种类型以下属性对全部控件通用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 图库引用lock语义源码中映射为 OOXMLw:lock枚举见 WordHandler.Add.Misc.cscontentLocked冻结内容回读时editablefalsesdtLocked禁止删除控件本身sdtContentLocked两者都生效既锁内容又锁删除。CLI 还接受若干兼容别名content↔contentLocked、sdt↔sdtLocked、both↔sdtContentLocked、none↔unlocked。placeholdertrue标记控件当前正在显示占位文本对应底层w:showingPlcHdr/元素placeholderText则是占位内容的 docPart 图库引用对应w:placeholderw:docPart w:val...//w:placeholder例如示例中的DefaultPlaceholder。三、逐类型属性详解3.1dropdown与combobox选择列表两者都用逗号分隔的items提供选项区别在于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.lastValueLON规则要点items是逗号列表每一项可以是纯display显示即存储值或display|value显示文本与存储值分离{dropDown,comboBox}.lastValue表示当前选中项的存储值源码中items底层写入SdtContentDropDownList/SdtContentComboBox的ListItem序列lastValue写入对应元素的LastValue属性一个实用细节items的解析兼容choices别名源码注释CONSISTENCY(sdt-items-alias)且set替换整个选项列表时会保留lastValue见 WordHandler.Set.Element.cs。3.2date日历日期选择器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显示掩码DateFormat属性只影响展示date.fullDate实际选中的日期值ISO-8601 UTC对应w:fullDate与显示掩码是两回事date.calendar日历体系如gregorian、hijri、japandate.lid语言/区域 ID如en-USdate.storeMappedDataAsXML 映射存储类型dateTime/date/text。3.3picture图片占位符officecli add file.docx /body --type sdt --prop typepicture \ --prop aliasProfile Photo --prop tagphoto无需额外属性Word 会渲染点击插入图片的占位提示。3.4richtext富文本字段officecli add file.docx /body --type sdt --prop typerichtext \ --prop aliasReviewer Notes --prop tagnotes \ --prop textManager may add formatted commentary here. \ --prop lockcontentLocked允许在控件内做加粗、着色等富文本编辑示例中配合lockcontentLocked冻结内容回读editablefalse。3.5group锁定分组包裹officecli add file.docx /body --type sdt --prop typegroup \ --prop aliasApproval Block --prop tagapproval \ --prop textApproved by HR — signature on file. \ --prop locksdtContentLocked把一段内容打包成整体单元sdtContentLocked同时阻止删除控件与编辑其内容。3.6checkbox真正的 Word 复选框officecli add file.docx /body --type sdt --prop typecheckbox \ --prop aliasApproved --prop taghrApproved \ --prop checkedtruecheckedtrue渲染 ☒Unicode 2612checkedfalse渲染 ☐2610状态存储在控件sdtPr中的w14:checkbox标记Office2010 扩展命名空间源码中复选框的默认内容 run 即是☒/☐字形见 WordHandler.Add.Misc.csset checked会重绘字形且不覆盖用户已输入的内容get回读typecheckbox与checked。四、创建后的修改set与可写性边界可 set 的共享属性alias、tag、lock、text。类型专属属性dropDown.lastValue、comboBox.lastValue、items、format、date.*、placeholderText在set阶段也大多可写但原文档明确标注其为add/get-only 语义——创建时设置、get回读需以实际set行为为准源码 WordHandler.Set.Element.cs 同时实现了对checked、items、lastValue、date.*、placeholder的 set 路径。示例把部门下拉控件改名为 Home Department 并加锁防删除officecli set file.docx /body/sdt[2] --prop aliasHome Department --prop locksdtLocked五、回读与检查query/getofficecli query content-controls.docx sdt # 每个控件一行 officecli get content-controls.docx /body/sdt[1]运行content-controls.sh后生成的 content-controls.docx 中query的典型输出节选/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只读回读键idOOXMLSdtId值是稳定路径/sdt[sdtIdN]的来源add 时不可设置由NextSdtId()分配editable当lock contentLocked或sdtContentLocked时为false与lock互相对应。完整属性清单可查officecli help docx sdt。六、Python SDK 方案content-controls.py逐段剖析CLI 的孪生脚本是 examples/word/content-controls.py它把整张员工入职信息表employee-intake form的构建压缩为可读的 SDK 调用。核心要点SDK 引入与回退优先import officecli对应pip install officecli-sdk未安装时回退到仓库内 sdk/python 的 SDK 副本sys.path.insert(0, ../../sdk/python)。辅助构造器para()封装add paragraph命令sdt()封装add sdt命令两者都走doc.batch([...])批量通道。一次会话完成全部工作officecli.create(FILE, --force)打开常驻进程 →batch依次添加标题、八个控件每个控件前用Heading2段落标注字段名→doc.send({command: set, path: /body/sdt[2], ...})做创建后修改 →doc.send({command: save})。回读校验循环get /body/sdt[i]i1..8从返回的data.results[0].format中打印type/alias/tag/lock/checked验证属性往返一致。独立进程验证最后用subprocess.run([officecli, validate, FILE])从磁盘重新打开校验文档有效性。重新生成文档cd examples/word pip install officecli-sdk python3 content-controls.py # 或bash content-controls.sh # → 生成 content-controls.docx提示content-controls.sh刻意不加set -e。因为脚本与 SDK 的doc.batch一样需要容忍前向兼容的UNSUPPORTED props警告officecli 此时退出码为 2继续构建以产出完整文档。CLI 脚本.sh的等价流程examples/word/content-controls.sh 展示了完全等价的命令序列officecli create→officecli open→ 逐条officecli add ... --type sdt --prop ...→officecli set→officecli close→officecli validate。两种写法产出等价的content-controls.docx方便你按命令行脚本或SDK 编程任选其一集成到自动化流水线。七、源码级支撑SDT 是如何写进 OOXML 的要理解这些属性背后的机制可深入三个文件schemas/help/docx/sdt.json属性契约的事实源。每个属性都标注add/set/get能力与examples例如checked的readback: true | false (checkbox controls only)、lock的四个枚举值以及id/editable的add:false, set:false只读声明。WordHandler.Add.Misc.csAddSdt实现。它先做嵌套合法性检查——不允许在纯文本 SDTsdtPr/w:text/内部再嵌 SDT否则产生的 OOXML 会被 Word 以错误 0x422 拒绝随后依次写入SdtId、SdtAlias、Tag、Lock再按类型写入对应的SdtContentDropDownList/SdtContentComboBox/SdtContentDate/SdtContentGroup/SdtContentPicture/BuildSdtCheckBox/SdtContentText行内控件还处理了 RTL 段落内 run 的rPr/rtl级联细节。WordHandler.Set.Element.csSetElementSdt实现 set 侧逻辑包括按CT_SdtPr顺序InsertSdtPropSchemaOrdered插入ShowingPlaceholder对应placeholdertrue、SdtPlaceholder对应placeholderText、SetSdtChecked重绘字形以及SetSdtItems整体替换选项列表。八、适用场景与边界典型用例员工入职表、审批单、报价单、调查问卷等一切固定结构 可填写域的 Word 表单tag提供机器可读的绑定键便于下游程序按tag提取用户填写值。适用前提sdt相关操作是 OfficeCLI 的 docx 处理能力之一无需安装 Microsoft Office单二进制即可运行buildingBlockGallery/repeatingSection类型需先在 Word 中创建控件再用 CLI 编辑其属性。更多参考仓库中 examples/word 目录还包含formulas.md、fields.md、document-formatting.md等配套示例可对照理解 Word 文档处理的其他属性面。赞分享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 内容控件Content Controls完全指南用 CLI 与 Python SDK 构建 Word 可填写表单OfficeCLI 内容控件Content Controls完全指南用 CLI 与 Python SDK 构建 Word 可填写表单 导读 本文以 Off人工智能AI 应用AI 技能CLIMCP 服务OfficeCLI Word-Form 实战指南用命令行构建带内容控件、复选框与邮件合并的真实可填写 Word 表单OfficeCLI Word Form 实战指南用命令行构建带内容控件、复选框与邮件合并的真实可填写 Word 表单 本篇技术指南基于 OfficeCLI 仓人工智能AI 应用AI 技能CLIMCP 服务OfficeCLI PPT 表格实战指南用 CLI 与 Python SDK 从零构建 PowerPoint 数据表格OfficeCLI PPT 表格实战指南用 CLI 与 Python SDK 从零构建 PowerPoint 数据表格 本文以 OfficeCLI 仓库中的CLIAI 应用MCP 服务上一篇FanControl终极指南如何免费定制你的Windows风扇控制方案下一篇如何解决FanControl风扇控制软件更新失败的5个关键步骤与预防策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考