Вставка полей

Существует несколько различных способов вставки полей в документ:

• используя DocumentBuilder
• используя FieldBuilder
• с помощью Aspose.Words Объектная модель документа (DOM)

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

Вставка полей в документ с помощью DocumentBuilder

В Aspose.Words метод InsertField используется для вставки новых полей в документ. Первый параметр принимает полный код вставляемого поля. Второй параметр является необязательным и позволяет вручную задать результат заполнения поля. Если это значение не указано, поле обновляется автоматически. Вы можете задать значение null или empty в этом параметре, чтобы вставить поле с пустым значением. Если вы не уверены в синтаксисе конкретного кода поля, сначала создайте поле в Microsoft Word и переключитесь на просмотр его кода.

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

В следующем примере кода показано, как вставить поле слияния в документ с помощью DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(InsertField.class);

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD MyFieldName \\* MERGEFORMAT");

doc.save(dataDir + "output.docx");

Тот же метод используется для вставки полей, вложенных в другие поля.

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

for (int i = 0; i < 5; i++)
    builder.insertBreak(BreakType.PAGE_BREAK);

builder.moveToHeaderFooter(HeaderFooterType.FOOTER_PRIMARY);

// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
Field field = builder.insertField("IF ");
builder.moveTo(field.getSeparator());
builder.insertField("PAGE");
builder.write(" <> ");
builder.insertField("NUMPAGES");
builder.write(" \"See Next Page\" \"Last Page\" ");

field.update();

doc.save(getArtifactsDir() + "WorkingWithFields.InsertNestedFields.docx");

Укажите языковой стандарт на уровне поля

Идентификатор языка - это стандартное международное цифровое сокращение для обозначения языка в стране или географическом регионе. С помощью Aspose.Words вы можете указать языковой стандарт на уровне поля, используя свойство LocaleId, которое возвращает или задает языковой стандарт поля ID.

В следующем примере кода показано, как использовать эту опцию:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
DocumentBuilder builder = new DocumentBuilder();

Field field = builder.insertField(FieldType.FIELD_DATE, true);
field.setLocaleId(1049);

builder.getDocument().save(getArtifactsDir() + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

Вставить Нетипизированное/пустое поле

Если вы хотите вставить нетипизированные/пустые поля ({}) так, как позволяет Microsoft Word, вы можете использовать метод InsertField с параметром FieldType.FieldNone. Чтобы вставить поле в документ Word, вы можете нажать комбинацию клавиш “Ctrl + F9”.

В следующем примере кода показано, как вставить пустое поле в документ:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

FieldUnknown field = (FieldUnknown) builder.insertField(FieldType.FIELD_NONE, false);

doc.save(getArtifactsDir() + "WorkingWithFields.InsertFieldNone.docx");

Вставить поле COMPARE

Поле COMPARE сравнивает два значения и возвращает числовое значение 1, если сравнение истинно, или 0, если сравнение ложно.

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

FieldCompare field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("3");
field.setComparisonOperator("<");
field.setRightExpression("2");
field.update();

builder.writeln();

field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.COMPARE.docx");

Вставить поле IF

Поле IF может использоваться для условной оценки аргументов.

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.write("Statement 1: ");
FieldIf field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("0");
field.setComparisonOperator("=");
field.setRightExpression("1");

// The IF field will display a string from either its "TrueText" property,
// or its "FalseText" property, depending on the truth of the statement that we have constructed.
field.setTrueText("True");
field.setFalseText("False");
field.update();

builder.write("\nStatement 2: ");
field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.setTrueText("True");
field.setFalseText("False");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.IF.docx");

Вставка полей в документ с помощью FieldBuilder

Альтернативным способом вставки полей в Aspose.Words является класс FieldBuilder. Он предоставляет удобный интерфейс для указания переключателей полей и значений аргументов в виде текста, узлов или даже вложенных полей.

В следующем примере кода показано, как вставить поле в документ с помощью FieldBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

FieldBuilder firstName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
firstName.addArgument("firstname");
FieldBuilder lastName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
lastName.addArgument("lastname");

FieldArgumentBuilder firstnameArgumentBuilder = new FieldArgumentBuilder();
firstnameArgumentBuilder.addText("Firstname: ");
firstnameArgumentBuilder.addField(firstName);

FieldArgumentBuilder lastnameArgumentBuilder = new FieldArgumentBuilder();
lastnameArgumentBuilder.addText("Lastname: ");
lastnameArgumentBuilder.addField(lastName);

// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
fieldBuilder.addArgument("left expression");
fieldBuilder.addArgument("=");
fieldBuilder.addArgument("right expression");
fieldBuilder.addArgument(firstnameArgumentBuilder);
fieldBuilder.addArgument(lastnameArgumentBuilder);

// Insert IF field in exact location
Field field = fieldBuilder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
field.update();

doc.save(getArtifactsDir() + "Field.InsertFieldUsingFieldBuilder.docx");

Вставка полей с помощью DOM

Вы также можете вставлять поля различных типов, используя Aspose.Words Объектную модель документа (DOM). В этом разделе мы рассмотрим несколько примеров.

Вставка поля слияния в документ с помощью DOM

MERGEFIELD field in Word document can be represented by the FieldMergeField class. You can use FieldMergeField class to perform the following operations:

• укажите название поля для объединения
• укажите форматирование поля для объединения
• укажите текст, который находится между разделителем полей и концом поля в поле объединения
• укажите текст, который будет вставлен после поля объединения, если это поле не является пустым
• укажите текст, который будет вставлен перед полем объединения, если это поле не является пустым

Для получения более подробной информации смотрите класс FieldMergeField API.

В следующем примере кода показано, как добавить поле MERGE с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);
builder.moveTo(para);

// We want to insert a merge field like this:
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
FieldMergeField field = (FieldMergeField) builder.insertField(FieldType.FIELD_MERGE_FIELD, false);

// { " MERGEFIELD Test1" }
field.setFieldName("Test1");
// { " MERGEFIELD Test1 \\b Test2" }
field.setTextBefore("Test2");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field.setTextAfter("Test3");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" }
field.isMapped(true);
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
field.isVerticalFormatting(true);

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertMergeFieldUsingDOM.docx");

Вставка поля Mail Merge ADDRESSBLOCK в документ с помощью DOM

Поле ADDRESSBLOCK используется для вставки адресного блока Mail Merge в документ Word. Поле ADDRESSBLOCK в документе Word может быть представлено классом FieldAddressBlock. Класс FieldAddressBlock можно использовать для выполнения следующих операций:

• укажите, следует ли указывать название страны/региона в этом поле
• укажите, следует ли форматировать адрес в соответствии со страной/регионом получателя, как указано в POST*CODE (Всемирный почтовый союз, 2006)
• укажите название исключенной страны/региона
• укажите формат имени и адреса
• укажите язык ID, используемый для форматирования адреса

Для получения более подробной информации смотрите класс FieldAddressBlock API.

В следующем примере кода показано, как добавить поле Mail Merge ADDRESSBLOCK с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);
builder.moveTo(para);

// We want to insert a mail merge address block like this:
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
FieldAddressBlock field = (FieldAddressBlock) builder.insertField(FieldType.FIELD_ADDRESS_BLOCK, false);

// { ADDRESSBLOCK \\c 1" }
field.setIncludeCountryOrRegionName("1");
// { ADDRESSBLOCK \\c 1 \\d" }
field.setFormatAddressOnCountryOrRegion(true);
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field.setExcludedCountryOrRegionName("Test2");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field.setNameAndAddressFormat("Test3");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field.setLanguageId("Test 4");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

Вставка поля ADVANCE в документ без использования DocumentBuilder

Поле ADVANCE используется для смещения последующего текста в строке влево, вправо, вверх или вниз. Поле ADVANCE в документе Word может быть представлено классом FieldAdvance. Класс FieldAdvance можно использовать для выполнения следующих операций:

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

Для получения более подробной информации смотрите класс FieldAdvance API.

В следующем примере кода показано, как добавить поле ADVANCE с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an Advance field like this:
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
FieldAdvance field = (FieldAdvance) para.appendField(FieldType.FIELD_ADVANCE, false);

// { ADVANCE \\d 10 " }
field.setDownOffset("10");
// { ADVANCE \\d 10 \\l 10 }
field.setLeftOffset("10");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field.setRightOffset("-3.3");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field.setUpOffset("0");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field.setHorizontalPosition("100");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field.setVerticalPosition("100");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.docx");

Вставка поля ASK в документ без использования DocumentBuilder

Поле ASK используется для запроса текста, который пользователь должен присвоить закладке в документе Word. Поле ASK в документе Word может быть представлено классом FieldAsk. Класс FieldAsk можно использовать для выполнения следующих операций:

• укажите название закладки
• укажите ответ пользователя по умолчанию (начальное значение, содержащееся в окне запроса)
• укажите, должен ли ответ пользователя быть получен один раз за операцию Mail Merge
• укажите текст запроса (заголовок окна запроса)

Для получения более подробной информации смотрите класс FieldAsk API.

В следующем примере кода показано, как добавить поле ASK с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an Ask field like this:
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
FieldAsk field = (FieldAsk) para.appendField(FieldType.FIELD_ASK, false);

// { ASK \"Test 1\" " }
field.setBookmarkName("Test 1");
// { ASK \"Test 1\" Test2 }
field.setPromptText("Test2");
// { ASK \"Test 1\" Test2 \\d Test3 }
field.setDefaultResponse("Test3");
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field.setPromptOnceOnMailMerge(true);

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.docx");

Вставка поля AUTHOR в документ без использования DocumentBuilder

Поле AUTHOR используется для указания имени автора документа в свойствах Document. Поле AUTHOR в документе Word может быть представлено классом FieldAuthor. Вы можете использовать класс FieldAuthor для выполнения следующих операций:

• укажите имя автора документа

Для получения более подробной информации смотрите класс FieldAuthor API.

В следующем примере кода показано, как добавить поле AUTHOR с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an AUTHOR field like this:
// { AUTHOR Test1 }
FieldAuthor field = (FieldAuthor) para.appendField(FieldType.FIELD_AUTHOR, false);
field.setAuthorName("Test1"); // { AUTHOR Test1 }

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAuthorField.docx");

Вставка поля INCLUDETEXT в документ без использования DocumentBuilder

В поле INCLUDETEXT вставляется текст и графические изображения, содержащиеся в документе, название которого указано в коде поля. Вы можете вставить весь документ или часть документа, на который ссылается закладка. Это поле в документе Word обозначается символом INCLUDETEXT. Вы можете использовать класс FieldIncludeText для выполнения следующих операций:

• укажите название закладки для включенного документа
• укажите местоположение документа

Для получения более подробной информации смотрите класс FieldIncludeText API.

В следующем примере кода показано, как добавить поле INCLUDETEXT с помощью DOM в абзац документа:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = new Paragraph(doc);

// We want to insert an INCLUDETEXT field like this:
// { INCLUDETEXT  "file path" }
FieldIncludeText fieldIncludeText = (FieldIncludeText) para.appendField(FieldType.FIELD_INCLUDE_TEXT, false);
fieldIncludeText.setBookmarkName("bookmark");
fieldIncludeText.setSourceFullName(getMyDir() + "IncludeText.docx");

doc.getFirstSection().getBody().appendChild(para);

fieldIncludeText.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

Вставка поля TOA в документ без использования DocumentBuilder

В поле TOA (Table of Authorities) создается и вставляется таблица полномочий. В поле TOA собираются записи, помеченные полями TA (Table of Authorities Entry). Microsoft Office Word вставляет поле TOA, когда вы нажимаете Insert Table of Authorities в группе Table of Authorities на вкладке References. При просмотре поля TOA в вашем документе синтаксис будет выглядеть следующим образом:

{ TOA [Switches ] }

Для получения более подробной информации смотрите класс FieldToa API.

В следующем примере кода показано, как добавить поле TOA с помощью DOM в абзац документа.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
Paragraph para = new Paragraph(doc);

// We want to insert TA and TOA fields like this:
// { TA  \c 1 \l "Value 0" }
// { TOA  \c 1 }
FieldTA fieldTA = (FieldTA) para.appendField(FieldType.FIELD_TOA_ENTRY, false);
fieldTA.setEntryCategory("1");
fieldTA.setLongCitation("Value 0");

doc.getFirstSection().getBody().appendChild(para);

para = new Paragraph(doc);

FieldToa fieldToa = (FieldToa) para.appendField(FieldType.FIELD_TOA, false);
fieldToa.setEntryCategory("1");
doc.getFirstSection().getBody().appendChild(para);

fieldToa.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");