使用文档属性

使用文档属性

本指南展示了如何读取和管理 Word 文档的元数据——即在 Word 的信息/属性面板中可见的属性，以及任何应用程序自定义的值。Document.BuiltInDocumentProperties 和 Document.CustomDocumentProperties 展示了这两类属性，它们最终都基于相同的底层 DocumentProperty 表示。

内置文档属性

Document.BuiltInDocumentProperties 返回一个 BuiltInDocumentProperties 集合，涵盖 Word 为每个文档跟踪的标准元数据：描述性字段，如 Title、Subject、Author、Manager、Company、Category、Keywords 和 Comments；时间戳，如 CreatedTime、LastSavedTime、LastPrinted，以及 LastSavedBy 和 RevisionNumber；以及统计信息，如 Words、Characters、CharactersWithSpaces、Lines、Paragraphs 和 Pages。Security 将文档的保护状态报告为 DocumentSecurity 值，Template、NameOfApplication 和 TotalEditingTime 描述了创作环境。由于 BuiltInDocumentProperties 是一组固定且已知的属性，单个值以普通属性 (BuiltInDocumentProperties.Author = "...") 的方式读取和写入，而不是通过名称查找。

自定义文档属性

Document.CustomDocumentProperties 返回一个 CustomDocumentProperties 集合，用于存放不属于 Word 内置集合的应用程序自定义元数据。多个 Add(name, value) 重载可根据名称和类型化值（字符串、数字、布尔值或日期，取决于重载）创建新属性，AddLinkToContent(name, linkSource) 则创建一个其值链接到文档中书签范围并随之跟踪的属性，而不是持有静态值。通过名称索引（例如 properties[name]）和 Contains(name) 可查找属性，IndexOf(name) 返回其位置，Remove(name)/RemoveAt(index) 用于删除属性。

DocumentProperty 对象及共享集合基类

BuiltInDocumentProperties和CustomDocumentProperties都源自抽象的DocumentPropertyCollection，该抽象通过名称、GetEnumerator()、Contains(name)、IndexOf(name)和Count定义了索引器——因此即使内建属性是固定的、自定义属性是开放式的，这两个集合的检查方式也相同。单独来看，一个DocumentProperty拥有Name、一个未类型化的Value，以及一个Type（PropertyType枚举值：Boolean、DateTime、Double、Number、String、StringArray、ObjectArray、ByteArray或Other）。IsLinkToContent和LinkSource报告该属性是链接到文档内容还是仅保存静态值（参见上面的AddLinkToContent）。由于Value未类型化，DocumentProperty提供了类型化的访问器——ToInt()、ToDouble()、ToDateTime()、ToBool()、ToByteArray()和ToString()——可在无需显式强制转换的情况下将其读取为特定类型。

文档安全

BuiltInDocumentProperties.Security报告一个DocumentSecurity值，用于描述文档的保护状态：None、PasswordProtected、ReadOnlyRecommended、ReadOnlyEnforced或ReadOnlyExceptAnnotations。这反映了从文件属性读取的文档存储的保护元数据。

提示与最佳实践

• 在DocumentProperty.Value上使用类型化访问器（ToInt()、ToDouble()、ToDateTime()、ToBool()），而不是直接对未类型化的object值进行强制转换，因为底层存储类型可能因PropertyType而异。
• 在按名称（例如properties[name]）索引任一属性集合之前检查Contains(name)，以防属性不存在，从而避免将缺失属性的情况视为异常路径处理。
• 当自定义属性的值应始终反映文档中已书签的部分时，请使用CustomDocumentProperties.AddLinkToContent(name, linkSource)，而不是在内容更改时手动重新同步静态自定义属性。
• 将BuiltInDocumentProperties统计信息（Words、Characters、Pages等）视为文件元数据中存储的值，而不是始终实时计算的计数——如果文档自上次写入后已更改，请显式刷新它们。
• 读取 BuiltInDocumentProperties.Security 以检查文档声明的保护状态，然后再决定是否需要进行进一步的保护相关处理。

常见问题

FAQ

如何读取或设置文档的作者和标题？

直接使用 Document.BuiltInDocumentProperties.Author 和 .Title ——它们是从 Document.BuiltInDocumentProperties 可访问的 BuiltInDocumentProperties 集合中的普通字符串属性。

如何添加非标准 Word 属性的特定应用程序元数据？

使用 Document.CustomDocumentProperties.Add(name, value) 并提供属性的名称和值；根据值的类型会选择相应的 Add 重载。

BuiltInDocumentProperties 与 CustomDocumentProperties 有何区别？

BuiltInDocumentProperties 是 Word 的固定标准元数据字段集合（作者、标题、统计信息等），通过具名属性访问。CustomDocumentProperties 是一个开放式、具名的 DocumentProperty 值集合，用于应用程序自定义元数据，可通过索引器按名称访问（例如 properties[name]）和 Contains。

如何在事先不知道其确切存储类型的情况下读取自定义属性？

通过索引集合检索 DocumentProperty（例如 properties[name]），检查其 Type（一个 PropertyType 值），然后在其 Value 上使用相匹配的类型访问器，例如 ToInt()、ToDouble()、ToDateTime() 或 ToBool()。

如何让自定义属性跟踪文档中的某段内容？

使用 CustomDocumentProperties.AddLinkToContent(name, linkSource)，将书签名称作为 linkSource 传递；属性的值随后反映该书签内容，而不是静态值。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation