Введение в области

Aspose.Words - это библиотека классов, предназначенная для обработки документов Microsoft Word на стороне сервера и поддерживающая поля следующими способами:

• все поля в документе сохраняются при открытии/сохранении и преобразовании
• можно обновить результаты по большинству полей

В этой статье мы узнаем больше о структуре поля, полях, поддерживаемых в Aspose.Words, и деталях работы с такими полями.

Структура поля

Поле состоит из:

• Узлы “Начало поля” и “разделитель” используются для отображения содержимого, составляющего код поля (обычно в виде обычного текста).
• Разделитель полей и конец поля отображают результат работы с полем. Это может быть содержимое различных типов - от фрагментов текста до абзацев и таблиц.
• Некоторые поля могут не иметь разделителя, что означает, что все содержимое составляет код поля.
• Код поля определяет поведение поля и состоит из идентификатора поля и часто других параметров, таких как название поля и переключатели.
• Поле “Результат” содержит самую последнюю оценку поля. Это значение сохраняется в поле “результат” и отображается пользователю. В некоторых полях может отсутствовать поле “результат”, поэтому в документе ничего не будет отображаться. Аналогично, некоторые поля, возможно, еще не обновлены, поэтому результат также не будет получен.

Содержимое, составляющее код поля, хранится в виде Run узлов между FieldStart и FieldSeparator. Результат поля хранится между узлами FieldSeparator и FieldEnd и может состоять из различных типов содержимого. Обычно поле результата содержит только текст, состоящий из узлов выполнения, однако узел FieldEnd может быть расположен в совершенно другом абзаце, и, таким образом, поле результата будет состоять из узлы блочного уровня например, узлы Table и Paragraph.

Вот представление о том, как хранится поле в Aspose.Words, с использованием примера “DocumentExplorer”, который можно найти на Github.

Поля в объектной модели документа Aspose.Words (DOM)

Когда документ загружается в Aspose.Words, поля документа загружаются в объектную модель документа Aspose.Words в виде набора отдельных компонентов (узлов). Одно поле загружается как набор узлов FieldStart, FieldSeparator и FieldEnd вместе с содержимым между этими узлами. Если у поля нет результата field, то не будет узла FieldSeparator. Все эти узлы всегда находятся в строке (как дочерние для Paragraph или SmartTag.

В Aspose.Words каждый из FieldXXX узлов является производным от FieldChar. Этот класс предоставляет свойство для проверки типа поля, представленного указанным узлом, с помощью свойства FieldType. Например, FieldType.FieldMergeField представляет поле объединения в документе.

В документе Word существуют некоторые особые поля, которые не импортируются в Aspose.Words как набор из FieldXXX узлов. Например, поле LINK и поле INCLUDEPICTURE импортируются в Aspose.Words как объект Shape. Этот объект предоставляет свойства для работы с данными изображения, которые обычно хранятся в этих полях. Чтобы импортировать поле INCLUDEPICTURE в качестве узлов FieldXXX, параметр PreserveIncludePictureField должен быть указан как true.

Поля формы также импортируются в Aspose.Words как их собственный специальный класс. Класс FormField представляет поле формы в документе Word и предоставляет дополнительные методы, характерные для поля формы.

Поддерживаемые поля

В текущей версии Aspose.Words поддерживается вычисление следующих полей:

• = (формула)
• ADDRESSBLOCK
• ASK
• AUTHOR
• AUTONUM
• AUTONUMLGL
• AUTONUMOUT
• AUTOTEXT
• BARCODE
• COMMENTS
• COMPARE
• CREATEDATE
• DATABASE
• DATE
• DISPLAYBARCODE
• DOCPROPERTY
• DOCVARIABLE
• EDITTIME
• EQ
• FILENAME
• FILESIZE
• FILLIN
• FORMCHECKBOX
• FORMDROPDOWN
• FORMTEXT
• GLOSSARY
• GOTOBUTTON
• GREETINGLINE
• HYPERLINK
• IF
• IMPORT
• INCLUDE
• INCLUDEPICTURE
• INCLUDETEXT
• INDEX
• INFO
• KEYWORDS
• LASTSAVEDBY
• LISTNUM
• MACROBUTTON
• MERGEBARCODE
• MERGEFIELD
• MERGEREC
• MERGESEQ
• NEXT
• NEXTIF
• NOTEREF
• NUMCHARS
• NUMPAGES
• NUMWORDS
• PAGE
• PAGEREF
• PRINTDATE
• QUOTE
• REF
• REVNUM
• SAVEDATE
• SECTION
• SECTIONPAGES
• SEQ
• SET
• SHAPE
• SKIPIF
• STYLEREF
• SUBJECT
• SYMBOL
• TEMPLATE
• TIME
• TITLE
• TOA
• TOC (including TOT and TOF)
• USERADDRESS
• USERINITIALS
• USERNAME

Сложный синтаксический анализ полей

Aspose.Words повторяет способ, которым Microsoft Word обрабатывает поля, и в результате корректно обрабатывает:

• вложенные поля: IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
• аргумент поля может быть результатом использования вложенного поля
• поля могут быть вложены как в код поля, так и в результат поля
• пробелы/без пробелов, кавычки/без кавычек, экранирующие символы в полях и т.д.: MERGEFIELD \f"Text after""Field \n\ame with \" and \\\ and \\\*"\bTextBefor\e
• поля, охватывающие несколько абзацев

Поля формул

Aspose.Words обеспечивает очень серьезную реализацию движка формул и поддерживает следующее:

• арифметические и логические операторы: =(54+4*(6-77)-(5))+(-6-5)/4/5
• функции: =ABS(-01.4)+2.645/(5.6^3.5)+776457 \\\# "#,##0"
• ссылки на закладки: =IF(C>4, 5,ABS(A)*.76) +3.85
• переключатели форматирования чисел: =00000000 \\\# "$#,##0.00;($#,##0.00)"

Поддерживаются следующие функции в выражениях: ABS, AND, AVERAGE, COUNT, DEFINED, FALSE, IF, INT, MAX, MIN, MOD, NOT, OR, PRODUCT, ROUND, SIGN, SUM, TRUE.

IF and COMPARE Fields

Лишь некоторые из выражений IF, которые Aspose.Words может легко вычислить, должны дать вам представление о том, насколько мощной является эта функция:

• IF 3 > 5.7^4+MAX(4,3) True False
• IF "abcd" > "abc" True False
• IF "?ab*" = "1abdsg" True False
• IF 4 = "2*2" True False
• COMPARE 3+5/34 < 4.6/3/2

DATE and TIME Fields

Aspose.Words поддерживает все параметры форматирования даты и времени, доступные в Microsoft Word, вот некоторые примеры:

• DATE @ "d-MMM-yy"
• DATE @ "d/MM/yyyy h:mm am/pm

Mail Merge Поля

Aspose.Words не накладывает ограничений на сложность полей Mail Merge в ваших документах, поддерживает вложенные поля IF и поля формул и даже может вычислять название объединяемого поля с помощью формулы.

Несколько примеров полей Mail Merge, которые поддерживает Aspose.Words:

• Mail merge переключатели полей: MERGEFIELD FirstName \\\\\\\\* FirstCap \b "Mr. "
• вложенные поля слияния в формуле: IF { MERGEFIELDValue1 } >= {MERGEFIELD Value2 } True False
• вычислите имя поля слияния во время выполнения: MERGEFIELD { IF{MERGEFIELDValue1 } >= {MERGEFIELD Value2 } FirstName"LastName" }
• условный переход к следующей записи в источнике данных: NEXTIF { MERGEFIELDValue1 } <= { =IF(-2.45 >= 6*{MERGEFIELD Value2 }, 2, -.45) }

Переключатели форматов

Поле в документе может иметь параметры форматирования, которые определяют, как должно быть отформатировано результирующее значение. Aspose.Words поддерживает следующие параметры форматирования:

• @ – форматирование даты и времени
• \# – форматирование чисел
• \\\\* Caps
• \\\\* FirstCap
• \\\\* Lower
• \\\\* Upper
• \\\\* CHARFORMAT – форматирование результата в соответствии с первым символом кода поля
• \\\\* MERGEFORMAT – отформатируйте результат в соответствии с тем, как был отформатирован старый результат

Форматирование даты и чисел в полях

Когда Aspose.Words вычисляет результат работы с полем, ему часто требуется преобразовать строку в число или значение даты, а также отформатировать ее обратно в строку.По умолчанию Aspose.Words использует текущую структуру потока для выполнения синтаксического анализа и форматирования при вычислении значений полей во время обновления поля и mail merge. Существуют также опции, представленные в виде класса FieldOptions, которые позволяют дополнительно контролировать, какой регион используется при обновлении поля%

• по умолчанию свойству FieldUpdateCultureSource присвоено значение CurrentThread, что позволяет форматировать поля, используя текущие параметры потока
• этому свойству можно присвоить значение FieldCode, чтобы вместо него для форматирования использовался язык, указанный в коде поля

Форматирование с использованием культуры текущего потока

Чтобы управлять культурой, используемой при расчете поля, просто установите для свойства CurrentCulture значение культуры по вашему выбору перед вызовом расчета поля.

В следующем примере кода показано, как изменить региональные параметры, используемые в полях форматирования во время обновления:

EXAMPLE (используйте общедоступную оболочку CurrentThreadSettings.getLocale() и setLocale() вместо частной Thread.CurrentThread.CurrentCulture)

Использование существующих стандартов для форматирования полей позволяет системе легко и последовательно управлять форматированием всех полей в документе во время обновления полей.

Форматирование с использованием региональных параметров документа

С другой стороны, Microsoft Word форматирует каждое отдельное поле на основе языка текста, найденного в поле (в частности, на основе кода поля). Иногда при обновлении полей это может быть желательным, например, если у вас есть глобализированные документы, содержащие содержимое на многих разных языках, и вы хотите, чтобы каждое поле соответствовало языковому стандарту, используемому в тексте. Aspose.Words также поддерживает эту функциональность.

Класс Document предоставляет свойство FieldOptions, которое содержит элементы, которые можно использовать для управления обновлением полей в документе.

В следующем примере кода показано, как указать, из какого источника выбирается региональная структура, используемая для форматирования даты при обновлении поля, и Mail Merge:

EXAMPLE