Come lavorare con i campi in .NET
Questa guida mostra come lavorare con i campi di Word — DATE, IF, REF, DATABASE, e decine di altri — in Aspose.Words FOSS per .NET: inserire un campo e leggere il suo risultato, aggiornare i campi dopo una modifica programmatica, configurare il comportamento di aggiornamento, tenere traccia degli aggiornamenti con una callback e convertire o rimuovere un campo. Aspose.Words FOSS per .NET è disponibile tramite NuGet o compilando dal sorgente.
Guida passo-passo
Passo 1: Ottieni la libreria
Clona il repository e compila Aspose.Words.sln in configurazione Release, quindi aggiungi un riferimento al progetto Aspose.Words.csproj dal tuo progetto .NET, come descritto nella Guida all’installazione. Aggiungi using Aspose.Words; and using Aspose.Words.Fields; all’inizio di qualsiasi file che lavora con i campi.
Passo 2: Inserisci un campo e leggi il suo risultato
DocumentBuilder.InsertField() inserisce un nuovo campo al cursore, con overload che aggiornano immediatamente il risultato del campo oppure lo lasciano per un passaggio di aggiornamento successivo. Ogni campo è un’istanza Field composta da tre nodi marcatore — FieldStart, Separator e FieldEnd, esposti come Field.Start / Field.Separator / Field.End. Field.Type identifica quale FieldType rappresenta, Field.Result e Field.DisplayResult contengono il valore calcolato più recente, Field.Format contiene eventuali switch di formato collegati al codice, e Field.GetFieldCode() restituisce il testo grezzo del codice del campo.
Passo 3: Aggiorna i campi dopo una modifica programmatica
Aspose.Words FOSS non ricalcola i campi quando il documento viene caricato o salvato. Dopo una modifica che dovrebbe cambiare il risultato di un campo, chiama Range.UpdateFields() per ricalcolare tutti i campi in quell’intervallo — usa Document.Range.UpdateFields() per l’intero documento — o Field.Update() per un singolo campo. Range.UnlinkFields() converte tutti i campi nell’intervallo in testo statico in una sola chiamata, e Range.NormalizeFieldTypes() riconcilia il codice tipo memorizzato di un campo con il suo codice campo effettivo dopo una modifica manuale.
Passo 4: Configura il comportamento di aggiornamento dei campi con FieldOptions
Document.FieldOptions (un’istanza di FieldOptions) regola il comportamento dei campi dell’intero documento durante un aggiornamento: CurrentUser (un’istanza di UserInformation — Name, Initials, Address) fornisce l’identità da cui i campi relativi a autore e nome utente leggono, DefaultDocumentAuthor genera i risultati relativi all’autore, e LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource controllano la formattazione di numeri e date. Per pipeline non supervisionate, assegna FieldOptions.UserPromptRespondent (un IFieldUserPromptRespondent) in modo che i campi guidati da prompt come ASK e FILLIN non blocchino in attesa di input interattivo, e assegna un IFieldDatabaseProvider personalizzato a FieldOptions.FieldDatabaseProvider per fornire le righe del campo DATABASE dalla tua fonte dati invece di una connessione a un database reale.
Passo 5: Traccia gli aggiornamenti dei campi con un callback
Implementa IFieldUpdatingCallback (FieldUpdating e FieldUpdated) e assegnalo a FieldOptions per eseguire il codice immediatamente prima e dopo ogni ricalcolo di campo — utile per verificare esattamente quali campi sono cambiati in un lavoro batch. Per la segnalazione di avanzamento su un documento grande, implementa IFieldUpdatingProgressCallback (Notify), che riceve un FieldUpdatingProgressArgs che espone TotalFieldsCount, UpdatedFieldsCount e UpdateCompleted.
Passo 6: Converti o rimuovi un campo
Field.Unlink() sostituisce il campo con il suo risultato ultimo calcolato come normale testo statico, scartando il codice del campo sottostante — usalo quando vuoi che il valore sia incorporato permanentemente nel documento. Field.Remove() elimina i nodi FieldStart, Separator e FieldEnd insieme al codice e al risultato del campo, rimuovendo il campo completamente. Preferisci questi due metodi rispetto all’eliminazione diretta dei nodi marcatore, poiché rimuovere manualmente solo una parte della struttura di un campo può lasciare l’albero del documento incoerente.
Problemi comuni e soluzioni
Il risultato visualizzato di un campo è obsoleto dopo aver modificato il documento. Aspose.Words FOSS non aggiorna automaticamente i campi al caricamento o al salvataggio. Chiama Range.UpdateFields() or Field.Update() esplicitamente dopo la modifica.
PAGE, NUMPAGES, o un numero di pagina dell’indice viene sempre mostrato 0. Il layout/presentazione della pagina non fa parte di questa edizione, quindi i campi il cui risultato dipende dalla paginazione vengono valutati come segnaposto 0. Questo è un comportamento previsto in questa edizione.
Un aggiornamento batch di campo sembra bloccarsi. Un campo guidato da prompt (ASK, FILLIN) non ha IFieldUserPromptRespondent assegnato. Assegna FieldOptions.UserPromptRespondent, o impostare DefaultResponse sull’istanza del campo individuale.
Il DATABASE il campo non produce righe. No IFieldDatabaseProvider è assegnato a FieldOptions.FieldDatabaseProvider. Implementa l’interfaccia e assegnala prima di chiamare Range.UpdateFields().
Domande frequenti
Il Aspose.Words FOSS valuta ogni tipo di campo Word?
Il modello oggetto Field rappresenta ogni valore FieldType e aggiorna la maggior parte di essi, 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 posso rivalutare i campi dopo una modifica programmatica?
Chiama Range.UpdateFields() sull’intervallo che copre il contenuto modificato, oppure Document.Range.UpdateFields() per l’intero documento.
Posso convertire un campo in testo semplice e statico?
Sì — Field.Unlink() sostituisce il campo con il suo risultato calcolato per ultimo come testo ordinario.
Come rimuovo completamente un campo, incluso il suo risultato?
Chiama Field.Remove(). Elimina i nodi FieldStart, Separator e FieldEnd insieme al codice del campo e al contenuto del risultato.
Come fornisco dati personalizzati al campo DATABASE?
Implementa IFieldDatabaseProvider e assegnalo a Document.FieldOptions.FieldDatabaseProvider. La sua implementazione GetQueryResult() restituisce un FieldDatabaseDataTable costruito da istanze FieldDatabaseDataRow.
