Trabalhando com Campos

Visão geral

Um campo do Word – DATE, IF, DATABASE, REF, e dezenas de outros – é representado em Aspose.Words FOSS para .NET pela Field classe e suas subclasses, todas no Aspose.Words.Fields namespace. Esta página cobre o mecanismo central de campos: o Field modelo de objeto em si, como os campos são coletados e atualizados, e as interfaces de callback que permitem inserir dados e comportamentos personalizados durante uma atualização de campo. Famílias específicas de campos – hiperlinks e referências cruzadas, campos de data/hora, campos de mala direta, campos de índice e de sumário – cada uma tem sua própria página de guia do desenvolvedor.


O Modelo de Objeto de Campo

Cada campo em um documento é uma instância Field composta por três nós marcadores – FieldStart, Separator e FieldEnd – expostos como as propriedades Field.Start, Field.Separator e Field.End. Field.Type identifica qual FieldType o campo representa, Field.Result e Field.DisplayResult expõem o valor calculado mais recentemente, e Field.Format contém quaisquer switches (como cadeias de formato numérico ou de data/hora) anexados ao código do campo. Field.IsLocked e Field.IsDirty relatam o estado bloqueado e desatualizado do campo. Chame Field.GetFieldCode() para ler o texto bruto do código do campo, Field.Update() para recalcular o resultado, Field.Unlink() para substituir o campo por texto estático e Field.Remove() para excluí-lo completamente.


Acessando e Atualizando Campos em um Documento

Document.Range.Fields retorna um FieldCollection – os campos contidos naquele intervalo, com Count, Remove(), RemoveAt() e Clear() para remoção em massa. Range.UpdateFields() recalcula todos os campos no intervalo, Range.UnlinkFields() converte todos os campos no intervalo em texto estático, e Range.NormalizeFieldTypes() reconcilia o código de tipo armazenado de um campo com seu código de campo real após edições manuais. DocumentBuilder.InsertField() insere um novo campo no cursor, com sobrecargas que atualizam o resultado do novo campo imediatamente ou o deixam para uma passagem Range.UpdateFields() posterior.


Opções de Atualização de Campo e Cultura

Document.FieldOptions é uma instância FieldOptions que governa como os campos de todo o documento se comportam quando atualizados: CurrentUser fornece o UserInformation usado pelos campos de identidade, DefaultDocumentAuthor gera resultados relacionados ao autor, LegacyNumberFormat e UseInvariantCultureNumberFormat controlam a formatação de números, e PreProcessCulture e FieldUpdateCultureSource (em conjunto com o callback IFieldUpdateCultureProvider) determinam qual cultura governa a formatação de datas e números durante uma atualização. TemplateName, FileName e BuiltInTemplatesPaths fornecem valores que os campos sensíveis a modelos e nomes de arquivos leem de volta.


Rastreamento e Personalização de Atualizações de Campos

Implemente IFieldUpdatingCallback (FieldUpdating e FieldUpdated) em FieldOptions para executar código imediatamente antes e depois de cada recálculo de campo — útil para auditar quais campos foram alterados em um trabalho em lote. Implemente IFieldUpdatingProgressCallback (Notify) para rastrear o progresso geral em um documento grande; ele recebe um FieldUpdatingProgressArgs com TotalFieldsCount, UpdatedFieldsCount e UpdateCompleted. Para mudar como o resultado numérico ou geral de um campo é renderizado como texto, implemente IFieldResultFormatter (Format(value, format) e FormatNumeric(value, format)) e atribua-o a FieldOptions.ResultFormatter.


Fornecendo Dados Externos aos Campos

O campo DATABASE lê suas linhas através de IFieldDatabaseProvider.GetQueryResult(), que retorna um FieldDatabaseDataTable (ColumnNames, Rows) construído a partir de instâncias FieldDatabaseDataRow (Values) — atribua sua implementação a FieldOptions.FieldDatabaseProvider. Campos de comparação, como IF, avaliam sua condição através de IComparisonExpressionEvaluator.Evaluate(), que recebe um ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) e devolve um ComparisonEvaluationResult (Result, ErrorMessage); atribua um avaliador personalizado a FieldOptions.ComparisonExpressionEvaluator para sobrescrever a lógica de comparação padrão. Campos que normalmente solicitam ao usuário entrada durante uma atualização — como ASK e FILLIN — chamam IFieldUserPromptRespondent.Respond() quando um é atribuído a FieldOptions.UserPromptRespondent, de modo que uma atualização não assistida não bloqueie aguardando entrada interativa.


Identidade de Usuário e Documento para Campos

UserInformation (Name, Initials, Address e o estático UserInformation.DefaultUser) fornece a identidade da qual os campos relacionados a autor e nome de usuário leem. Atribua uma instância a Document.FieldOptions.CurrentUser antes de atualizar campos que dependem do autor do documento ou da identidade do usuário.


Dicas e Melhores Práticas

  • Aspose.Words FOSS não recalcula campos automaticamente ao carregar ou salvar como o Word faz – chame Range.UpdateFields() (ou Field.Update() para um único campo) explicitamente após qualquer edição programática que deva ser refletida nos resultados dos campos.
  • FieldStart, Separator e FieldEnd são nós reais na árvore do documento; remova um campo através de Field.Remove() ou Field.Unlink() em vez de excluir os nós de marcador diretamente, caso contrário a estrutura do campo pode ficar inconsistente.
  • Campos cujo resultado depende do layout da página – PAGE, NUMPAGES e entradas de número de página do sumário (TOC) – avaliam para um placeholder 0, porque esta edição não inclui o motor de layout/renderização de página.
  • Registre IFieldUpdatingCallback antes de executar Range.UpdateFields() em um documento grande ou desconhecido se precisar registrar ou auditar exatamente quais campos foram alterados.
  • Defina FieldOptions.UserPromptRespondent (ou forneça valores DefaultResponse nas classes de campo individuais acionadas por prompt) antes de atualizar um documento em um pipeline não supervisionado, para que os campos ASK/FILLIN não travem aguardando entrada interativa.

Problemas comuns

ProblemaCausaCorreção
O resultado do campo está desatualizado após editar o documentoAspose.Words FOSS não atualiza automaticamente os campos ao carregar ou salvarChame Range.UpdateFields() ou Field.Update() explicitamente
PAGE, NUMPAGES ou os números de página do TOC mostram 0O layout/renderização de página não faz parte desta ediçãoComportamento esperado – use a versão comercial Aspose.Words para .NET se precisar de números de página calculados
campo DATABASE não produz linhasNenhum IFieldDatabaseProvider está atribuído a FieldOptions.FieldDatabaseProviderImplemente IFieldDatabaseProvider e atribua-o antes de chamar Range.UpdateFields()
A atualização em lote do campo parece travarUm campo orientado por prompt (ASK, FILLIN) não tem IFieldUserPromptRespondent atribuídoAtribua FieldOptions.UserPromptRespondent, ou defina DefaultResponse na instância do campo

FAQ

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.

Como reavaliar campos após editar um documento programaticamente?

Chame Range.UpdateFields() no intervalo que cobre o conteúdo editado, ou Document.Range.UpdateFields() para atualizar todos os campos no documento.

Posso converter um campo para texto simples e estático?

Sim – Field.Unlink() substitui o campo pelo seu resultado calculado mais recentemente como texto comum, removendo o código subjacente do campo.

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 e o conteúdo do resultado do campo.

Como forneço dados personalizados ao campo DATABASE?

Implemente IFieldDatabaseProvider e atribua-a a Document.FieldOptions.FieldDatabaseProvider. Sua implementação GetQueryResult() retorna um FieldDatabaseDataTable construído a partir de instâncias FieldDatabaseDataRow.


API Reference Resumo

Classe / InterfaceDescrição
FieldClasse base para um campo Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionOs campos em um intervalo, via Range.Fields; Count, Remove(), Clear()
FieldTypeEnum que identifica qual campo Word uma instância de Field representa
FieldOptionsConfiguração de atualização de campo em todo o documento, via Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated ganchos ao redor de cada atualização de campo
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsRelatório de progresso durante uma atualização em massa de campos
IFieldResultFormatterFormatação personalizada do resultado calculado de um campo
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowFonte de dados externa para o campo DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultAvaliação personalizada de expressões de campo em estilo de comparação
IFieldUserPromptRespondentFornece respostas para campos acionados por prompts em atualizações sem supervisão
IFieldUpdateCultureProvider / FieldUpdateCultureSourceSeleção de cultura durante atualizações de campo
UserInformationIdentidade do autor/usuário (Name, Initials, Address) lida pelos campos de identidade

Ver também

 Português