使用结构化文档标签（内容控件）

使用结构化文档标签（内容控件）

结构化文档标签（SDT），在 Word UI 中称为内容控件，将文档内容的一部分包装为具有特定类型、受限编辑行为的区域——复选框、日期选择器、下拉列表，或纯文本/富文本占位符。 Aspose.Words 针对 .NET 的 FOSS 通过以下方式对其进行建模 Aspose.Words.Markup 命名空间，以 StructuredDocumentTag 类。本页涵盖插入内容控件、配置每种类型、查找并移除它们，以及将它们绑定到自定义 XML 数据。

结构化文档标签对象模型

StructuredDocumentTag 是一个 CompositeNode，同时实现了 IMarkupNode、ITrackableNode 和 IStructuredDocumentTag。SdtType 用于标识它是哪种控件。Tag 和 Title 保存作者在 Word 中设置的标识字符串；Placeholder（一个 BuildingBlock）和 PlaceholderName 提供当控件为空时显示的提示文本，通过 IsShowingPlaceholderText 报告。LockContentControl 防止控件被删除，LockContents 防止其内容被编辑，两者相互独立。

插入内容控件

DocumentBuilder.InsertStructuredDocumentTag(SdtType) 在光标处插入一个新控件，但仅限于七种 SdtType 值：PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture 和 Date。RepeatingSection 和 RepeatingSectionItem 不能以这种方式在文本光标处插入——它们会包裹整个段落或表格行。其余出现在 Word 文件中但在 Word UI 中未作为可插入类型出现的 SdtType 值——None、Bibliography、Citation、Equation、BuildingBlockGallery、DocPartObj、Group 和 EntityPicker——不受此插入方法支持。

特定类型内容

复选框控件的状态是 StructuredDocumentTag.Checked；SetCheckedSymbol() 和 SetUncheckedSymbol() 设置每种状态显示的字形。日期控件将其值存储在 FullDate 中，DateDisplayFormat 和 DateDisplayLocale 控制其呈现方式，DateStorageFormat（一个 SdtDateStorageFormat）控制当绑定到 XML 数据时的存储方式，CalendarType（一个 SdtCalendarType）选择日历系统。下拉列表或组合框通过 ListItems 暴露其选项，ListItems 是 SdtListItemCollection 的 SdtListItem（DisplayText，Value），并带有 SelectedValue。纯文本控件的 Multiline 属性决定是否允许在其中换行。

外观和锁定

Appearance（SdtAppearance）控制该控件在 Word 中的视觉分隔方式。Color 设置其突出显示颜色，ContentsFont / EndCharacterFont 控制应用于其内容以及其尾部字符的字体。LockContentControl 和 LockContents 是独立的开关——第一个阻止删除控件本身，第二个阻止编辑其内部内容。

查找和删除内容控件

Range.StructuredDocumentTags 返回一个作用于该范围的 StructuredDocumentTagCollection，并提供 GetById()、GetByTag() 和 GetByTitle() 用于有针对性的查找，以及 Remove() 和 RemoveAt()。对于单个 StructuredDocumentTag，Remove() 同时删除控件及其内容，RemoveSelfOnly() 只删除包装器而保留文档中的内容，Clear() 清空控件的内容但保留控件本身。

XML 数据绑定

StructuredDocumentTag.XmlMapping 是一个描述与文档中自定义 XML 部分绑定的 XmlMapping 实例：CustomXmlPart、XPath、PrefixMappings、StoreItemId 和 IsMapped。SetMapping() 建立与现有自定义 XML 部分的绑定，Delete() 将其移除。

多节（范围）内容控件

跨越多个章节的内容控件——由 IsMultiSection 报告——并不是由单个 StructuredDocumentTag 节点表示，而是一对 StructuredDocumentTagRangeStart 和 StructuredDocumentTagRangeEnd 节点，通过 StructuredDocumentTagRangeStart.RangeEnd 连接。单节点形式和范围形式都实现了通用的 IStructuredDocumentTag 接口，因此只需要 Tag、Title、SdtType、Placeholder 等类似标识属性的代码可以统一地处理这两种形式。

提示与最佳实践

• 在依赖 DocumentBuilder.InsertStructuredDocumentTag() 之前，请检查其支持的类型列表——只有 PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture 和 Date 可以在光标处插入；其他类型会抛出异常。
• 当您想要“扁平化”内容控件时，请使用 RemoveSelfOnly() 而不是 Remove()——保留其内容在文档中，但去除控件包装。
• 在期望 DropDownList 或 ComboBox 控件显示选项之前，先填充 ListItems，并设置 SelectedValue 以选择活动项。
• 如果您的代码需要以相同方式处理普通内容控件和多章节（范围）内容控件，请针对 IStructuredDocumentTag 编程，而不是直接使用 StructuredDocumentTag。
• XmlMapping.SetMapping() 绑定到文档自定义 XML 数据存储中必须已存在的自定义 XML 部分——在将控件映射到该部分之前，先添加或加载 XML 数据。

常见问题

FAQ

我可以直接使用 DocumentBuilder 插入哪些内容控件类型？

PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture 和 Date。其他 SdtType 值不受 InsertStructuredDocumentTag() 支持。

我如何查找具有特定标签的所有内容控件？

使用 Range.StructuredDocumentTags.GetByTag()，或者如果你匹配的是后者，可使用 GetByTitle() / GetById()。

如何删除内容控件但保留其内容？

调用 StructuredDocumentTag.RemoveSelfOnly() 而不是 Remove()。

如何将内容控件绑定到自定义 XML 数据？

对该控件调用 XmlMapping.SetMapping()，并将其指向现有的自定义 XML 部件以及其中的 XPath 表达式。

普通的 StructuredDocumentTag 与范围型的之间有什么区别？

跨越多个文档节的内容控件表示为 StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd 对，而不是单个节点；这两种形式都实现了 IStructuredDocumentTag。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation