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

脚本专家 发表于 2026-6-18 09:00:02

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

环境准备
首先安装库：

pip install Spire.Doc

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

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

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

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

from spire.doc import *
from spire.doc.common import *

document = Document()
section = document.AddSection()
paragraph = section.AddParagraph()
txtRange = paragraph.AppendText("添加组合框内容控件：")
txtRange.CharacterFormat.Italic = True

# 创建内联内容控件
sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.ComboBox

# 添加选项
cb = SdtComboBox()
cb.ListItems.Add(SdtListItem("Spire.Doc"))
cb.ListItems.Add(SdtListItem("Spire.XLS"))
cb.ListItems.Add(SdtListItem("Spire.PDF"))
sd.SDTProperties.ControlProperties = cb

# 默认显示第一项
rt = TextRange(document)
rt.Text = cb.ListItems.DisplayText
sd.SDTContent.ChildObjects.Add(rt)

document.SaveToFile("ComboBoxControl.docx", FileFormat.Docx)
document.Close()

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

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

from spire.doc import *
from spire.doc.common import *

document = Document()
section = document.AddSection()
paragraph = section.AddParagraph()
paragraph.AppendText("添加文本内容控件：").CharacterFormat.Italic = True

sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.Text

text = SdtText(True)# True 允许多行
text.IsMultiline = True
sd.SDTProperties.ControlProperties = text

rt = TextRange(document)
rt.Text = "请输入文本内容..."
sd.SDTContent.ChildObjects.Add(rt)

document.SaveToFile("TextControl.docx", FileFormat.Docx)
document.Close()

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

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

from spire.doc import *
from spire.doc.common import *

document = Document()
section = document.AddSection()
paragraph = section.AddParagraph()
paragraph.AppendText("添加图片内容控件：").CharacterFormat.Italic = True

sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.Picture

pic = DocPicture(document)
pic.Width = 100
pic.Height = 100
pic.LoadImage("./Data/logo.png")# 请确保文件存在
sd.SDTContent.ChildObjects.Add(pic)

document.SaveToFile("PictureControl.docx", FileFormat.Docx)
document.Close()

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

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

from spire.doc import *
from spire.doc.common import *

document = Document()
section = document.AddSection()
paragraph = section.AddParagraph()
paragraph.AppendText("添加日期选择器内容控件：").CharacterFormat.Italic = True

sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.DatePicker

date = SdtDate()
date.CalendarType = CalendarType.Default
date.DateFormat = "yyyy.MM.dd"
date.FullDate = DateTime.get_Now()# 当前时间
sd.SDTProperties.ControlProperties = date

rt = TextRange(document)
rt.Text = "2024.01.15"# 默认显示文本
sd.SDTContent.ChildObjects.Add(rt)

document.SaveToFile("DatePickerControl.docx", FileFormat.Docx)
document.Close()

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

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

from spire.doc import *
from spire.doc.common import *

document = Document()
section = document.AddSection()
paragraph = section.AddParagraph()
paragraph.AppendText("添加下拉列表内容控件：").CharacterFormat.Italic = True

sd = StructureDocumentTagInline(document)
paragraph.ChildObjects.Add(sd)
sd.SDTProperties.SDTType = SdtType.DropDownList

sddl = SdtDropDownList()
sddl.ListItems.Add(SdtListItem("Harry"))
sddl.ListItems.Add(SdtListItem("Jerry"))
sddl.ListItems.Add(SdtListItem("Tom"))
sd.SDTProperties.ControlProperties = sddl

rt = TextRange(document)
rt.Text = sddl.ListItems.DisplayText
sd.SDTContent.ChildObjects.Add(rt)

document.SaveToFile("DropDownListControl.docx", FileFormat.Docx)
document.Close()

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

sd.SDTProperties.LockContents = True
sd.SDTProperties.LockControl = True

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

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

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

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

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

热心网友5 发表于 2026-6-18 11:05:00

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

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

热心网友5 发表于 2026-6-18 13:10:00

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

非常实用的教程！Spire.Doc 这个库之前没怎么接触过，看了你的示例代码，感觉添加组合框和日期选择器都挺清晰的。尤其是对默认显示文本的处理，还有图片控件的动态插入，正好解决了我做表单模板时的痛点。想问一下，如果要对已添加的内容控件进行修改或删除，有没有对应的 API 示例？谢谢分享！

热心网友4 发表于 2026-6-18 15:40:01

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

非常实用的教程！Spire.Doc 处理 Word 内容控件的操作写得很清晰，尤其是组合框和日期选择器的代码示例，直接复制就能跑通，省去了翻文档的麻烦。我也注意到你提到了锁定控件和数据提取，后续可以再补充一下这部分的具体实现吗？比如怎么设置控件为不可编辑或提取用户输入的值。感谢分享！

页: [1]

红客联盟 - 由08小组运营's Archiver