Lavorare con i campi

Panoramica

Un campo Word – DATE, IF, DATABASE, REF, e decine di altri – è rappresentato in Aspose.Words FOSS per .NET da Field classe e le sue sottoclassi, tutte nel Aspose.Words.Fields namespace. Questa pagina copre il motore di campo principale: il Field modello oggetto stesso, come i campi vengono raccolti e aggiornati, e le interfacce di callback che ti consentono di inserire dati e comportamenti personalizzati durante un aggiornamento del campo. Le famiglie di campi specifiche – collegamenti ipertestuali e riferimenti incrociati, campi data/ora, campi di stampa unione, campi indice e indice dei contenuti – hanno ciascuna la propria pagina guida per sviluppatori dedicata.


Il modello oggetto del campo

Ogni campo in un documento è un’istanza Field composta da tre nodi marcatore – FieldStart, Separator e FieldEnd – esposti come le proprietà Field.Start, Field.Separator e Field.End. Field.Type identifica quale FieldType il campo rappresenta, Field.Result e Field.DisplayResult espongono l’ultimo valore calcolato, e Field.Format contiene eventuali switch (come stringhe di formato numerico o data/ora) associati al codice del campo. Field.IsLocked e Field.IsDirty segnalano lo stato bloccato e obsoleto del campo. Chiama Field.GetFieldCode() per leggere il testo grezzo del codice del campo, Field.Update() per ricalcolare il risultato, Field.Unlink() per sostituire il campo con testo statico, e Field.Remove() per eliminarlo completamente.


Accedere e aggiornare i campi in un documento

Document.Range.Fields restituisce un FieldCollection – i campi contenuti in quell’intervallo, con Count, Remove(), RemoveAt() e Clear() per la rimozione in blocco. Range.UpdateFields() ricalcola ogni campo nell’intervallo, Range.UnlinkFields() converte ogni campo nell’intervallo in testo statico, e Range.NormalizeFieldTypes() riconcilia il codice tipo memorizzato di un campo con il suo codice campo effettivo dopo modifiche manuali. DocumentBuilder.InsertField() inserisce un nuovo campo al cursore, con overload che o aggiornano immediatamente il risultato del nuovo campo o lo lasciano per un successivo passaggio di Range.UpdateFields().


Opzioni di aggiornamento del campo e cultura

Document.FieldOptions è un’istanza FieldOptions che governa il modo in cui i campi dell’intero documento si comportano quando vengono aggiornati: CurrentUser fornisce il UserInformation usato dai campi di identità, DefaultDocumentAuthor genera i risultati relativi all’autore, LegacyNumberFormat e UseInvariantCultureNumberFormat controllano la formattazione dei numeri, e PreProcessCulture e FieldUpdateCultureSource (in coppia con il callback IFieldUpdateCultureProvider) determinano quale cultura governa la formattazione di data e numero durante un aggiornamento. TemplateName, FileName e BuiltInTemplatesPaths forniscono i valori che i campi consapevoli di template e nome file leggono indietro.


Tracciamento e personalizzazione degli aggiornamenti dei campi

Implementa IFieldUpdatingCallback (FieldUpdating e FieldUpdated) su FieldOptions per eseguire il codice immediatamente prima e dopo ogni ricalcolo del campo — utile per auditare quali campi sono cambiati in un lavoro batch. Implementa IFieldUpdatingProgressCallback (Notify) per tenere traccia del progresso complessivo su un documento di grandi dimensioni; riceve un FieldUpdatingProgressArgs con TotalFieldsCount, UpdatedFieldsCount e UpdateCompleted. Per modificare il modo in cui il risultato numerico o generale di un campo viene renderizzato come testo, implementa IFieldResultFormatter (Format(value, format) e FormatNumeric(value, format)) e assegnalo a FieldOptions.ResultFormatter.


Fornire dati esterni ai campi

Il campo DATABASE legge le sue righe tramite IFieldDatabaseProvider.GetQueryResult(), che restituisce un FieldDatabaseDataTable (ColumnNames, Rows) costruito da istanze FieldDatabaseDataRow (Values) — assegna la tua implementazione a FieldOptions.FieldDatabaseProvider. I campi di confronto come IF valutano la loro condizione tramite IComparisonExpressionEvaluator.Evaluate(), che riceve un ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) e restituisce un ComparisonEvaluationResult (Result, ErrorMessage); assegna un valutatore personalizzato a FieldOptions.ComparisonExpressionEvaluator per sovrascrivere la logica di confronto predefinita. I campi che normalmente chiedono all’utente un input durante un aggiornamento — come ASK e FILLIN — chiamano IFieldUserPromptRespondent.Respond() quando uno è assegnato a FieldOptions.UserPromptRespondent, così un aggiornamento non assistito non si blocca in attesa di input interattivo.


Identità utente e documento per i campi

UserInformation (Name, Initials, Address e il statico UserInformation.DefaultUser) fornisce l’identità da cui i campi relativi a nome autore e nome utente leggono. Assegna un’istanza a Document.FieldOptions.CurrentUser prima di aggiornare i campi che dipendono dall’autore del documento o dall’identità dell’utente.


Suggerimenti e migliori pratiche

  • Aspose.Words FOSS non ricalcola i campi automaticamente al caricamento o al salvataggio come fa Word – chiama Range.UpdateFields() (o Field.Update() per un singolo campo) esplicitamente dopo qualsiasi modifica programmatica che dovrebbe essere riflessa nei risultati del campo.
  • FieldStart, Separator e FieldEnd sono nodi reali nell’albero del documento; rimuovi un campo tramite Field.Remove() o Field.Unlink() invece di eliminare direttamente i nodi marcatore, altrimenti la struttura del campo potrebbe risultare incoerente.
  • I campi il cui risultato dipende dal layout della pagina – PAGE, NUMPAGES e le voci di numero di pagina dell’indice – valutano a un segnaposto 0, perché questa edizione non include il motore di layout/rendering della pagina.
  • Registra IFieldUpdatingCallback prima di eseguire Range.UpdateFields() su un documento grande o sconosciuto se hai bisogno di registrare o verificare esattamente quali campi sono cambiati.
  • Imposta FieldOptions.UserPromptRespondent (o fornisci i valori DefaultResponse sulle singole classi di campo guidate da prompt) prima di aggiornare un documento in una pipeline non assistita, così i campi ASK/FILLIN non si bloccheranno in attesa di input interattivo.

Problemi comuni

ProblemaCausaCorrezione
Il risultato del campo è obsoleto dopo aver modificato il documentoAspose.Words FOSS non aggiorna automaticamente i campi al caricamento o al salvataggioChiama Range.UpdateFields() o Field.Update() esplicitamente
PAGE, NUMPAGES o i numeri di pagina del TOC mostrano 0Il layout/rendering della pagina non fa parte di questa edizioneComportamento previsto – usa la versione commerciale Aspose.Words per .NET se ti servono numeri di pagina calcolati
Il campo DATABASE non produce righeNessun IFieldDatabaseProvider è assegnato a FieldOptions.FieldDatabaseProviderImplementa IFieldDatabaseProvider e assegnalo prima di chiamare Range.UpdateFields()
L’aggiornamento batch del campo sembra bloccarsiUn campo guidato da prompt (ASK, FILLIN) non ha IFieldUserPromptRespondent assegnatoAssegna FieldOptions.UserPromptRespondent, oppure imposta DefaultResponse sull’istanza del campo

FAQ

Il Aspose.Words FOSS valuta tutti i tipi di campo di Word?

Il modello oggetto Field rappresenta ogni valore FieldType e ne aggiorna la maggior parte, ma i campi il cui risultato dipende dal layout della pagina – come PAGE e NUMPAGES – valutano a un segnaposto 0 perché questa edizione non include il motore di layout/rendering.

Come faccio a rivalutare i campi dopo aver modificato un documento programmaticamente?

Chiama Range.UpdateFields() sull’intervallo che copre il contenuto modificato, oppure Document.Range.UpdateFields() per aggiornare tutti i campi nel documento.

Posso convertire un campo in testo semplice e statico?

Sì – Field.Unlink() sostituisce il campo con il suo risultato calcolato più recentemente come testo ordinario, rimuovendo il codice del campo sottostante.

Come rimuovo completamente un campo, incluso il suo risultato?

Chiama Field.Remove(). Elimina i nodi FieldStart, Separator e FieldEnd insieme al codice e al contenuto del risultato del campo.

Come fornisco dati personalizzati al campo DATABASE?

Implementa IFieldDatabaseProvider e assegnalo a Document.FieldOptions.FieldDatabaseProvider. La tua implementazione GetQueryResult() restituisce un FieldDatabaseDataTable costruito da istanze FieldDatabaseDataRow.


API Reference Riepilogo

Classe / InterfacciaDescrizione
FieldClasse base per un campo Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionI campi in un intervallo, tramite Range.Fields; Count, Remove(), Clear()
FieldTypeEnum che identifica quale campo Word rappresenta un’istanza di Field
FieldOptionsConfigurazione dell’aggiornamento dei campi a livello di documento, tramite Document.FieldOptions
IFieldUpdatingCallbackHook FieldUpdating / FieldUpdated intorno a ogni aggiornamento del campo
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsSegnalazione di avanzamento durante un aggiornamento massivo dei campi
IFieldResultFormatterFormattazione personalizzata del risultato calcolato di un campo
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowFonte dati esterna per il campo DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultValutazione personalizzata delle espressioni di campo in stile confronto
IFieldUserPromptRespondentFornisce risposte per i campi guidati da prompt negli aggiornamenti non supervisionati
IFieldUpdateCultureProvider / FieldUpdateCultureSourceSelezione della cultura durante gli aggiornamenti dei campi
UserInformationIdentità dell’autore/utente (Name, Initials, Address) letta dai campi di identità

Vedi anche

 Italiano