Visão geral dos campos

Normalmente um campo, quando inserido no Microsoft Word, já contém um valor atualizado. Por exemplo, se o campo for uma fórmula ou um número de página, ele conterá um valor calculado correto para determinada versão do documento. Mas se você tiver um aplicativo que gera ou modifica um documento com campos (por exemplo, combina dois documentos ou preenche com dados), para que o documento seja útil, o ideal é que todos os campos sejam atualizados.

Um campo consiste em:

• Os nós de início e separador de campo são usados para abranger o conteúdo que compõe o código do campo (normalmente como texto simples)
• O separador de campo e o final do campo abrangem o resultado do campo. Isso pode ser composto de vários tipos de conteúdo, desde trechos de texto até parágrafos e tabelas.
• Alguns campos podem não ter separador, o que significa que todo o conteúdo constitui o código do campo.
• O código do campo define o comportamento do campo e é composto pelo identificador do campo e, muitas vezes, por outros parâmetros, como nome do campo e opções.
• O resultado do campo contém a avaliação mais recente do campo. Este valor é armazenado no resultado do campo e é o que é exibido ao usuário. Alguns campos podem não ter nenhum resultado de campo, portanto, não exibirão nada no documento. Da mesma forma, alguns campos podem ainda não estar atualizados e portanto também não terão resultado de campo.

Aqui está uma visão de como um campo é armazenado em Aspose.Words usando o exemplo “DocumentExplorer” que pode ser encontrado em GitHub.

Aspose.Words é uma biblioteca de classes projetada para processamento de documentos Microsoft Word no servidor e oferece suporte a campos das seguintes maneiras:

• Todos os campos de um documento são preservados durante a abertura/salvamento e conversões.
• É possível atualizar resultados de alguns dos campos mais populares.

Campos em Microsoft Word

Os campos em documentos Microsoft Word são complexos. Existem mais de 50 tipos de campos (cada um precisa de seu próprio procedimento de cálculo de resultados), fórmulas e expressões, marcadores e referências, funções e várias opções. Os campos também podem ser aninhados. Normalmente quando um documento é aberto, o resultado do campo (o valor do campo) é mostrado para todos os campos do documento. Você pode alternar a exibição do resultado do campo ou dos códigos de campo em Microsoft Word para todos os campos pressionando ALT+F9.

Código de campo	Resultado do campo

Inserindo campos em Microsoft Word

Para inserir um campo em Microsoft Word:

1. Clique no menu Insert.
2. Clique no menu suspenso Quick Parts
3. Selecione Field
4. É apresentada uma tela que permite inserir os detalhes do campo. No lado esquerdo você recebe uma lista dos campos possíveis e no lado direito uma tela para editar visualmente as propriedades do campo.
   
5. Além disso, você pode pressionar o botão Field Codes que permite escrever diretamente o código de campo.
   
6. Os switches também podem ser inseridos usando o botão Options
   
7. Usando qualquer um dos métodos, preencha os campos desejados com as informações apropriadas e pressione Ok.
8. O campo é inserido no documento na posição atual do cursor.
   

Atualizando campos em Microsoft Word

Para atualizar um único campo em Microsoft Word:

1. Mova o cursor para o campo que deseja atualizar.
2. Pressione F9 para atualizar o campo.

Para atualizar todos os campos em Microsoft Word:

1. Pressione Ctrl+A para selecionar todo o conteúdo do documento.
2. Pressione F9 para atualizar todos os campos encontrados na seleção.

Alternando entre exibição de código de campo e resultado de campo

Para alternar códigos de campo de um único campo em Microsoft Word:

1. Mova o cursor para o campo desejado.
2. Pressione MUDANÇA+F9 para alternar o código de campo apenas para este campo.

Para alternar os códigos de campo de todos os campos em Microsoft Word:

1. Pressione ALT+F9

Convertendo campos em texto estático em Microsoft Word

Para converter um campo dinâmico em texto estático em Microsoft Word:

1. Mova o cursor para o campo que deseja converter.
2. Pressione Ctrl+Shift+F9 para converter os campos em texto estático.

Removendo um campo em Microsoft Word

Para remover um campo em Microsoft Word:

1. Selecione todo o conteúdo que compõe o campo. Se os códigos de campo forem exibidos, as chaves de abertura e final também deverão ser selecionadas.
2. Pressione Delete para remover todo o campo.

Campos em Aspose.Words

Quando um documento é carregado no Aspose.Words, os campos do documento são carregados no Aspose.Words Document Object Model como um conjunto de componentes separados (nós). Um único campo é carregado como uma coleção de nós FieldStart, FieldSeparator e FieldEnd junto com o conteúdo entre esses nós. Se um campo não tiver um resultado de campo, não haverá nó FieldSeparator. Todos esses nós são sempre encontrados em linha (como filhos de Paragraph ou SmartTag.

O conteúdo que compõe o código do campo é armazenado como nós Run entre o FieldStart e o FieldSeparator. O resultado do campo é armazenado entre os nós FieldSeparator e FieldEnd e pode ser composto por vários tipos de conteúdo. Normalmente o resultado do campo contém apenas texto composto por nós Run, porém é possível que o nó FieldEnd esteja localizado em um parágrafo completamente diferente, tornando o resultado do campo composto também por nós de nível de bloco, como nós Table e Paragraph.

No Aspose.Words, cada um dos nós FieldXXX deriva de FieldChar. Esta classe fornece uma propriedade para verificar o tipo de campo representado pelo nó especificado através da propriedade FieldChar.field_type. Por exemplo, FieldType.FIELD_MERGE_FIELD representa um campo de mesclagem no documento.

Existem alguns campos específicos em um documento do Word que não são importados para Aspose.Words como uma coleção de nós FieldXXX. Por exemplo, o campo LINK e o campo INCLUDEPICTURE são importados para Aspose.Words como um objeto Shape. Este objeto fornece propriedades para trabalhar com os dados de imagem normalmente armazenados nesses campos.

Os campos do formulário também são importados para o Aspose.Words como sua própria classe especial. A classe FormField representa um campo de formulário em um documento do Word e fornece métodos adicionais específicos de um campo de formulário.

Campos suportados durante a atualização

O cálculo dos seguintes campos é suportado na versão atual do Aspose.Words:

• = (campo de fórmula)
• ADDRESSBLOCK
• AUTHOR
• COMPARE
• CREATEDATE
• DATE
• DOCPROPERTY
• DOCVARIABLE
• GREETINGLINE
• IF
• INCLUDETEXT
• MERGEFIELD
• MERGEREC
• MERGESEQ
• NEXT
• NEXTIF
• NUMPAGES
• PAGE
• PAGEREF
• REF
• SECTION
• SECTIONPAGES
• SEQ
• SET
• STYLEREF
• TIME
• TITLE
• TOA
• TOC (incluindo TOT e TOF) -TC

Análise sofisticada

Aspose.Words segue a forma como o Microsoft Word processa os campos e como resultado ele trata corretamente:

• Campos aninhados : IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
• O argumento do campo pode ser resultado de um campo aninhado.
• Os campos podem ser aninhados dentro de um código de campo, bem como no resultado do campo.
• Espaços/sem espaços, aspas/sem aspas, caracteres de escape em campos etc.: MERGEFIELD \f"Text after""Field \n\ame with \" and \\\ and \\\*"\bTextBefor\e
• Campos que abrangem vários parágrafos.

Campos de Fórmula

Aspose.Words fornece uma implementação muito séria do mecanismo de fórmula e oferece suporte ao seguinte:

• Operadores aritméticos e lógicos: =(54+4*(6-77)-(5))+(-6-5)/4/5
• Funções: =ABS(-01.4)+2.645/(5.6^3.5)+776457 \\\# "#,##0"
• Referências a marcadores: =IF(C>4, 5,ABS(A)*.76) +3.85
• Opções de formatação de números: =00000000 \\\# "$#,##0.00;($#,##0.00)"

As seguintes funções em expressões são suportadas: ABS, AND, AVERAGE, COUNT, DEFINED, FALSE, IF, INT, MAX, MIN, MOD, NOT, OR, PRODUCT, ROUND, SIGN, SUM, TRUE.

Campos IF e COMPARE

Apenas algumas das expressões IF que o Aspose.Words pode calcular facilmente devem dar uma ideia de quão poderoso é esse recurso:

• 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

Campos DATE e TIME

Aspose.Words suporta todas as opções de formatação de data e hora disponíveis em Microsoft Word, alguns exemplos são:

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

Campos Mail Merge

Aspose.Words não impõe limites à complexidade dos campos Mail Merge em seus documentos e oferece suporte a campos IF e de fórmula aninhados e pode até calcular o nome do campo de mesclagem usando uma fórmula.

Alguns exemplos de campos Mail Merge compatíveis com Aspose.Words:

• Alternadores de campo Mail merge: MERGEFIELD FirstName \\\\\\\\* FirstCap \b "Mr. "
• Campos de mesclagem aninhados em uma fórmula: IF { MERGEFIELDValue1 } >= {MERGEFIELD Value2 } True False
• Calcule o nome do campo de mesclagem em tempo de execução: MERGEFIELD { IF{MERGEFIELDValue1 } >= {MERGEFIELD Value2 } FirstName"LastName" }
• Movimento condicional para o próximo registro na fonte de dados: NEXTIF { MERGEFIELDValue1 } <= { =IF(-2.45 >= 6*{MERGEFIELD Value2 }, 2, -.45) }

Opções de formato

Um campo em um documento pode ter opções de formatação que especificam como o valor resultante deve ser formatado. Aspose.Words oferece suporte às seguintes opções de formato:

• @ - formatação de data e hora
• \# - formatação de números
• \\\\* Cápsulas
• \\\\* Primeira Cap
• \\\\* Mais baixo
• \\\\* Superior
• \\\\* CHARFORMAT – formata o resultado de acordo com o primeiro caractere do código do campo.
• \\\\* MERGEFORMAT – formata o resultado de acordo com a formatação do resultado antigo.

Date e formatação de números em campos

Quando o Aspose.Words calcula o resultado de um campo, muitas vezes ele precisa analisar uma string em um número ou valor de data e também formatá-la de volta para uma string. Por padrão, o Aspose.Words usa a cultura de thread atual para realizar a análise e formatação ao calcular valores de campo durante a atualização do campo e mail merge. Também existem opções fornecidas na forma de classe FieldOptions que permitem maior controle sobre qual cultura é usada durante a atualização do campo.

• Por padrão a propriedade FieldOptions.field_update_culture_source é definida como FieldUpdateCultureSource.CURRENT_THREAD que formata os campos usando a cultura do thread atual.
• Esta propriedade pode ser definida como FieldUpdateCultureSource.FIELD_CODE para que o idioma definido no código do campo seja usado para formatação.

Formatando usando a cultura do thread atual

Para controlar a cultura usada durante o cálculo do campo, basta usar o método locale.setlocale para definir a cultura de sua escolha antes de invocar o cálculo do campo. O exemplo abaixo mostra como alterar a cultura usada na formatação de campos durante a atualização.

Usar a cultura atual para formatar campos permite que um sistema controle de forma fácil e consistente como todos os campos do documento são formatados durante a atualização do campo.

Formatando usando a cultura no documento

Por outro lado, o Microsoft Word formata cada campo individual com base no idioma do texto encontrado no campo (especificamente, as execuções do código do campo). Às vezes, durante a atualização do campo, esse pode ser o comportamento desejado, por exemplo, se você tiver documentos globalizados contendo conteúdo composto de vários idiomas diferentes e quiser que cada campo respeite a localidade usada no texto. Aspose.Words também oferece suporte a essa funcionalidade.

A classe Document fornece uma propriedade field_options que contém membros que podem ser usados para controlar como os campos são atualizados no documento. O exemplo abaixo mostra como especificar onde a cultura usada para formatação de data durante a atualização de campo e Mail Merge é escolhida.

Encontrando o código do campo e o resultado do campo

Um campo inserido usando DocumentBuilder.insert_field retorna um objeto Field. Esta é uma classe de fachada que fornece métodos úteis para encontrar rapidamente tais propriedades de um campo. Observe que se você estiver procurando apenas os nomes dos campos de mesclagem no documento, poderá usar o método interno MailMerge.get_field_names. O exemplo abaixo mostra como obter nomes de todos os campos de mesclagem em um documento.

Como renomear campos de mesclagem

O exemplo abaixo mostra como renomear campos de mesclagem em um documento do Word.