如何在 .NET 中使用结构化文档标签

步骤 1：安装包

Aspose.Words FOSS for .NET 仍未发布 NuGet 包——请改为从源码构建库。克隆 https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git，然后使用 .NET SDK 在 Release 配置下构建 Aspose.Words.sln，并在项目中引用生成的 Aspose.Words 程序集。该库面向 .NET Standard 2.0，因此可在 .NET Framework 4.6.2+ 和 .NET 6/8/10 上运行。

步骤 2：导入必需的类

为 Document 和 DocumentBuilder 添加一个 using Aspose.Words; 指令，并为 StructuredDocumentTag、SdtType、SdtListItem、SdtListItemCollection、XmlMapping 以及本指南涉及的其他内容控件类添加一个 using Aspose.Words.Markup; 指令。

第3步：检查可以插入的内容控件类型

在插入之前，检查目标 SdtType 是否是 DocumentBuilder.InsertStructuredDocumentTag(SdtType) 接受的七种类型之一：PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture 和 Date。RepeatingSection 和 RepeatingSectionItem 不能通过此方法在文本光标处插入——它们会包裹整个段落或表格行。其余可以出现在 Word 文件中但在 Word UI 中未列为可插入类型的 SdtType 值——None、Bibliography、Citation、Equation、BuildingBlockGallery、DocPartObj、Group 和 EntityPicker——根本不被此插入方法接受。

第4步：在光标处插入内容控件

使用 DocumentBuilder.InsertStructuredDocumentTag(SdtType) 并传入七种受支持类型之一，在构建器当前光标位置插入一个新控件；该调用返回新的 StructuredDocumentTag。在返回的控件上设置 Tag 和 Title，以提供作者在 Word 中看到的标识字符串，并设置 PlaceholderName（由 Placeholder BuildingBlock 支持）作为控件为空时 Word 显示的提示文本——IsShowingPlaceholderText 报告该提示当前是否显示。

第5步：配置特定类型的内容

对于复选框控件，读取或设置 StructuredDocumentTag.Checked，并调用 SetCheckedSymbol() / SetUncheckedSymbol() 来自定义每种状态显示的字形。对于日期控件，设置 FullDate，其中 DateDisplayFormat 和 DateDisplayLocale 控制其呈现方式，DateStorageFormat（SdtDateStorageFormat）控制绑定到 XML 数据时的存储方式，CalendarType（SdtCalendarType）选择日历系统。对于下拉列表或组合框，在设置 SelectedValue 以选择活动项之前，填充 ListItems——一个 SdtListItemCollection，其值为 SdtListItem（DisplayText、Value）。对于纯文本控件，Multiline 是 StructuredDocumentTag 上的 bool 属性，可用于配置该控件。

第6步：控制外观和锁定

设置 Appearance（SdtAppearance）以控制控件在 Word 中的可视分隔方式，并设置 Color 以指定其高亮颜色。ContentsFont 和 EndCharacterFont 控制应用于控件内容及其尾随字符的字体。LockContentControl 和 LockContents 是独立的开关——将 LockContentControl 设置为阻止删除控件本身，将 LockContents 设置为阻止编辑其内部内容，而不影响另一项。

第7步：查找并删除内容控件

读取 Range.StructuredDocumentTags —— 一个作用域为该范围的 StructuredDocumentTagCollection —— 并调用 GetById()、GetByTag() 或 GetByTitle() 来定位特定的控件，或在集合上使用 Remove() / RemoveAt() 通过引用或索引删除控件。对于单个控件，调用 Remove() 可删除控件及其内容，调用 RemoveSelfOnly() 仅删除包装器而保留文档中的内容，或调用 Clear() 清空其内容但保留控件本身。

第8步：将控件绑定到自定义 XML 数据

读取 StructuredDocumentTag.XmlMapping —— 一个 XmlMapping 实例 —— 并调用 SetMapping(customXmlPart, xPath, prefixMapping) 将控件绑定到文档自定义 XML 数据存储中已存在的自定义 XML 部分，使用 XPath 表达式选择绑定的元素。XmlMapping.IsMapped 报告绑定是否当前处于活动状态，CustomXmlPart 和 StoreItemId 标识绑定的数据部分，Delete() 移除映射。

第9步：处理跨多个章节的内容控件

跨越多个文档章节的内容控件——由 IsMultiSection 报告——并不是由单个 StructuredDocumentTag 节点表示，而是由一对 StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd 组成，通过 StructuredDocumentTagRangeStart.RangeEnd 关联。当代码需要统一处理单节点形式和范围形式时，应针对共享的 IStructuredDocumentTag 接口（Tag、Title、Placeholder、PlaceholderName、Appearance、IsShowingPlaceholderText、RemoveSelfOnly()）进行编程，而不是对具体类型进行分支。