Работа со свойствами документа

Работа со свойствами документа

Это руководство показывает, как читать и управлять метаданными документа 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. Это отражает сохранённые метаданные защиты документа, считанные из свойств файла.

Советы и лучшие практики

• Используйте типизированные аксессоры (ToInt(), ToDouble(), ToDateTime(), ToBool()) на DocumentProperty.Value, а не напрямую приводить нетипизированное значение object, поскольку базовый тип хранилища может различаться в зависимости от PropertyType.
• Проверьте Contains(name) перед обращением к любой из коллекций свойств по имени (например, properties[name]), если свойство может отсутствовать, чтобы избежать обработки случая отсутствующего свойства как пути исключения.
• Используйте CustomDocumentProperties.AddLinkToContent(name, linkSource), когда значение пользовательского свойства должно всегда отражать закладку в документе, вместо того чтобы вручную синхронизировать статическое пользовательское свойство каждый раз при изменении содержимого.
• Считайте статистику BuiltInDocumentProperties (Words, Characters, Pages и аналогичные) значениями, хранящимися в метаданных файла, а не постоянно живыми вычисляемыми подсчётами — явно обновляйте их, если документ изменился с момента последней записи.
• Прочитайте BuiltInDocumentProperties.Security, чтобы проверить объявленное состояние защиты документа, прежде чем решать, нужна ли дальнейшая обработка, связанная с защитой.

Распространённые проблемы

FAQ

Как прочитать или установить автора и название документа?

Используйте Document.BuiltInDocumentProperties.Author и .Title напрямую — это обычные строковые свойства в коллекции BuiltInDocumentProperties, доступной через Document.BuiltInDocumentProperties.

Как добавить метаданные, специфичные для приложения, которые не являются стандартным свойством Word?

Используйте Document.CustomDocumentProperties.Add(name, value) с именем свойства и его значением; соответствующая перегрузка Add выбирается в зависимости от типа значения.

В чём разница между BuiltInDocumentProperties и CustomDocumentProperties?

BuiltInDocumentProperties — это фиксированный набор стандартных полей метаданных Word (автор, название, статистика и т.д.), доступных как именованные свойства. CustomDocumentProperties — это открытая именованная коллекция значений DocumentProperty для метаданных, определяемых приложением, доступных по имени через индексатор (например, properties[name]) и Contains.

Как прочитать пользовательское свойство, не зная заранее его точный тип хранения?

Получите DocumentProperty, индексируя коллекцию (например, properties[name]), проверьте её Type (значение PropertyType), и используйте соответствующий типизированный аксессор, такой как ToInt(), ToDouble(), ToDateTime() или ToBool(), на её Value.

Как заставить пользовательское свойство отслеживать часть содержимого документа?

Используйте CustomDocumentProperties.AddLinkToContent(name, linkSource), передавая имя закладки в качестве linkSource; тогда значение свойства будет отражать содержимое этой закладки, а не статическое значение.

API Reference Сводка

См. также:

• Aspose.Words for .NET — Enterprise Documentation