使用自定义 XML 标记

使用自定义 XML 标记

本指南展示了如何读取和管理 Word 文档可携带的自定义 XML 数据，这些数据与可见内容一起存在——用于绑定内容控件、存储特定应用程序的元数据或嵌入任意包部件。Document.CustomXmlParts 暴露文档级别的自定义 XML 数据，而 Document.PackageCustomParts 暴露包级别的自定义部件，这些部件并非特定的自定义 XML。

自定义 XML 部件

CustomXmlPart 表示附加到文档的一个自定义 XML 数据岛——与 Word 用于支撑 XML 映射的内容控件的机制相同。每个部件都有一个 Id、一个保存原始 XML 的 Data 字节数组、一个 DataChecksum，以及一个 Schemas 属性（一个 CustomXmlSchemaCollection），列出与之关联的 XML 架构。Document.CustomXmlParts 返回一个 CustomXmlPartCollection：Add(part) 附加现有的 CustomXmlPart，Add(id, xml) 直接从 id 和 XML 字符串创建一个，GetById(id) 检索特定部件，RemoveAt(index)/Clear() 删除部件。CustomXmlPart 和 CustomXmlPartCollection 都暴露 Clone() 用于复制自定义 XML 数据，例如在文档之间复制内容时。

自定义 XML 架构

CustomXmlSchemaCollection（通过 CustomXmlPart.Schemas 访问）列出与自定义 XML 部件关联的架构 URI。它支持 Add(value)、Remove(name)、RemoveAt(index)、IndexOf(value)、Clear() 和 Clone()，以及一个 Count 属性——架构 URI 被作为普通字符串而非已解析的架构对象进行跟踪。

自定义 XML 属性

与 CustomXmlPart 分开，CustomXmlProperty 表示单个名称/值 XML 属性，由 CustomXmlProperty(name, uri, value) 构造并公开 Name、Uri 和 Value。CustomXmlPropertyCollection 管理这些属性的集合：Add(property) 添加一个，索引器（例如 properties["MyProp"]）可按名称查找并使用 Contains(name) 检查其是否存在，IndexOfKey(name) 返回其位置，Remove(name)/RemoveAt(index)/Clear() 则删除条目。SmartTag.Properties 返回一个 CustomXmlPropertyCollection，这就是旧版智能标签的结构化数据的表示方式（见下文）。

包级自定义部件

Document.PackageCustomParts 返回一个 CustomPartCollection，其中包含 CustomPart 对象——存储在 OOXML 包中的任意部件，这些部件不是自定义 XML 数据，例如由其他修改文件的应用程序添加的部件。每个 CustomPart 都有一个 Name、ContentType、RelationshipType、一个 Data 字节数组，以及一个 IsExternal 标志，指示该部件是外部引用还是嵌入内容。该集合支持 Add(part)、RemoveAt(index)、Clear() 和 Clone()，以及 Count。

旧版智能标签

SmartTag 是一种节点类型（NodeType.SmartTag），表示围绕已识别文本的旧版 Word 智能标签。SmartTag 通过 SmartTag(doc) 构造，并公开 Element（识别器元素名称）和 Uri（识别器的命名空间），以及 Properties——一个保存识别器附加到标记文本的结构化数据的 CustomXmlPropertyCollection。由于 SmartTag 是节点，它同其他节点一样参与文档树，支持 Accept(visitor)、AcceptStart(visitor) 和 AcceptEnd(visitor) 以进行基于 DocumentVisitor 的遍历。

MarkupLevel

MarkupLevel 是一个枚举——Unknown、Inline、Block、Row、Cell——用于描述文档树中标记元素（例如结构化文档标签）可能出现的结构层级。

提示与最佳实践

• 当您已知所需部件的 ID 时，请使用 CustomXmlPartCollection.GetById(id) 而不是手动遍历集合。
• 读取 CustomXmlPart.DataChecksum 以检测底层 XML 数据是否已更改，而无需进行完整的字节比较。
• 区分 Document.CustomXmlParts（自定义 XML 数据，通常绑定到内容控件）和 Document.PackageCustomParts（任意非 XML 的包部件）——它们用途不同，且存储方式也不同。
• 在处理使用智能标签的旧版文档时，请同时检查 SmartTag.Element 和 Uri 以确定是哪种识别器创建了标签，然后再依赖其 Properties。
• 在文档之间复制数据时，使用 CustomXmlPart.Clone()（或集合的 Clone()）克隆自定义 XML 部件，而不是重新读取并重新添加原始的 XML。

常见问题

FAQ

CustomXmlPart 与 CustomXmlProperty 有何区别？

CustomXmlPart 是一个完整的 XML 数据岛（包含字节数组负载和相关模式），通过 Document.CustomXmlParts 访问。CustomXmlProperty 是单个名称/值对，通常通过 SmartTag.Properties 而不是直接从文档中获取。

我如何向文档添加自定义 XML 数据？

使用 ID 字符串和 XML 内容调用 Document.CustomXmlParts.Add(id, xml)，或者单独构造一个 CustomXmlPart 并将其传递给 Add(part)。

什么是包自定义部件，它们与自定义 XML 部件有何区别？

Document.PackageCustomParts（一个包含 CustomPart 对象的 CustomPartCollection）保存任意非自定义 XML 的 OOXML 包部件——每个部件都有一个 ContentType、RelationshipType 和原始的 Data。Document.CustomXmlParts 专用于自定义 XML 数据岛。

什么是 SmartTag？

SmartTag 是 Word 的旧版功能，表示由智能标签识别器识别并包装的文本。它是一个文档节点（NodeType.SmartTag），具有用于标识识别器的 Element 和 Uri，以及一个包含识别器附加的 CustomXmlProperty 值的 Properties 集合。

我如何在文档之间复制自定义 XML 数据？

在源部分使用 CustomXmlPart.Clone()，然后将克隆添加到目标文档的 Document.CustomXmlParts，并使用 Add(part)。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation