Python+Spire.Doc实现Word内容控件完全指南：组合框、下拉列表、日期选择器等

脚本专家

在Word文档自动化中，内容控件（Content Controls）能嵌入下拉列表、日期选择器、文本框等交互元素，适合构建表单模板、调查问卷或标准化文档。本文基于Spire.Doc for Python库，演示如何通过代码添加和管理组合框、纯文本框、图片控件、日期选择器和下拉列表，并附带锁定控件、设置外观和数据提取等实用技巧。

环境准备
首先安装库：

2. pip install Spire.Doc

复制代码

Spire.Doc 无需安装 Microsoft Word 即可创建、读取和编辑 Word 文档，支持 .docx 格式。

什么是内容控件
内容控件（结构化文档标签 SDT）是 Word 中的容器，用于限定输入区域。其优势包括：
- 数据验证：限制输入格式或选项。
- 结构化数据：便于后续提取和处理。
- 用户体验：提供下拉菜单、日历等交互。
- 文档标准化：统一格式。

常见类型：组合框、纯文本框、图片控件、日期选择器、下拉列表。

添加组合框 (ComboBox)
组合框允许用户从预定义列表中选择，也可手动输入。适合产品名称、部门等标准化输入场景。

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. paragraph = section.AddParagraph()
8. txtRange = paragraph.AppendText("添加组合框内容控件：")
9. txtRange.CharacterFormat.Italic = True
11. # 创建内联内容控件
12. sd = StructureDocumentTagInline(document)
13. paragraph.ChildObjects.Add(sd)
14. sd.SDTProperties.SDTType = SdtType.ComboBox
16. # 添加选项
17. cb = SdtComboBox()
18. cb.ListItems.Add(SdtListItem("Spire.Doc"))
19. cb.ListItems.Add(SdtListItem("Spire.XLS"))
20. cb.ListItems.Add(SdtListItem("Spire.PDF"))
21. sd.SDTProperties.ControlProperties = cb
23. # 默认显示第一项
24. rt = TextRange(document)
25. rt.Text = cb.ListItems[0].DisplayText
26. sd.SDTContent.ChildObjects.Add(rt)
28. document.SaveToFile("ComboBoxControl.docx", FileFormat.Docx)
29. document.Close()

复制代码

关键点：StructureDocumentTagInline 创建内联控件；SdtComboBox 管理列表项；默认显示文本需手动设置到 SDTContent。

添加纯文本框 (Text)
纯文本控件支持多行输入，用于地址、备注等自由文本。

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. paragraph = section.AddParagraph()
8. paragraph.AppendText("添加文本内容控件：").CharacterFormat.Italic = True
10. sd = StructureDocumentTagInline(document)
11. paragraph.ChildObjects.Add(sd)
12. sd.SDTProperties.SDTType = SdtType.Text
14. text = SdtText(True)  # True 允许多行
15. text.IsMultiline = True
16. sd.SDTProperties.ControlProperties = text
18. rt = TextRange(document)
19. rt.Text = "请输入文本内容..."
20. sd.SDTContent.ChildObjects.Add(rt)
22. document.SaveToFile("TextControl.docx", FileFormat.Docx)
23. document.Close()

复制代码

SdtText 构造函数参数为 True 时启用多行，用户可换行输入。

添加图片控件 (Picture)
图片控件用于动态插入产品图片、徽标或签名。

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. paragraph = section.AddParagraph()
8. paragraph.AppendText("添加图片内容控件：").CharacterFormat.Italic = True
10. sd = StructureDocumentTagInline(document)
11. paragraph.ChildObjects.Add(sd)
12. sd.SDTProperties.SDTType = SdtType.Picture
14. pic = DocPicture(document)
15. pic.Width = 100
16. pic.Height = 100
17. pic.LoadImage("./Data/logo.png")  # 请确保文件存在
18. sd.SDTContent.ChildObjects.Add(pic)
20. document.SaveToFile("PictureControl.docx", FileFormat.Docx)
21. document.Close()

复制代码

图片控件自动处理缩放，用户可手动替换或移除。

添加日期选择器 (Date Picker)
日期选择器提供日历界面，确保日期格式统一。

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. paragraph = section.AddParagraph()
8. paragraph.AppendText("添加日期选择器内容控件：").CharacterFormat.Italic = True
10. sd = StructureDocumentTagInline(document)
11. paragraph.ChildObjects.Add(sd)
12. sd.SDTProperties.SDTType = SdtType.DatePicker
14. date = SdtDate()
15. date.CalendarType = CalendarType.Default
16. date.DateFormat = "yyyy.MM.dd"
17. date.FullDate = DateTime.get_Now()  # 当前时间
18. sd.SDTProperties.ControlProperties = date
20. rt = TextRange(document)
21. rt.Text = "2024.01.15"  # 默认显示文本
22. sd.SDTContent.ChildObjects.Add(rt)
24. document.SaveToFile("DatePickerControl.docx", FileFormat.Docx)
25. document.Close()

复制代码

通过 SdtDate 的 DateFormat 自定义格式，如 "yyyy-MM-dd"、"MM/dd/yyyy" 等。

添加下拉列表 (DropDownList)
与组合框不同，下拉列表禁止用户手动输入，严格限制选项。

2. from spire.doc import *
3. from spire.doc.common import *
5. document = Document()
6. section = document.AddSection()
7. paragraph = section.AddParagraph()
8. paragraph.AppendText("添加下拉列表内容控件：").CharacterFormat.Italic = True
10. sd = StructureDocumentTagInline(document)
11. paragraph.ChildObjects.Add(sd)
12. sd.SDTProperties.SDTType = SdtType.DropDownList
14. sddl = SdtDropDownList()
15. sddl.ListItems.Add(SdtListItem("Harry"))
16. sddl.ListItems.Add(SdtListItem("Jerry"))
17. sddl.ListItems.Add(SdtListItem("Tom"))
18. sd.SDTProperties.ControlProperties = sddl
20. rt = TextRange(document)
21. rt.Text = sddl.ListItems[0].DisplayText
22. sd.SDTContent.ChildObjects.Add(rt)
24. document.SaveToFile("DropDownListControl.docx", FileFormat.Docx)
25. document.Close()

复制代码

实用技巧
锁定控件：防止用户删除或修改控件结构。

2. sd.SDTProperties.LockContents = True
3. sd.SDTProperties.LockControl = True

复制代码

设置外观：自定义颜色和边框显示。

2. sd.SDTProperties.Color = Color.get_LightBlue()
3. sd.SDTProperties.Appearance = SdtAppearance.BoundingBox

复制代码

提取控件数据：遍历文档中所有内容控件，获取类型和内容。

2. for sdt in document.GetChildObjects(True, ObjectType.StructureDocumentTagInline):
3.     tag = sdt if isinstance(sdt, StructureDocumentTagInline) else None
4.     if tag:
5.         control_type = tag.SDTProperties.SDTType
6.         content = tag.SDTContent.Text
7.         print(f"类型:{control_type}, 内容:{content}")

复制代码

总结
内容控件为 Word 自动化带来了交互能力。通过 Spire.Doc for Python，可以用纯代码创建组合框、下拉列表、文本框、图片控件和日期选择器。这些控件特别适合表单模板、合同文档、调查问卷和标准化报告的生成。实际项目中，建议按需求组合控件，并配合锁定、外观设置和提取逻辑，可大幅提升文档处理效率与准确性。

热心网友5

楼主写得很详细，代码可以直接跑通，对我这种刚接触Spire.Doc的新手帮助很大。之前一直用VBA处理Word控件，Python版确实更灵活。请问组合框和下拉列表在实际使用中主要区别是什么？我看代码里组合框加了`SdtComboBox`，下拉列表是类似`SdtDropDownList`吗？另外，帖子提到“锁定控件”和“数据提取”的实用技巧，但正文好像没展开，方便的话能否补充一下？期待后续教程！