Створення полів за допомогою FieldBuilder

Цей посібник показує, як створити поле Word з нуля у Aspose.Words FOSS для .NET, використовуючи FieldBuilder and FieldArgumentBuilder, замість роботи з полем, яке вже існує в документі. Для читання, оновлення чи видалення існуючих полів, дивіться Робота з полями посібник.

Створення поля за допомогою FieldBuilder

FieldBuilder створює поле з токенів коду поля — аргументів і перемикачів. Створіть його за допомогою new FieldBuilder(fieldType), передаючи FieldType поля, яке ви хочете створити. Додавайте аргументи за допомогою перевантаженого методу AddArgument(argument), який приймає string, int, double, вкладений FieldBuilder або FieldArgumentBuilder. Додавайте перемикачі за допомогою перевантажених методів AddSwitch(switchName), AddSwitch(switchName, switchArgument) (string) або AddSwitch(switchName, switchArgument) (int/double).

Вставка створеного поля

Коли FieldBuilder має свої аргументи та перемикачі, викличте BuildAndInsert(refNode), щоб вставити його в документ — одна перевантажена версія приймає вузол Inline і вставляє поле перед ним, інша приймає Paragraph і вставляє поле в кінець цього абзацу.

Складання складних аргументів за допомогою FieldArgumentBuilder

FieldArgumentBuilder створює складний аргумент поля, що складається з полів, вузлів і простого тексту, для випадків, коли одному аргументу потрібно більше, ніж простий рядок. Створіть його за допомогою new FieldArgumentBuilder(), потім викличте AddText(text), щоб додати простий текст, AddNode(node), щоб додати вузол Inline, або AddField(fieldBuilder), щоб вкласти інше поле (побудоване за допомогою його власного FieldBuilder) всередину аргументу. Передайте завершений FieldArgumentBuilder у FieldBuilder.AddArgument(argument), щоб використати його як один з аргументів зовнішнього поля.

Поради та найкращі практики

Використовуйте FieldBuilder, коли створюєте тип поля, який не підтримується жодним із спеціалізованих класів полів (наприклад, FieldDate або FieldSymbol), або коли генеруєте коди полів програмно з даних, а не вручну.
Вкладіть дочірнє поле всередину аргументу зовнішнього поля за допомогою FieldBuilder.AddArgument(FieldBuilder) у простому випадку, або створіть змішаний аргумент тексту, вузлів і вбудованих полів за допомогою FieldArgumentBuilder, коли аргумент складається більше, ніж з одного поля.
Виберіть перевантаження BuildAndInsert(refNode), яке відповідає місцю, куди ви хочете розташувати поле — перед конкретним вузлом Inline або в кінці Paragraph.
Після BuildAndInsert обробляйте результат як будь-яке інше поле в дереві — наприклад, викличте Update() для нього, якщо тип поля вимагає явного перерахунку.

Поширені проблеми

Проблема	Причина	Виправлення
`BuildAndInsert` націлюється на неправильне місце	Було використано неправильне перевантаження для запланованої точки вставки	Передайте вузол `Inline`, щоб вставити перед ним, або `Paragraph`, щоб вставити в його кінець
Аргумент поля не приймає одночасно простий текст і вузол	`AddArgument` було викликано з одним `string`/`int`/`double` замість складеного аргументу	Сформуйте змішаний аргумент за допомогою `FieldArgumentBuilder` (`AddText`, `AddNode`, `AddField`) і передайте його до `AddArgument`
Значення перемикача не розпізнається у згенерованому коді поля	`AddSwitch(switchName)` було використано, хоча перемикач насправді потребує аргументу	Використайте перевантаження `AddSwitch(switchName, switchArgument)` зі строковим, цілим або double значенням перемикача

FAQ

Коли слід використовувати FieldBuilder замість вставки готового коду поля?

Використовуйте FieldBuilder, коли потрібен явний контроль над аргументами та перемикачами поля під час їх програмного формування, а не вставка готового рядка коду поля.

Як додати до поля більше одного аргументу?

Викличте AddArgument один раз для кожного аргументу — він перевантажений для string, int, double, вкладеного FieldBuilder та FieldArgumentBuilder.

Чи можу я створити поле, аргумент якого містить суміш тексту та іншого поля?

Так — використайте FieldArgumentBuilder, викликаючи AddText, AddNode та AddField за потреби, а потім передайте це до FieldBuilder.AddArgument.

Як фактично вставити створене поле в документ?

Викличте BuildAndInsert(refNode), передаючи або вузол Inline (вставляє перед ним), або Paragraph (вставляє в його кінець).

API Reference Підсумок

Клас/Метод	Опис
`FieldBuilder`	Створює поле з токенів коду поля (аргументи та перемикачі)
`FieldBuilder(fieldType)`	Конструктор, який приймає `FieldType` для створення
`FieldBuilder.AddArgument(argument)`	Додає аргумент (`string`, `int`, `double`, `FieldBuilder` або `FieldArgumentBuilder`)
`FieldBuilder.AddSwitch(switchName)` / `AddSwitch(switchName, switchArgument)`	Додає перемикач поля, з або без значення
`FieldBuilder.BuildAndInsert(refNode)`	Вставляє створене поле перед вузлом `Inline` або в кінець `Paragraph`
`FieldArgumentBuilder`	Створює складний аргумент поля з тексту, вузлів та вкладених полів
`FieldArgumentBuilder.AddText(text)`	Додає простий текст до аргументу
`FieldArgumentBuilder.AddNode(node)`	Додає вузол `Inline` до аргументу
`FieldArgumentBuilder.AddField(fieldBuilder)`	Вбудовує поле, створене `FieldBuilder`, у аргумент

Дивіться також

Aspose.Words for .NET — Enterprise Documentation