Como trabalhar com campos em .NET
Este guia mostra como trabalhar com campos do Word — DATE, IF, REF, DATABASE e dezenas de outros — em Aspose.Words FOSS para .NET: inserir um campo e ler seu resultado, atualizar campos após uma edição programática, configurar o comportamento de atualização, rastrear atualizações com um callback e converter ou remover um campo. Aspose.Words FOSS para .NET está disponível via NuGet ou compilando a partir do código-fonte.
Guia passo a passo
Etapa 1: Obter a biblioteca
Clone o repositório e compile Aspose.Words.sln na configuração Release, então adicione uma referência de projeto a Aspose.Words.csproj do seu próprio projeto .NET, conforme descrito no guia de Instalação. Adicione using Aspose.Words; and using Aspose.Words.Fields; no início de qualquer arquivo que trabalhe com campos.
Etapa 2: Inserir um campo e ler seu resultado
DocumentBuilder.InsertField() insere um novo campo no cursor, com sobrecargas que ou atualizam o resultado do campo imediatamente ou o deixam para uma passagem de atualização posterior. Cada campo é uma instância Field composta por três nós marcadores — FieldStart, Separator e FieldEnd, expostos como Field.Start / Field.Separator / Field.End. Field.Type identifica qual FieldType ele representa, Field.Result e Field.DisplayResult armazenam o valor calculado mais recentemente, Field.Format contém quaisquer switches de formato anexados ao código, e Field.GetFieldCode() retorna o texto bruto do código do campo.
Etapa 3: Atualizar Campos Após uma Edição Programática
Aspose.Words FOSS não recalcula campos quando o documento é carregado ou salvo. Após uma edição que deveria mudar o resultado de um campo, chame Range.UpdateFields() para recalcular todos os campos naquele intervalo — use Document.Range.UpdateFields() para todo o documento — ou Field.Update() para um único campo. Range.UnlinkFields() converte todos os campos no intervalo para texto estático em uma única chamada, e Range.NormalizeFieldTypes() reconcilia o código de tipo armazenado de um campo com seu código de campo real após uma edição manual.
Etapa 4: Configurar o Comportamento de Atualização de Campos com FieldOptions
Document.FieldOptions (uma instância de FieldOptions) controla como os campos de todo o documento se comportam durante uma atualização: CurrentUser (uma instância de UserInformation — Name, Initials, Address) fornece a identidade da qual os campos relacionados a autor e nome de usuário leem, DefaultDocumentAuthor gera resultados relacionados ao autor, e LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource controlam a formatação de números e datas. Para pipelines não supervisionados, atribua FieldOptions.UserPromptRespondent (um IFieldUserPromptRespondent) para que campos acionados por prompt, como ASK e FILLIN, não bloqueiem aguardando entrada interativa, e atribua um IFieldDatabaseProvider personalizado a FieldOptions.FieldDatabaseProvider para fornecer as linhas do campo DATABASE a partir da sua própria fonte de dados em vez de uma conexão de banco de dados real.
Etapa 5: Rastrear Atualizações de Campos com um Callback
Implemente IFieldUpdatingCallback (FieldUpdating e FieldUpdated) e atribua-o a FieldOptions para executar código imediatamente antes e depois de cada recalculação de campo — útil para auditar exatamente quais campos foram alterados em um trabalho em lote. Para relatar o progresso em um documento grande, implemente IFieldUpdatingProgressCallback (Notify), que recebe um FieldUpdatingProgressArgs expondo TotalFieldsCount, UpdatedFieldsCount e UpdateCompleted.
Etapa 6: Converter ou Remover um Campo
Field.Unlink() substitui o campo pelo seu último resultado calculado como texto estático comum, descartando o código subjacente do campo — use-o quando quiser que o valor fique incorporado permanentemente no documento. Field.Remove() exclui os nós FieldStart, Separator e FieldEnd juntamente com o código e o resultado do campo, removendo o campo completamente. Prefira esses dois métodos em vez de excluir diretamente os nós de marcação, já que remover manualmente apenas parte da estrutura de um campo pode deixar a árvore do documento inconsistente.
Problemas Comuns e Soluções
O resultado exibido de um campo fica desatualizado após editar o documento. Aspose.Words FOSS não atualiza automaticamente os campos ao carregar ou salvar. Chame Range.UpdateFields() or Field.Update() explicitamente após a edição.
PAGE, NUMPAGES, ou um número de página do índice sempre é exibido 0. Layout/paginação de página não faz parte desta edição, portanto campos cujo resultado depende da paginação são avaliados como um placeholder 0. Este é o comportamento esperado nesta edição.
Uma atualização em lote de campo parece travar. Um campo acionado por prompt (ASK, FILLIN) não tem IFieldUserPromptRespondent atribuído. Atribuir FieldOptions.UserPromptRespondent, ou definir DefaultResponse na instância de campo individual.
O DATABASE campo não produz linhas. Nenhum IFieldDatabaseProvider está atribuído a FieldOptions.FieldDatabaseProvider. Implemente a interface e atribua-a antes de chamar Range.UpdateFields().
Perguntas Frequentes
O Aspose.Words FOSS avalia todos os tipos de campo do Word?
O modelo de objeto Field representa cada valor FieldType e atualiza a maioria deles, mas campos cujo resultado depende do layout da página — como PAGE e NUMPAGES — avaliam para um placeholder 0 porque esta edição não inclui o motor de layout/rendering engine.
Como reavaliar campos após uma edição programática?
Chame Range.UpdateFields() no intervalo que cobre o conteúdo editado, ou Document.Range.UpdateFields() para todo o documento.
Posso converter um campo em texto simples e estático?
Sim — Field.Unlink() substitui o campo pelo seu último resultado calculado como texto comum.
Como remover um campo completamente, incluindo seu resultado?
Chame Field.Remove(). Ele exclui os nós FieldStart, Separator e FieldEnd juntamente com o código do campo e o conteúdo do resultado.
Como forneço dados personalizados ao campo DATABASE?
Implemente IFieldDatabaseProvider e atribua-o a Document.FieldOptions.FieldDatabaseProvider. Sua implementação GetQueryResult() retorna um FieldDatabaseDataTable construído a partir de instâncias FieldDatabaseDataRow.
