Как работать со свойствами документа в .NET
Как работать со свойствами документа в .NET
Каждый документ Word содержит две категории метаданных — стандартные поля, которые Word отслеживает для каждого файла, и любые значения, определённые приложением и добавленные программой. Это руководство показывает, как читать и задавать обе категории с помощью Aspose.Words FOSS для .NET, используя Document.BuiltInDocumentProperties и Document.CustomDocumentProperties, которые в конечном итоге построены на одной и той же DocumentProperty репрезентации.
Пошаговое руководство
Шаг 1: Чтение и установка встроенных свойств документа
Document.BuiltInDocumentProperties возвращает коллекцию BuiltInDocumentProperties. Поскольку это фиксированный, известный набор свойств, значения читаются и записываются как обычные члены, а не ищутся по имени — например, BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords и .Comments для описательных полей, или .CreatedTime, .LastSavedTime, .LastPrinted и .LastSavedBy для временных меток. Статистика, такая как .Characters, .CharactersWithSpaces, .Lines и .Bytes, также доступна таким образом, наряду с .Template и .HyperlinkBase.
Шаг 2: Добавить пользовательское свойство документа
Document.CustomDocumentProperties возвращает CustomDocumentProperties коллекцию пользовательских метаданных, которые не входят в набор Word по умолчанию. Вызовите одну из перегрузок Add(name, value), передав имя и типизированное значение — строку, число, логическое значение или дату, в зависимости от того, какая перегрузка соответствует типу значения — чтобы создать новое свойство.
Шаг 3: Связать пользовательское свойство с содержимым документа
Вместо статического значения пользовательское свойство может отслеживать диапазон содержимого, отмеченный закладкой, чтобы его значение оставалось синхронным с этим содержимым. Вызовите CustomDocumentProperties.AddLinkToContent(name, linkSource), передавая имя закладки как linkSource, вместо того чтобы вручную пересинхронизировать статическое свойство каждый раз, когда изменяется связанное содержимое.
Шаг 4: Поиск, проверка и удаление свойств
И BuiltInDocumentProperties, и CustomDocumentProperties наследуются от абстрактного DocumentPropertyCollection, поэтому их проверяют одинаковым способом: индексация по имени (например, properties[name]) возвращает свойство, Contains(name) проверяет, существует ли оно, IndexOf(name) возвращает его позицию, а Count сообщает, сколько свойств содержит коллекция. Вызовите Contains(name) перед индексацией по имени, когда пользовательское свойство может отсутствовать, чтобы избежать обработки отсутствующего свойства как пути исключения. Удалите свойство с помощью Remove(name) или RemoveAt(index), либо очистите все свойства в коллекции с помощью Clear().
Шаг 5: Читать значение пользовательского свойства без предварительного знания его типа
У DocumentProperty есть Name, нетипизированный Value и Type — значение перечисления PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray или Other. Поскольку Value нетипизирован, используйте соответствующий типизированный аксессор вместо прямого приведения типов: ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() или ToString(). Проверьте IsLinkToContent и LinkSource, чтобы выяснить, связано ли свойство с содержимым документа (см. Шаг 3), а не содержит статическое значение.
Шаг 6: Проверить состояние защиты документа
BuiltInDocumentProperties.Security сообщает значение DocumentSecurity, описывающее сохранённые метаданные защиты документа: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced или ReadOnlyExceptAnnotations. Прочитайте это свойство, прежде чем решать, нужен ли дальнейший процесс, связанный с защитой, для загруженного документа.
Распространённые проблемы и их решения
Индексация CustomDocumentProperties коллекция по имени не возвращает ничего пригодного. Свойство не существует в этом документе. Вызовите Contains(name) сначала, либо добавьте свойство с соответствующим Add(name, value) перегрузкой.
Чтение значения пользовательского свойства возвращает неверный тип. DocumentProperty.Value не типизировано object; вызывающий предположил тип, который не совпадает Type. Используйте соответствующий типизированный аксессор (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) на основе DocumentProperty.Type.
Значение связанного пользовательского свойства выглядит устаревшим. Свойство связано через AddLinkToContent, и содержимое закладки изменилось. Подтвердите, что linkSource закладка по-прежнему отмечает диапазон, который должен заполнять значение свойства.
Статистика слов, такая как Characters or Lines не соответствует фактическому текущему содержимому документа. Встроенная статистика отражает сохранённые метаданные, а не живой пересчёт. Пересчитайте и обновите соответствующие BuiltInDocumentProperties значения, если требуется актуальный подсчёт.
Часто задаваемые вопросы
Как прочитать или задать автора и заголовок документа?
Используйте Document.BuiltInDocumentProperties.Author и .Title напрямую — это обычные строковые свойства в коллекции BuiltInDocumentProperties, доступной через Document.BuiltInDocumentProperties.
Как добавить метаданные, специфичные для приложения, которые не являются стандартным свойством Word?
Используйте Document.CustomDocumentProperties.Add(name, value) с именем свойства и его значением; соответствующая перегрузка Add выбирается в зависимости от типа значения.
В чём разница между BuiltInDocumentProperties и CustomDocumentProperties?
BuiltInDocumentProperties — это фиксированный набор стандартных полей метаданных Word, доступных как именованные члены. CustomDocumentProperties — это открытая именованная коллекция значений DocumentProperty для метаданных, определённых приложением, доступная по имени через индексатор (например, properties[name]) и Contains.
Как сделать так, чтобы пользовательское свойство отслеживало часть содержимого документа, а не статическое значение?
Используйте CustomDocumentProperties.AddLinkToContent(name, linkSource), передавая имя закладки как linkSource; значение свойства тогда будет отражать содержимое этой закладки.
Как проверить, защищён ли документ паролем?
Прочитайте Document.BuiltInDocumentProperties.Security, значение DocumentSecurity; PasswordProtected указывает, что сохраняемая в документе метаданные объявляют защиту паролем.
