Inserir Campos

Existem várias maneiras diferentes de inserir campos em um documento:

• usando DocumentBuilder
• usando FieldBuilder
• utilização Aspose.Words Modelo De Objecto Do Documento (DOM)

Neste artigo, examinaremos cada forma com mais detalhes e analisaremos como inserir determinados campos usando essas opções.

Inserir campos num documento utilizando DocumentBuilder

Em Aspose.Words o método InsertField é utilizado para inserir novos campos num documento. O primeiro parâmetro aceita o código de campo completo do campo a inserir. O segundo parâmetro é opcional e permite que o resultado do campo seja definido manualmente. Se isso não for fornecido, o campo é atualizado automaticamente. Você pode passar null ou empty para este parâmetro para inserir um campo com um valor de campo vazio. Se você não tiver certeza sobre a sintaxe do código de campo específico, crie o campo em Microsoft Word Primeiro e alterne para ver seu código de campo.

Se o seu código de campo tiver um parâmetro contendo um espaço, ele deve ser colocado dentro de marcas de fala. Caso contrário, o campo em Microsoft Word e Aspose.Words pode não funcionar como esperado, pois o parâmetro é tratado por ambos como truncado.

O exemplo de código a seguir mostra como inserir um campo de mesclagem em um documento usando 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");

A mesma técnica é usada para inserir campos aninhados em outros campos.

O exemplo de código a seguir demonstra como inserir campos aninhados em outro campo usando 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");

Especificar localidade ao nível do campo

Um identificador de idioma é uma abreviatura numérica internacional padrão para o idioma em um país ou região geográfica. Com Aspose.Words, você pode especificar a localidade no nível do campo usando a propriedade LocaleId, que obtém ou define a localidade do campo ID.

O exemplo de código a seguir mostra como usar essa opção:

// 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");

Inserir Campo Não Digitado / Vazio

Se você deseja inserir campos não digitados / vazios ({}) da mesma forma que Microsoft Word permite, você pode usar o método InsertField com o parâmetro FieldType.FieldNone. Para inserir um campo em um documento do Word, você pode pressionar a combinação de teclas “Ctrl + F9”.

O exemplo de código a seguir mostra como inserir um campo vazio no documento:

// 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");

Inserir Campo COMPARE

O campo COMPARE compara dois valores e devolve o valor numérico 1 se a comparação for verdadeira ou 0 se a comparação for falsa.

O exemplo de código a seguir mostra como adicionar campos COMPARE Usando 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");

Inserir Campo IF

O campo IF pode ser usado para avaliar argumentos condicionalmente.

O exemplo de código a seguir mostra como adicionar campos IF Usando 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");

Inserir campos num documento utilizando FieldBuilder

A forma alternativa de inserir campos em Aspose.Words é a classe FieldBuilder. Ele fornece interface fluente para especificar comutadores de campo e valores de argumento como texto, nós ou mesmo campos aninhados.

O exemplo de código a seguir mostra como inserir um campo em um documento usando 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");

Inserir Campos utilizando DOM

Você também pode inserir vários tipos de campos usando Aspose.Words Modelo De Objecto Do Documento (DOM). Nesta secção, veremos alguns exemplos.

Inserindo o campo de mesclagem em um documento usando DOM

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

• especifique o nome do campo de mesclagem
• especifique a formatação do campo de mesclagem
• especifique o texto que está entre o separador de campo e o fim do campo do campo de mesclagem
• especifique o texto a ser inserido após o campo de mesclagem se o campo não estiver em branco
• especifique o texto a ser inserido antes do campo de mesclagem se o campo não estiver em branco

Para obter mais detalhes, consulte a classe FieldMergeField API.

O exemplo de código a seguir mostra como adicionar o campo MERGE usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo Mail Merge ADDRESSBLOCK num documento utilizando DOM

O campo ADDRESSBLOCK é utilizado para inserir um bloco de endereços Mail Merge num documento do Word. O campo ADDRESSBLOCK no documento do Word pode ser representado pela classe FieldAddressBlock. Você pode usar a classe FieldAddressBlock para executar as seguintes operações:

• especificar se deve incluir o nome do país / região no campo
• especificar se deve formatar o endereço de acordo com o país / região do destinatário, tal como definido em POST * CODE (União Postal Universal 2006)
• especificar o nome do país/região excluído
• especificar o nome e o formato do endereço
• especificar o idioma ID utilizado para formatar o endereço

Para obter mais detalhes, consulte a classe FieldAddressBlock API.

O exemplo de código a seguir mostra como adicionar o campo Mail Merge ADDRESSBLOCK usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo ADVANCE num documento sem utilizar DocumentBuilder

O campo ADVANCE é utilizado para deslocar o texto subsequente dentro de uma linha à esquerda, à direita, para cima ou para baixo. O campo ADVANCE no documento do Word pode ser representado pela classe FieldAdvance. Você pode usar a classe FieldAdvance para executar as seguintes operações:

• especifique o número de pontos pelos quais o texto que segue o campo deve ser movido verticalmente a partir da borda superior da página
• especifique o número de pontos pelos quais o texto que segue o campo deve ser movido horizontalmente a partir da borda esquerda da coluna, quadro ou caixa de texto
• especificar o número de pontos pelos quais o texto que segue o campo deve ser movido para a esquerda, direita, para cima ou para baixo

Para obter mais detalhes, consulte a classe FieldAdvance API.

O exemplo de código a seguir mostra como adicionar o campo ADVANCE usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo ASK num documento sem utilizar DocumentBuilder

O campo ASK é utilizado para solicitar ao utilizador que o texto atribua a um marcador no documento do Word. O campo ASK no documento do Word pode ser representado pela classe FieldAsk. Você pode usar a classe FieldAsk para executar as seguintes operações:

• especifique o nome do marcador
• especifique a resposta padrão do Usuário (valor inicial contido na janela do prompt)
• especificar se a resposta do utilizador deve ser recebida uma vez por uma operação Mail Merge
• especifique o texto do prompt (O título da janela do prompt)

Para obter mais detalhes, consulte a classe FieldAsk API.

O exemplo de código a seguir mostra como adicionar o campo ASK usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo AUTHOR num documento sem utilizar DocumentBuilder

O campo AUTHOR é utilizado para especificar o nome do autor do documento a partir das propriedades Document. O campo AUTHOR no documento do Word pode ser representado pela classe FieldAuthor. Você pode usar a classe FieldAuthor para executar as seguintes operações:

• especificar o nome do autor do documento

Para obter mais detalhes, consulte a classe FieldAuthor API.

O exemplo de código a seguir mostra como adicionar o campo AUTHOR usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo INCLUDETEXT num documento sem utilizar DocumentBuilder

O campo INCLUDETEXT insere o texto e os gráficos contidos no documento indicado no código do campo. Pode inserir o documento inteiro ou uma parte do documento referido por um marcador. Este campo no documento do Word é representado por INCLUDETEXT. Você pode usar a classe FieldIncludeText para executar as seguintes operações:

• especificar o nome do marcador do documento incluído
• especificar a localização do documento

Para obter mais detalhes, consulte a classe FieldIncludeText API.

O exemplo de código a seguir mostra como adicionar o campo INCLUDETEXT usando DOM a um parágrafo em um documento:

// 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");

Inserir o campo TOA num documento sem utilizar DocumentBuilder

O campo TOA (Table of Authorities) cria e insere uma tabela de autoridades. O campo TOA recolhe entradas marcadas por campos TA (Table of Authorities Entry). Microsoft o Office Word insere o campo TOA quando clica em Insert Table of Authorities no grupo Table of Authorities no separador References. Quando visualiza o campo TOA no documento, a sintaxe é semelhante a esta:

{ TOA [Switches ] }

Para obter mais detalhes, consulte a classe FieldToa API.

O exemplo de código a seguir mostra como adicionar o campo TOA usando DOM a um parágrafo em um documento.

// 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");