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()(oField.Update()per un singolo campo) esplicitamente dopo qualsiasi modifica programmatica che dovrebbe essere riflessa nei risultati del campo. FieldStart,SeparatoreFieldEndsono nodi reali nell’albero del documento; rimuovi un campo tramiteField.Remove()oField.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,NUMPAGESe le voci di numero di pagina dell’indice – valutano a un segnaposto0, perché questa edizione non include il motore di layout/rendering della pagina. - Registra
IFieldUpdatingCallbackprima di eseguireRange.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 valoriDefaultResponsesulle singole classi di campo guidate da prompt) prima di aggiornare un documento in una pipeline non assistita, così i campiASK/FILLINnon si bloccheranno in attesa di input interattivo.
Problemi comuni
| Problema | Causa | Correzione |
|---|---|---|
| Il risultato del campo è obsoleto dopo aver modificato il documento | Aspose.Words FOSS non aggiorna automaticamente i campi al caricamento o al salvataggio | Chiama Range.UpdateFields() o Field.Update() esplicitamente |
PAGE, NUMPAGES o i numeri di pagina del TOC mostrano 0 | Il layout/rendering della pagina non fa parte di questa edizione | Comportamento previsto – usa la versione commerciale Aspose.Words per .NET se ti servono numeri di pagina calcolati |
Il campo DATABASE non produce righe | Nessun IFieldDatabaseProvider è assegnato a FieldOptions.FieldDatabaseProvider | Implementa IFieldDatabaseProvider e assegnalo prima di chiamare Range.UpdateFields() |
| L’aggiornamento batch del campo sembra bloccarsi | Un campo guidato da prompt (ASK, FILLIN) non ha IFieldUserPromptRespondent assegnato | Assegna 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 / Interfaccia | Descrizione |
|---|---|
Field | Classe base per un campo Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | I campi in un intervallo, tramite Range.Fields; Count, Remove(), Clear() |
FieldType | Enum che identifica quale campo Word rappresenta un’istanza di Field |
FieldOptions | Configurazione dell’aggiornamento dei campi a livello di documento, tramite Document.FieldOptions |
IFieldUpdatingCallback | Hook FieldUpdating / FieldUpdated intorno a ogni aggiornamento del campo |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Segnalazione di avanzamento durante un aggiornamento massivo dei campi |
IFieldResultFormatter | Formattazione personalizzata del risultato calcolato di un campo |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Fonte dati esterna per il campo DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Valutazione personalizzata delle espressioni di campo in stile confronto |
IFieldUserPromptRespondent | Fornisce risposte per i campi guidati da prompt negli aggiornamenti non supervisionati |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Selezione della cultura durante gli aggiornamenti dei campi |
UserInformation | Identità dell’autore/utente (Name, Initials, Address) letta dai campi di identità |