Как работать с полями в .NET

Шаг 1: Получить библиотеку

Клонируйте репозиторий и соберите Aspose.Words.sln в конфигурации Release, затем добавьте ссылку на проект Aspose.Words.csproj из вашего собственного проекта .NET, как описано в руководстве по установке. Добавьте using Aspose.Words; and using Aspose.Words.Fields; в начале любого файла, работающего с полями.

Шаг 2: Вставить поле и прочитать его результат

DocumentBuilder.InsertField() вставляет новое поле в позицию курсора, предлагая перегрузки, которые либо сразу обновляют результат поля, либо откладывают обновление на более поздний проход. Каждое поле представляет собой экземпляр Field, состоящий из трёх маркерных узлов — FieldStart, Separator и FieldEnd, доступных как Field.Start / Field.Separator / Field.End. Field.Type определяет, какой FieldType он представляет, Field.Result и Field.DisplayResult содержат последнее вычисленное значение, Field.Format хранит любые переключатели формата, прикреплённые к коду, а Field.GetFieldCode() возвращает необработанный текст кода поля.

Шаг 3: Обновить поля после программного редактирования

Aspose.Words FOSS не пересчитывает поля при загрузке или сохранении документа. После изменения, которое должно изменить результат поля, вызовите Range.UpdateFields(), чтобы пересчитать все поля в этом диапазоне — используйте Document.Range.UpdateFields() для всего документа — или Field.Update() для отдельного поля. Range.UnlinkFields() преобразует каждое поле в диапазоне в статический текст одним вызовом, а Range.NormalizeFieldTypes() согласует сохранённый тип кода поля с его фактическим кодом после ручного редактирования.

Шаг 4: Настроить поведение обновления полей с помощью FieldOptions

Document.FieldOptions (экземпляр FieldOptions) определяет, как поля всего документа ведут себя во время обновления: CurrentUser (экземпляр UserInformation — Name, Initials, Address) предоставляет идентификацию, из которой читают поля, связанные с именем автора и пользователя, DefaultDocumentAuthor задаёт результаты, связанные с автором, а LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource управляют форматированием чисел и дат. Для автоматических конвейеров назначьте FieldOptions.UserPromptRespondent (это IFieldUserPromptRespondent), чтобы поля, требующие ввода, такие как ASK и FILLIN, не блокировали процесс, ожидая интерактивный ввод, и задайте пользовательский IFieldDatabaseProvider для FieldOptions.FieldDatabaseProvider, чтобы поставлять строки поля DATABASE из вашего собственного источника данных вместо реального соединения с базой данных.

Шаг 5: Отслеживать обновления полей с помощью обратного вызова

Реализуйте IFieldUpdatingCallback (FieldUpdating и FieldUpdated) и назначьте его FieldOptions, чтобы выполнять код непосредственно до и после каждого пересчёта поля — полезно для аудита точных изменений полей в пакетной задаче. Для отчёта о прогрессе в большом документе реализуйте IFieldUpdatingProgressCallback (Notify), который получает FieldUpdatingProgressArgs, раскрывающий TotalFieldsCount, UpdatedFieldsCount и UpdateCompleted.

Шаг 6: Преобразовать или удалить поле

Field.Unlink() заменяет поле его последним вычисленным результатом обычным статическим текстом, отбрасывая исходный код поля — используйте его, когда нужно навсегда внедрить значение в документ. Field.Remove() удаляет узлы FieldStart, Separator и FieldEnd вместе с кодом и результатом поля, полностью удаляя поле. Предпочтительно использовать эти два метода вместо прямого удаления маркерных узлов, так как ручное удаление лишь части структуры поля может сделать дерево документа несогласованным.