Construindo Campos com FieldBuilder

Construindo Campos com FieldBuilder

Este guia mostra como construir um campo Word do zero em Aspose.Words FOSS para .NET usando FieldBuilder and FieldArgumentBuilder, em vez de trabalhar com um campo que já existe em um documento. Para ler, atualizar ou remover campos existentes, veja o Trabalhando com Campos guia.

Criando um Campo com FieldBuilder

FieldBuilder constrói um campo a partir de tokens de código de campo — argumentos e switches. Construa um com new FieldBuilder(fieldType), passando o FieldType do campo que você deseja construir. Adicione argumentos com o método sobrecarregado AddArgument(argument), que aceita um string, int, double, um FieldBuilder aninhado ou um FieldArgumentBuilder. Adicione switches com os métodos sobrecarregados AddSwitch(switchName), AddSwitch(switchName, switchArgument) (string) ou AddSwitch(switchName, switchArgument) (int/double).

Inserindo o Campo Construído

Depois que um FieldBuilder tem seus argumentos e switches, chame BuildAndInsert(refNode) para inseri-lo no documento — uma sobrecarga aceita um nó Inline e insere o campo antes dele, e outra aceita um Paragraph e insere o campo ao final desse parágrafo.

Compondo Argumentos Complexos com FieldArgumentBuilder

FieldArgumentBuilder constrói um argumento de campo complexo composto por campos, nós e texto simples, para casos em que um único argumento precisa de mais do que uma string simples. Crie um com new FieldArgumentBuilder(), então chame AddText(text) para adicionar texto simples, AddNode(node) para adicionar um nó Inline, ou AddField(fieldBuilder) para aninhar outro campo (construído com seu próprio FieldBuilder) dentro do argumento. Passe o FieldArgumentBuilder concluído para FieldBuilder.AddArgument(argument) para usá-lo como um dos argumentos do campo externo.

Dicas e Melhores Práticas

• Use FieldBuilder ao construir um tipo de campo que não é suportado por uma das classes de campo dedicadas (como FieldDate ou FieldSymbol), ou ao gerar códigos de campo programaticamente a partir de dados em vez de criá-los manualmente.
• Aninhe um campo filho dentro do argumento de um campo externo com FieldBuilder.AddArgument(FieldBuilder) para um caso simples, ou construa um argumento misto de texto, nós e campos aninhados com FieldArgumentBuilder quando o argumento for mais que um único campo.
• Escolha a sobrecarga BuildAndInsert(refNode) que corresponde ao local onde você deseja que o campo seja inserido — antes de um nó Inline específico, ou ao final de um Paragraph.
• Após BuildAndInsert, trate o resultado como qualquer outro campo na árvore — por exemplo, chame Update() nele se o tipo de campo exigir uma recalculação explícita.

Problemas Comuns

FAQ

Quando devo usar FieldBuilder em vez de inserir um código de campo pré-formado?

Use FieldBuilder quando precisar de controle explícito sobre os argumentos e opções de um campo ao construí-los programaticamente, em vez de inserir uma string de código de campo pré-formada.

Como adiciono mais de um argumento a um campo?

Chame AddArgument uma vez por argumento — ele está sobrecarregado para string, int, double, um FieldBuilder aninhado e FieldArgumentBuilder.

Posso criar um campo cujo argumento contenha uma mistura de texto e outro campo?

Sim — use FieldArgumentBuilder, chamando AddText, AddNode e AddField conforme necessário, e então passe-o para FieldBuilder.AddArgument.

Como realmente insiro o campo construído no documento?

Chame BuildAndInsert(refNode), passando um nó Inline (insere antes dele) ou um Paragraph (insere ao final dele).

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation