使用 Python 操作 Word 内容控件

在现代文档自动化场景中，内容控件（Content Controls）可以说是一种非常实用的结构化工具。它让你能在Word文档里嵌入下拉列表、日期选择器、文本输入框这些交互元素，从而轻松构建表单模板、调查问卷或标准化文档。

那么，如何用Python在Word中以编程方式添加和管理这些控件呢？这篇文章就围绕Spire.Doc库，带你看看怎么操作组合框、文本框、图片控件、日期选择器和下拉列表。

环境准备

首先，需要安装Spire.Doc for Python库：

pip install Spire.Doc

Spire.Doc是一个功能挺全的Word文档处理库，可以在不装Microsoft Word的情况下创建、读取、编辑和转换Word文档——对开发者来说很方便。

什么是内容控件

内容控件，也叫结构化文档标签（Structured Document Tags—SDT），本质上是Word里的容器元素，用来定义文档中特定类型内容的区域。它的优势很明显：

• 数据验证：限制用户只能输入特定格式的数据，或者从预定义选项里选。
• 结构化数据：方便后续提取和处理文档中的数据。
• 用户体验：提供直观的交互界面，比如下拉菜单和日历选择器。
• 文档标准化：确保文档走统一的格式和规范。

常见的内容控件类型包括：

• 组合框（Combo Box）
• 纯文本框（Text）
• 图片控件（Picture）
• 日期选择器（Date Picker）
• 下拉列表（Drop-Down List）

添加组合框内容控件

组合框允许用户从预定义的列表中选择一项，也可以手动输入自定义值。这在需要标准化输入的场景里特别有用，比如选择产品名称、部门或类别。

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[0].DisplayText
sd.SDTContent.ChildObjects.Add(rt)# 保存文档
document.Sa veToFile("ComboBoxControl.docx", FileFormat.Docx)
document.Close()

输出结果：

在这段代码里，StructureDocumentTagInline 用来创建内联的内容控件。通过把 SDTType 设为 ComboBox，就指定了控件类型。SdtComboBox 对象负责管理列表项，可以动态添加或删除选项。

添加纯文本内容控件

纯文本控件允许用户输入多行文本，适用于地址、备注或描述这类自由文本字段。

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.Text# 配置文本属性，允许多行输入
text = SdtText(True)
text.IsMultiline = True
sd.SDTProperties.ControlProperties = text# 设置占位符文本
rt = TextRange(document)
rt.Text = "请输入文本内容..."
sd.SDTContent.ChildObjects.Add(rt)document.Sa veToFile("TextControl.docx", FileFormat.Docx)
document.Close()

输出结果：

注意 SdtText 构造函数里的布尔参数——设为 True 就表示允许多行输入，用户可以输入带换行符的长文本。

添加图片内容控件

图片控件允许用户在文档中插入和管理图像，适用于需要动态添加产品图片、徽标或签名的场景。

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.Picture# 加载并添加图片
pic = DocPicture(document)
pic.Width = 100
pic.Height = 100
pic.LoadImage("./Data/logo.png")
sd.SDTContent.ChildObjects.Add(pic)document.Sa veToFile("PictureControl.docx", FileFormat.Docx)
document.Close()

输出结果：

图片控件会自动处理图像的缩放和布局，用户可以通过控件界面替换或移除图片。

添加日期选择器内容控件

日期选择器提供了日历界面，让用户以标准化格式选择日期，能有效避免日期格式不一致的问题。

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.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.Sa veToFile("DatePickerControl.docx", FileFormat.Docx)
document.Close()

输出结果：

SdtDate 对象支持自定义日期格式字符串，像 "yyyy-MM-dd"、"MM/dd/yyyy" 这类常见格式都可以灵活配置。

添加下拉列表内容控件

和组合框不同，下拉列表只允许用户从预定义选项中选择，不允许手动输入。这特别适合需要严格限制输入值的场景。

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.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[0].DisplayText
sd.SDTContent.ChildObjects.Add(rt)document.Sa veToFile("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文档自动化提供了相当强大的交互能力。通过Python加上Spire.Doc库，我们可以用代码来创建和管理多种类型的内容控件，包括：

• 组合框和下拉列表：提供标准化选项选择
• 文本框：支持自由文本输入
• 图片控件：简化图像管理
• 日期选择器：确保日期格式一致性

这些控件在创建表单模板、合同文档、调查问卷和标准化报告时特别有用。合理组合不同类型的内容控件，能构建出既美观又实用的交互式Word文档，大幅提升文档处理的效率和准确性。

在实际项目中，建议根据具体需求选择合适的控件类型，同时考虑加入数据验证逻辑来保证输入质量。当然，清晰的控件布局和直观的标签说明，也能显著提升最终用户体验。