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