Come lavorare con i campi transizionali in .NET
Come lavorare con i campi transizionali in .NET
Aspose.Words FOSS per .NET rappresenta un gruppo di tipi di campo Word più vecchi — campi barcode e una manciata di campi di compatibilità pre-Open-XML — tramite classi dedicate nel Aspose.Words.Fields namespace, informalmente chiamato transitional fields qui. Questa guida mostra come trovarli, leggerli e configurarli. Ogni classe di campo transizionale deriva dal tipo base Field type, accanto al generic Field object esposto da Document.Range.Fields.
Guida passo-passo
Passo 1: Trova i campi transizionali in un documento
Enumerare Document.Range.Fields e confrontare il Type di ogni campo (un valore FieldType) con le costanti pertinenti — FieldBarcode, FieldDisplayBarcode, FieldMergeBarcode, FieldBidiOutline, FieldEQ, FieldFootnoteRef o FieldInfo — quindi convertire il generico Field nella classe corrispondente per accedere alle sue proprietà specifiche. Controllare sempre Type prima della conversione: convertire nella classe di campo sbagliata genera un InvalidCastException.
Passo 2: Configura un campo DISPLAYBARCODE o MERGEBARCODE
FieldDisplayBarcode (il campo DISPLAYBARCODE) e FieldMergeBarcode (il campo MERGEBARCODE, che implementa anche IMergeFieldSurrogate per l’unione della posta) condividono lo stesso insieme di proprietà di configurazione del codice a barre: BarcodeType, BarcodeValue, SymbolHeight, SymbolRotation, ScalingFactor, ForegroundColor, BackgroundColor, PosCodeStyle, CaseCodeStyle, ErrorCorrectionLevel, DisplayText, AddStartStopChar e FixCheckDigit. Impostali sull’istanza del campo, poi chiama Update() in modo che Result rifletta la nuova configurazione prima che il documento venga salvato.
Passo 3: Leggi i dati del campo BARCODE (Postale) legacy
FieldBarcode implementa il campo più vecchio BARCODE, che è specificamente un campo di codice a barre postale statunitense (POSTNET) piuttosto che un codice a barre generico — non condivide le proprietà BarcodeType/BarcodeValue del Passo 2. Invece espone PostalAddress (l’indirizzo codificato dal codice a barre), FacingIdentificationMark, IsUSPostalAddress e IsBookmark. Verifica Field.Type contro FieldType.FieldBarcode specificamente prima di leggere queste proprietà, poiché il casting di un campo DISPLAYBARCODE o MERGEBARCODE a FieldBarcode non esporrebbe le proprietà che ti aspetti.
Passo 4: Genera le immagini del codice a barre con un generatore personalizzato
Questa edizione FOSS contiene i dati del campo codice a barre ma non include un motore di rendering del codice a barre. BarcodeParameters è il contenitore pass-through che consolida le impostazioni di entrambe le famiglie di campi codice a barre — le proprietà DISPLAYBARCODE/MERGEBARCODE del Passo 2 e le proprietà postali del Passo 3 — in un unico oggetto passato a un renderer. Implementa IBarcodeGenerator, esponendo GetBarcodeImage(parameters) e il legacy GetOldBarcodeImage(parameters), per fornire il rendering effettivo dell’immagine; senza un’implementazione fornita, i campi codice a barre contengono solo dati di configurazione.
Passo 5: Lavora con i campi di compatibilità legacy
Altre quattro classi coprono codici di campo più vecchi ancora presenti nei file legacy .docx. FieldBidiOutline implementa il campo BIDIOUTLINE per la numerazione dell’indice da destra a sinistra e non espone proprietà oltre la superficie comune Field. FieldEQ implementa il campo equazione EQ e inoltre espone AsOfficeMath() per convertire il suo contenuto in un oggetto OfficeMath — ciò riesce solo quando il campo codifica effettivamente un’equazione. FieldFootnoteRef implementa il campo FOOTNOTEREF, che fa riferimento incrociato a un segno di nota a piè di pagina o di fine documento, e non espone proprietà oltre la superficie comune Field. FieldInfo implementa il campo INFO, leggendo o scrivendo una proprietà di riepilogo-informazione del documento tramite le sue proprietà InfoType e NewValue.
Passo 6: Aggiorna o blocca il valore di un campo transizionale
Ogni classe di campo transizionale eredita GetFieldCode() (il testo di codice sottostante del campo), Update() (ri-valuta il risultato), Unlink() (sostituisce il campo con il suo ultimo risultato calcolato come testo statico) e Remove() (elimina il campo). Chiama Update() dopo aver modificato la configurazione di qualsiasi campo affinché Result rifletta la modifica, e usa Unlink() quando il valore corrente di un campo deve essere congelato anziché rimanere ricalcolabile.
Problemi comuni e soluzioni
InvalidCastException quando si effettua il cast di un Field a una classe di campo transizionale. Il sbagliato FieldType è stato assunto. Verifica Field.Type contro la corrispondenza FieldType costante prima del casting.
A DISPLAYBARCODE/MERGEBARCODE le proprietà del campo sono mancanti dopo il casting. Il campo è stato castato a FieldBarcode invece di FieldDisplayBarcode/FieldMergeBarcode (o viceversa) — queste classi espongono diversi set di proprietà anche se tutti e tre rappresentano dati di codice a barre. Conferma Field.Type prima del casting.
I campi barcode trasportano dati ma non viene renderizzata alcuna immagine. No IBarcodeGenerator l’implementazione è stata fornita. Fornisci un generatore personalizzato che implementi GetBarcodeImage(parameters) — questa edizione non fornisce un motore di rendering barcode integrato.
FieldEQ.AsOfficeMath() restituisce risultati inattesi. Il campo non contiene un’istruzione di equazione valida. Ispeziona il campo. GetFieldCode() l’output prima di tentare la conversione.
FieldInfo’s value non è aggiornato dopo l’impostazione NewValue. Il campo non è stato aggiornato dopo la modifica. Chiama Update() sul campo dopo la modifica NewValue.
Domande frequenti
Cosa significa “transitional” per questi tipi di campo?
Non è una terminologia ufficiale di Word — raggruppa le classi di campo in questo namespace Aspose.Words.Fields di questa edizione che implementano i codici di campo più vecchi (campi barcode e campi di compatibilità pre-Open-XML) tramite le proprie classi tipizzate, anziché essere gestiti solo tramite l’oggetto generico Field.
Il FieldBarcode utilizza le stesse proprietà di FieldDisplayBarcode?
No. FieldBarcode implementa il campo legacy BARCODE (postal/POSTNET) e espone PostalAddress, FacingIdentificationMark, IsUSPostalAddress e IsBookmark. FieldDisplayBarcode e FieldMergeBarcode condividono un diverso insieme di proprietà — BarcodeType, BarcodeValue, SymbolHeight e le relative impostazioni di rendering.
Questa edizione genera immagini barcode?
No. FieldBarcode, FieldDisplayBarcode e FieldMergeBarcode contengono i dati di configurazione del barcode e espongono l’interfaccia IBarcodeGenerator, ma nessun motore di rendering barcode è incluso in questa edizione — è necessaria un’implementazione personalizzata IBarcodeGenerator per produrre un’immagine.
Posso convertire un campo EQ in un’equazione OfficeMath?
Sì, tramite FieldEQ.AsOfficeMath(), a condizione che il codice del campo codifichi effettivamente un’equazione.
Come faccio a trovare tutti i campi transizionali in un documento?
Enumera Document.Range.Fields e confronta ciascuno Field.Type con le costanti FieldType rilevanti (FieldBarcode, FieldDisplayBarcode, FieldMergeBarcode, FieldBidiOutline, FieldEQ, FieldFootnoteRef, FieldInfo).
