Panoramica dei campi

Aspose.Words è una libreria di classi progettata per l’elaborazione lato server di documenti Microsoft Word e supporta i campi nei seguenti modi:

  • tutti i campi in un documento vengono conservati durante l’apertura/salvataggio e le conversioni
  • è possibile aggiornare i risultati della maggior parte dei campi

In questo articolo impareremo di più sulla struttura dei campi, sui campi supportati in Aspose.Words e sui dettagli su come lavorare con tali campi.

Struttura del campo

Un campo è costituito da:

  • I nodi inizio campo e separatore vengono utilizzati per racchiudere il contenuto che costituisce il codice del campo (normalmente come testo semplice).
  • Il separatore di campo e la fine del campo racchiudono il risultato del campo. Questo può essere costituito da vari tipi di contenuto che vanno dalle sequenze di testo ai paragrafi alle tabelle.
  • Alcuni campi potrebbero non avere un separatore, il che significa che l’intero contenuto costituisce il codice del campo.
  • Il codice di campo definisce il comportamento del campo ed è composto dall’identificatore del campo e spesso da altri parametri come il nome del campo e le opzioni.
  • Il risultato del campo contiene la valutazione più recente del campo. Questo valore viene memorizzato nel campo risultato ed è ciò che viene visualizzato all’utente. Alcuni campi potrebbero non avere alcun risultato di campo quindi non verrà visualizzato nulla nel documento. Allo stesso modo, alcuni campi potrebbero non essere ancora aggiornati, pertanto non avranno risultati di campo.

fields-aspose-words

Il contenuto che costituisce il codice di campo viene archiviato come nodi Run tra FieldStart e FieldSeparator. Il risultato del campo viene archiviato tra i nodi FieldSeparator e FieldEnd e può essere costituito da vari tipi di contenuto. Normalmente il risultato del campo contiene solo testo composto da nodi Run, tuttavia è possibile che il nodo FieldEnd si trovi in un paragrafo completamente diverso, rendendo così il risultato del campo composto anche da nodi Livelli logici dei nodi in un documento come Table e Paragraph.

Ecco una visualizzazione di come un campo viene archiviato in Aspose.Words utilizzando l’esempio “DocumentExplorer” che può essere trovato su Github.

document-explorer-aspose-words

Campi nel Aspose.Words Document Object Model (DOM)

Quando un documento viene caricato in Aspose.Words, i campi del documento vengono caricati in Aspose.Words Document Object Model (DOM) come un insieme di componenti separati (nodi). Un singolo campo viene caricato come raccolta di nodi FieldStart, FieldSeparator e FieldEnd insieme al contenuto tra questi nodi. Se un campo non ha un risultato di campo, non ci sarà alcun nodo FieldSeparator. Tutti questi nodi si trovano sempre in linea (come figli di Paragraph o SmartTag.

In Aspose.Words ciascuno dei nodi FieldXXX deriva da FieldChar. Questa classe fornisce una proprietà per verificare il tipo di campo rappresentato dal nodo specificato tramite la proprietà FieldType. Ad esempio FieldType.FieldMergeField rappresenta un campo di unione nel documento.

Campi supportati

Il calcolo dei seguenti campi è supportato nella versione attuale di Aspose.Words:

  • = (formula)
  • ADDRESSBLOCK
  • ASK
  • AUTHOR
  • AUTONUM
  • AUTONUMLGL
  • AUTONUMOUT
  • AUTOTEXT
  • BARCODE
  • COMMENTS
  • COMPARE
  • CREATEDATE
  • DATABASE
  • DATE
  • DISPLAYBARCODE
  • DOCPROPERTY
  • DOCVARIABLE
  • EDITTIME
  • EQ
  • FILENAME
  • FILESIZE
  • FILLIN
  • FORMCHECKBOX
  • FORMDROPDOWN
  • FORMTEXT
  • GLOSSARY
  • GOTOBUTTON
  • GREETINGLINE
  • HYPERLINK
  • IF
  • IMPORT
  • INCLUDE
  • INCLUDEPICTURE
  • INCLUDETEXT
  • INDEX
  • INFO
  • KEYWORDS
  • LASTSAVEDBY
  • LISTNUM
  • MACROBUTTON
  • MERGEBARCODE
  • MERGEFIELD
  • MERGEREC
  • MERGESEQ
  • NEXT
  • NEXTIF
  • NOTEREF
  • NUMCHARS
  • NUMPAGES
  • NUMWORDS
  • PAGE
  • PAGEREF
  • PRINTDATE
  • QUOTE
  • REF
  • REVNUM
  • SAVEDATE
  • SECTION
  • SECTIONPAGES
  • SEQ
  • SET
  • SHAPE
  • SKIPIF
  • STYLEREF
  • SUBJECT
  • SYMBOL
  • TEMPLATE
  • TIME
  • TITLE
  • TOA
  • TOC
  • USERADDRESS
  • USERINITIALS
  • USERNAME

Analisi sofisticata del campo

Aspose.Words segue il modo in cui Microsoft Word elabora i campi e di conseguenza gestisce correttamente:

  • campi nidificati: IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
  • L’argomento del campo può essere il risultato di un campo nidificato
  • I campi possono essere nidificati all’interno di un codice di campo così come nel risultato del campo
  • spazi/senza spazi, virgolette/senza virgolette, caratteri di escape nei campi ecc.: MERGEFIELD \f"Text after""Field \n\ame with \" and \\\ and \\\*"\bTextBefor\e
  • campi che si estendono su più paragrafi

Campi formula

Aspose.Words fornisce un’implementazione molto seria del motore delle formule e supporta quanto segue:

  • operatori aritmetici e logici: =(54+4*(6-77)-(5))+(-6-5)/4/5
  • funzioni: =ABS(-01.4)+2.645/(5.6^3.5)+776457 \\\# "#,##0"
  • riferimenti ai segnalibri: =IF(C>4, 5,ABS(A)*.76) +3.85
  • interruttori di formattazione dei numeri: =00000000 \\\# "$#,##0.00;($#,##0.00)"

Sono supportate le seguenti funzioni nelle espressioni: ABS, AND, AVERAGE, COUNT, DEFINED, FALSE, IF, INT, MAX, MIN, MOD, NOT, OR, PRODUCT, ROUND, SIGN, SUM, TRUE.

Campi IF e COMPARE

Solo alcune delle espressioni IF che Aspose.Words può facilmente calcolare dovrebbero darti un’idea di quanto sia potente questa funzionalità:

  • IF 3 > 5.7^4+MAX(4,3) True False
  • IF "abcd" > "abc" True False
  • IF "?ab*" = "1abdsg" True False
  • IF 4 = "2*2" True False
  • COMPARE 3+5/34 < 4.6/3/2

Campi DATE e TIME

Aspose.Words supporta tutte le opzioni di formattazione di data e ora disponibili in Microsoft Word, alcuni esempi sono:

  • DATE @ "d-MMM-yy"
  • DATE @ "d/MM/yyyy h:mm am/pm

Campi Mail Merge

Aspose.Words non impone limiti alla complessità dei campi Mail Merge nei tuoi documenti e supporta campi formula e IF nidificati e può persino calcolare il nome del campo di unione utilizzando una formula.

Alcuni esempi di campi Mail Merge supportati da Aspose.Words:

  • Interruttori di campo Mail merge: MERGEFIELD FirstName \\\\\\\\* FirstCap \b "Mr. "
  • campi di unione nidificati in una formula: IF { MERGEFIELDValue1 } >= {MERGEFIELD Value2 } True False
  • calcola il nome del campo di unione in fase di esecuzione: MERGEFIELD { IF{MERGEFIELDValue1 } >= {MERGEFIELD Value2 } FirstName"LastName" }
  • passaggio condizionale al record successivo nell’origine dati: NEXTIF { MERGEFIELDValue1 } <= { =IF(-2.45 >= 6*{MERGEFIELD Value2 }, 2, -.45) }

Interruttori di formato

Un campo in un documento può avere opzioni di formattazione che specificano come deve essere formattato il valore risultante. Aspose.Words supporta le seguenti opzioni di formato:

  • \@ – formattazione di data e ora
  • \# – formattazione del numero
  • \* Tappi
  • \* PrimoCap
  • \* Inferiore
  • \* Superiore
  • \* CHARFORMAT – formatta il risultato in base al primo carattere del codice di campo
  • \* MERGEFORMAT – formatta il risultato in base a come è formattato il vecchio risultato

Date e formattazione dei numeri nei campi

Quando Aspose.Words calcola il risultato di un campo, spesso è necessario analizzare una stringa in un numero o un valore di data e anche formattarla nuovamente in una stringa. Per impostazione predefinita, Aspose.Words utilizza la cultura del thread corrente per eseguire l’analisi e la formattazione durante il calcolo dei valori del campo durante l’aggiornamento del campo e mail merge. Sono inoltre disponibili opzioni sotto forma di classe FieldOptions che consentono un ulteriore controllo su quale cultura viene utilizzata durante l’aggiornamento del campo.

  • per impostazione predefinita la proprietà FieldUpdateCultureSource è impostata su CurrentThread che formatta i campi utilizzando la cultura del thread corrente
  • questa proprietà può essere impostata su FieldCode in modo che per la formattazione venga utilizzata la lingua impostata dal codice del campo

Formattazione utilizzando la cultura del thread corrente

Per controllare la lingua utilizzata durante il calcolo del campo, imposta semplicemente la proprietà Thread.CurrentThread.CurrentCulture su una lingua a tua scelta prima di richiamare il calcolo del campo.

L’esempio di codice seguente mostra come modificare la lingua utilizzata nei campi di formattazione durante l’aggiornamento:

L’utilizzo della lingua corrente per formattare i campi consente a un sistema di controllare in modo semplice e coerente il modo in cui tutti i campi nel documento vengono formattati durante l’aggiornamento dei campi.

Formattazione utilizzando la lingua nel documento

D’altra parte, Microsoft Word formatta ogni singolo campo in base alla lingua del testo trovato nel campo (in particolare, le parti dal codice di campo). A volte durante l’aggiornamento del campo questo potrebbe essere il comportamento desiderato, ad esempio se si hanno documenti globalizzati con contenuti composti da molte lingue diverse e si desidera che ciascun campo rispetti la locale utilizzata dal testo. Aspose.Words supporta anche questa funzionalità.

La classe Document fornisce una proprietà FieldOptions che contiene membri che possono essere utilizzati per controllare il modo in cui i campi vengono aggiornati all’interno del documento.

L’esempio di codice seguente mostra come specificare da dove vengono scelte le impostazioni cultura utilizzate per la formattazione della data durante l’aggiornamento del campo e mail merge:

Inserisci campi in C#