Інформація про документ

У цьому посібнику показано, як читати та записувати метадані документа за допомогою Aspose.Words FOSS для .NET. Кожен завантажений або новостворений Document містить два типи метаданих разом зі своїм вмістом: фіксований набір вбудованих властивостей (автор, заголовок, кількість слів тощо) та відкритий набір користувацьких властивостей, які ви визначаєте самостійно. Aspose.Words FOSS для .NET також реалізує поля Word, які виводять ці метадані всередині тіла документа — AUTHOR, COMMENTS і DOCPROPERTY — тож значення властивостей можуть з’являтися як живий, оновлюваний текст.

Вбудовані властивості документа

Document.BuiltInDocumentProperties повертає колекцію BuiltInDocumentProperties з однією властивістю для кожного стандартного поля метаданих Word: Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime та статистики, такої як Pages, Words, Characters, CharactersWithSpaces, Paragraphs і Lines. Оскільки BuiltInDocumentProperties успадковується від DocumentPropertyCollection, вона також підтримує пошук за іменем через індексатор Contains(), IndexOf() та перебір через GetEnumerator(). Та сама колекція доступна в PlainTextDocument.BuiltInDocumentProperties при роботі з вхідним простим текстом.

Користувацькі властивості документа

Document.CustomDocumentProperties повертає колекцію CustomDocumentProperties для властивостей, які самостійно визначає застосунок — довільні пари ім’я/значення, які Word зберігає поряд із вбудованим набором. Додайте властивість за допомогою Add(name, value), який перевантажений у CustomDocumentProperties для типів значень, які може містити властивість; отримайте її за ім’ям за допомогою індексатора, наприклад properties[name]; і видаліть записи за допомогою Remove(name), RemoveAt(index) або Clear(). AddLinkToContent(name, linkSource) створює властивість, значення якої пов’язане з закладкою або діапазоном у документі, а не зберігається як фіксоване значення.

Кожен запис у будь-якій з колекцій — вбудованій або користувацькій — є DocumentProperty, який надає Name, Value та Type (значення PropertyType: String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray або Other), а також IsLinkToContent і LinkSource для пов’язаних властивостей. DocumentProperty надає допоміжні функції конвертації, такі як ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool() і ToByteArray() для отримання базового значення у потрібному типі .NET.

Поля інформації про документ

Три підкласу Field надають метадані документа у вигляді полів всередині самого тіла документа: FieldAuthor (поле AUTHOR з властивістю AuthorName), FieldComments (поле COMMENTS з властивістю Text), та FieldDocProperty (поле DOCPROPERTY, яке зчитує іменовану властивість документа — вбудовану або користувацьку — у документ). Як і кожен Field, ці три ділять базовий життєвий цикл Field: GetFieldCode() для зчитування коду базового поля, Result / DisplayResult для зчитування останнього обчисленого значення, Update() для повторного обчислення значення, Unlink() для заміни поля його статичним результатом і Remove() для його видалення. Вставте поле інформації про документ за допомогою DocumentBuilder.InsertField(fieldCode) — наприклад, код поля AUTHOR або DOCPROPERTY "Company" — або за допомогою перевантаження InsertField(fieldType, updateField), використовуючи значення FieldType, таке як FieldType.FieldAuthor, FieldType.FieldComments або FieldType.FieldDocProperty.

Оскільки FieldDocProperty зчитує будь-яку властивість документа, до якої воно прив’язане, зміна базового значення BuiltInDocumentProperties або CustomDocumentProperties і подальший виклик Update() — або Document.UpdateFields() для одночасного оновлення всіх полів у документі — передає нове значення у відображений результат поля.

Поради та кращі практики

Встановіть вбудовані властивості, такі як Title, Author і Subject, перед збереженням — Word та інші споживачі зчитують їх з BuiltInDocumentProperties для списків документів та індексації пошуку.
Використовуйте DocumentProperty.Type, щоб перевірити PropertyType властивості перед викликом конкретного допоміжного засобу конвертації (ToInt(), ToDateTime() тощо), аби уникнути невідповідності конвертації для властивості, яку ви не створювали.
AddLinkToContent() зберігає користувацьку властивість синхронізованою з вмістом документа (наприклад, діапазоном із закладкою) замість фіксованого значення — використовуйте її, коли властивість має завжди відображати поточний стан документа.
Викличте Document.UpdateFields() після зміни властивостей документа, щоб будь-які поля FieldDocProperty, FieldAuthor або FieldComments, вже розташовані в тілі документа, підхапили нові значення.
BuiltInDocumentProperties та CustomDocumentProperties доступні як у PlainTextDocument, так і у Document, тому метадані передаються навіть коли завантажений вміст є простим текстом.

Типові проблеми

Проблема	Причина	Виправлення
Індексатор повертає `null` для користувацької властивості	Властивість ще не додана	Спочатку викличте `CustomDocumentProperties.Add(name, value)`, або перевірте `Contains(name)` перед читанням
`FieldDocProperty` показує застаріле значення після зміни властивості	Поле не було оновлено	Викличте `Update()` для поля, або `Document.UpdateFields()`, щоб оновити всі поля в документі
`DocumentProperty.ToInt()` / `ToDateTime()` викидає	Фактичне `Type` властивості не збігається з запитаним перетворенням	Перевірте `DocumentProperty.Type` перед тим, як обирати, який помічник перетворення викликати

FAQ

У чому різниця між вбудованими та користувацькими властивостями документа?

Вбудовані властивості (Document.BuiltInDocumentProperties) — це фіксований набір, визначений форматом OOXML — Author, Title, Pages та інші подібні. Користувацькі властивості (Document.CustomDocumentProperties) — це відкритий, визначений застосунком набір пар ім’я/значення, доданий за допомогою Add().

Як зробити так, щоб користувацька властивість відстежувала вміст документа замість фіксованого значення?

Використовуйте CustomDocumentProperties.AddLinkToContent(name, linkSource), який зв’язує значення властивості з закладкою або діапазоном у документі замість зберігання статичного значення.

Чи оновлює оновлення властивості документа автоматично поля, які її відображають?

Ні — викличте Update() на конкретному полі або Document.UpdateFields(), щоб переобчислити кожне поле в документі, включаючи екземпляри FieldDocProperty, FieldAuthor та FieldComments.

Чи можу я зчитати властивості документа з простого текстового документа?

Так. PlainTextDocument надає ті ж BuiltInDocumentProperties і CustomDocumentProperties властивості, що й Document.

API Reference Підсумок

Клас / Метод	Опис
`Document.BuiltInDocumentProperties`	Стандартна колекція метаданих OOXML (`Author`, `Title`, `Pages` тощо)
`Document.CustomDocumentProperties`	Колекція властивостей ім’я/значення, визначена застосунком
`CustomDocumentProperties.Add()` / індексатор за ім’ям / `AddLinkToContent()`	Додати, отримати або створити контентне посилання на власну властивість
`DocumentProperty`	Один запис властивості; `Value`, `Type`, і `ToString()`/`ToInt()`/`ToDouble()`/`ToDateTime()`/`ToBool()`/`ToByteArray()` допоміжні функції перетворення
`FieldAuthor` / `FieldComments` / `FieldDocProperty`	`AUTHOR`, `COMMENTS` і `DOCPROPERTY` поля; `Update()`, `Result`, `GetFieldCode()`
`DocumentBuilder.InsertField()`	Вставляє поле за кодом поля або `FieldType`

Дивіться також

Aspose.Words for .NET — Enterprise Documentation