Робота з полями
Огляд
Поле 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 |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated хуки навколо оновлення кожного поля |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Звіт про прогрес під час масового оновлення поля |
IFieldResultFormatter | Користувацьке форматування розрахованого результату поля |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Зовнішнє джерело даних для поля DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Користувацька оцінка виразів полів у стилі порівняння |
IFieldUserPromptRespondent | Надає відповіді для полів, керованих підказками, під час безконтрольних оновлень |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Вибір культури під час оновлення полів |
UserInformation | Ідентичність автора/користувача (Name, Initials, Address), яку зчитують поля ідентифікації |