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

Обзор

Поле 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 и записи номеров страниц в оглавлении (TOC) — оцениваются как заполнитель 0, потому что в этом издании отсутствует движок макета/рендеринга страниц.
  • Зарегистрируйте IFieldUpdatingCallback перед запуском Range.UpdateFields() над большим или незнакомым документом, если вам необходимо вести журнал или аудит того, какие поля изменились.
  • Установите FieldOptions.UserPromptRespondent (или задайте значения DefaultResponse для отдельных классов полей, управляемых запросом) перед обновлением документа в автоматическом конвейере, чтобы поля ASK/FILLIN не зависали в ожидании интерактивного ввода.

Общие проблемы

ПроблемаПричинаИсправление
Результат поля устарел после редактирования документаAspose.Words FOSS не обновляет поля автоматически при загрузке или сохраненииВызовите Range.UpdateFields() или Field.Update() явно
PAGE, NUMPAGES или номера страниц оглавления показывают 0Разметка/рендеринг страниц не входит в эту редакциюОжидаемое поведение – используйте коммерческую Aspose.Words для .NET если вам нужны вычисленные номера страниц
поле DATABASE не возвращает строкНе назначено IFieldDatabaseProvider для FieldOptions.FieldDatabaseProviderРеализуйте 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) читаемая полями идентичности

См. также:

 Русский