Робота з полями

Огляд

Поле Word – DATE, IF, DATABASE, REF, і десятки інших – представлено у Aspose.Words FOSS для .NET через Field класу та його підкласів, всі в Aspose.Words.Fields просторі імен. Ця сторінка охоплює ядро механізму полів: Field сама об’єктна модель, як поля збираються та оновлюються, і інтерфейси зворотного виклику, які дозволяють підключати власні дані та поведінку під час оновлення поля. Конкретні сімейства полів – гіперпосилання та перехресні посилання, поля дати/часу, поля злиття листів, поля індексу та змісту – кожне має свою окрему сторінку посібника розробника.


Об’єктна модель поля

Кожне поле в документі є екземпляром Field, що складається з трьох маркерних вузлів — FieldStart, Separator та FieldEnd — які доступні як властивості Field.Start, Field.Separator і Field.End. Field.Type визначає, який FieldType представляє поле, Field.Result і Field.DisplayResult показують останнє обчислене значення, а Field.Format містить будь-які перемикачі (наприклад, рядки форматування чисел або дати-часу), прикріплені до коду поля. Field.IsLocked і Field.IsDirty повідомляють про заблокований та застарілий стан поля. Викличте Field.GetFieldCode(), щоб прочитати необроблений текст коду поля, Field.Update(), щоб переобчислити результат, Field.Unlink(), щоб замінити поле статичним текстом, і Field.Remove(), щоб повністю його видалити.


Доступ та оновлення полів у документі

Document.Range.Fields повертає FieldCollection — поля, що містяться у цьому діапазоні, з Count, Remove(), RemoveAt() і Clear() для масового видалення. Range.UpdateFields() переобчислює кожне поле у діапазоні, Range.UnlinkFields() перетворює кожне поле у діапазоні в статичний текст, а Range.NormalizeFieldTypes() узгоджує збережений тип коду поля з його фактичним кодом після ручних правок. DocumentBuilder.InsertField() вставляє нове поле в позицію курсора, з перевантаженнями, які або одразу оновлюють результат нового поля, або залишають його для подальшого проходу Range.UpdateFields().


Параметри оновлення полів та культура

Document.FieldOptions — це FieldOptions екземпляр, який визначає, як усі поля документа поводяться під час оновлення: CurrentUser постачає UserInformation, що використовується полями ідентифікації, DefaultDocumentAuthor ініціює результати, пов’язані з автором, LegacyNumberFormat і UseInvariantCultureNumberFormat контролюють форматування чисел, а PreProcessCulture і FieldUpdateCultureSource (у парі з зворотним викликом IFieldUpdateCultureProvider) визначають, яка культура керує форматуванням дат і чисел під час оновлення. TemplateName, FileName і BuiltInTemplatesPaths постачають значення, які читаються полями, що враховують шаблони та імена файлів.


Відстеження та налаштування оновлень полів

Реалізуйте IFieldUpdatingCallback (FieldUpdating і FieldUpdated) на FieldOptions, щоб виконувати код безпосередньо перед і після кожного переобчислення поля — корисно для аудиту, які поля змінилися під час пакетного завдання. Реалізуйте IFieldUpdatingProgressCallback (Notify), щоб відстежувати загальний прогрес у великому документі; він отримує FieldUpdatingProgressArgs з TotalFieldsCount, UpdatedFieldsCount і UpdateCompleted. Щоб змінити спосіб, у який числовий або загальний результат поля виводиться як текст, реалізуйте IFieldResultFormatter (Format(value, format) і FormatNumeric(value, format)) і призначте його FieldOptions.ResultFormatter.


Надання зовнішніх даних полям

Поле DATABASE читає свої рядки через IFieldDatabaseProvider.GetQueryResult(), який повертає FieldDatabaseDataTable (ColumnNames, Rows), створений із екземплярів FieldDatabaseDataRow (Values) — призначте свою реалізацію до FieldOptions.FieldDatabaseProvider. Порівняльні поля, такі як IF, оцінюють свою умову через IComparisonExpressionEvaluator.Evaluate(), який отримує ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) і повертає ComparisonEvaluationResult (Result, ErrorMessage); призначте власний оцінювач до FieldOptions.ComparisonExpressionEvaluator, щоб перевизначити логіку порівняння за замовчуванням. Поля, які зазвичай запитують користувача про введення під час оновлення — наприклад, ASK і FILLIN — викликають IFieldUserPromptRespondent.Respond(), коли один призначений до FieldOptions.UserPromptRespondent, щоб автоматичне оновлення не блокувалося в очікуванні інтерактивного вводу.


Ідентифікація користувача та документа для полів

UserInformation (Name, Initials, Address і статичний UserInformation.DefaultUser) надає ідентифікацію, з якої читаються поля, що пов’язані з автором та іменем користувача. Призначте екземпляр до Document.FieldOptions.CurrentUser перед оновленням полів, які залежать від автора документа або ідентифікації користувача.


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

  • Aspose.Words FOSS не перераховує поля автоматично під час завантаження або збереження, як це робить Word — викличте Range.UpdateFields() (або Field.Update() для окремого поля) явно після будь-якого програмного редагування, яке має бути відображене в результатах полів.
  • FieldStart, Separator та FieldEnd є реальними вузлами у дереві документа; видаляйте поле через Field.Remove() або Field.Unlink(), а не видаляючи маркерні вузли безпосередньо, інакше структура поля може стати несумісною.
  • Поля, чий результат залежить від розкладки сторінки — PAGE, NUMPAGES та записи номерів сторінок у ЗМ — оцінюються як заповнювач 0, оскільки ця редакція не включає движок розкладки/рендерингу.
  • Зареєструйте IFieldUpdatingCallback перед запуском Range.UpdateFields() над великим або незнайомим документом, якщо потрібно вести журнал або аудит того, які саме поля змінилися.
  • Встановіть FieldOptions.UserPromptRespondent (або надайте значення DefaultResponse у окремих класах полів, що керуються запитами) перед оновленням документа у автоматизованому конвеєрі, щоб поля ASK/FILLIN не зависали в очікуванні інтерактивного вводу.

Поширені проблеми

ПроблемаПричинаВиправлення
Результат поля застарів після редагування документаAspose.Words FOSS не оновлює поля автоматично під час завантаження або збереженняВикличте Range.UpdateFields() або Field.Update() явно
PAGE, NUMPAGES, або номери сторінок змісту показують 0Розмітка/візуалізація сторінки не є частиною цього випускуОчікувана поведінка — використовуйте комерційну Aspose.Words для .NET якщо вам потрібні обчислені номери сторінок
поле DATABASE не повертає рядківДля FieldOptions.FieldDatabaseProvider не призначено IFieldDatabaseProviderРеалізуйте IFieldDatabaseProvider і призначте його перед викликом Range.UpdateFields()
Здається, пакетне оновлення полів завислоПоле, кероване підказкою (ASK, FILLIN) не має призначеного IFieldUserPromptRespondentПризначте FieldOptions.UserPromptRespondent, або встановіть DefaultResponse у екземплярі поля

FAQ

Чи Aspose.Words FOSS оцінює кожен тип поля Word?

Модель об’єктів Field представляє кожне значення FieldType і оновлює більшість з них, але поля, результат яких залежить від макету сторінки — такі як PAGE та NUMPAGES — оцінюються як заповнювач 0, оскільки ця версія не включає движок макетування/рендерингу.

Як переоцінити поля після програмного редагування документа?

Викличте Range.UpdateFields() для діапазону, що охоплює відредагований вміст, або Document.Range.UpdateFields(), щоб оновити кожне поле в документі.

Чи можу я перетворити поле на простий, статичний текст?

Так — Field.Unlink() замінює поле його останнім обчисленим результатом у вигляді звичайного тексту, видаляючи підлягаючий код поля.

Як повністю видалити поле, включно з його результатом?

Викличте Field.Remove(). Він видаляє вузли FieldStart, Separator та FieldEnd разом з кодом поля та вмістом результату.

Як надати користувацькі дані полю DATABASE?

Реалізуйте IFieldDatabaseProvider і призначте його Document.FieldOptions.FieldDatabaseProvider. Ваша реалізація GetQueryResult() повертає FieldDatabaseDataTable, створений з FieldDatabaseDataRow екземплярів.


API Reference Підсумок

Клас / ІнтерфейсОпис
FieldБазовий клас для поля Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionПоля у діапазоні, через Range.Fields; Count, Remove(), Clear()
FieldTypeПерелік, що визначає, яке поле Word представляє екземпляр Field
FieldOptionsКонфігурація оновлення полів у всьому документі, через Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated хуки навколо оновлення кожного поля
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsЗвіт про прогрес під час масового оновлення поля
IFieldResultFormatterКористувацьке форматування розрахованого результату поля
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowЗовнішнє джерело даних для поля DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultКористувацька оцінка виразів полів у стилі порівняння
IFieldUserPromptRespondentНадає відповіді для полів, керованих підказками, під час безконтрольних оновлень
IFieldUpdateCultureProvider / FieldUpdateCultureSourceВибір культури під час оновлення полів
UserInformationІдентичність автора/користувача (Name, Initials, Address), яку зчитують поля ідентифікації

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

 Українська