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()(ouField.Update()para um único campo) explicitamente após qualquer edição programática que deva ser refletida nos resultados dos campos. FieldStart,SeparatoreFieldEndsão nós reais na árvore do documento; remova um campo através deField.Remove()ouField.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,NUMPAGESe entradas de número de página do sumário (TOC) – avaliam para um placeholder0, porque esta edição não inclui o motor de layout/renderização de página. - Registre
IFieldUpdatingCallbackantes de executarRange.UpdateFields()em um documento grande ou desconhecido se precisar registrar ou auditar exatamente quais campos foram alterados. - Defina
FieldOptions.UserPromptRespondent(ou forneça valoresDefaultResponsenas classes de campo individuais acionadas por prompt) antes de atualizar um documento em um pipeline não supervisionado, para que os camposASK/FILLINnão travem aguardando entrada interativa.
Problemas comuns
| Problema | Causa | Correção |
|---|---|---|
| O resultado do campo está desatualizado após editar o documento | Aspose.Words FOSS não atualiza automaticamente os campos ao carregar ou salvar | Chame Range.UpdateFields() ou Field.Update() explicitamente |
PAGE, NUMPAGES ou os números de página do TOC mostram 0 | O layout/renderização de página não faz parte desta edição | Comportamento esperado – use a versão comercial Aspose.Words para .NET se precisar de números de página calculados |
campo DATABASE não produz linhas | Nenhum IFieldDatabaseProvider está atribuído a FieldOptions.FieldDatabaseProvider | Implemente IFieldDatabaseProvider e atribua-o antes de chamar Range.UpdateFields() |
| A atualização em lote do campo parece travar | Um campo orientado por prompt (ASK, FILLIN) não tem IFieldUserPromptRespondent atribuído | Atribua 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 / Interface | Descrição |
|---|---|
Field | Classe base para um campo Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Os campos em um intervalo, via Range.Fields; Count, Remove(), Clear() |
FieldType | Enum que identifica qual campo Word uma instância de Field representa |
FieldOptions | Configuração de atualização de campo em todo o documento, via Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated ganchos ao redor de cada atualização de campo |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Relatório de progresso durante uma atualização em massa de campos |
IFieldResultFormatter | Formatação personalizada do resultado calculado de um campo |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Fonte de dados externa para o campo DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Avaliação personalizada de expressões de campo em estilo de comparação |
IFieldUserPromptRespondent | Fornece respostas para campos acionados por prompts em atualizações sem supervisão |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Seleção de cultura durante atualizações de campo |
UserInformation | Identidade do autor/usuário (Name, Initials, Address) lida pelos campos de identidade |