Aperçu des champs

Habituellement, un champ, lorsqu’il est inséré dans Microsoft Word, contient déjà une valeur à jour. Par exemple, si le champ est une formule ou un numéro de page, il contiendra une valeur calculée correcte pour la version donnée du document. Mais si vous disposez d’une application qui génère ou modifie un document avec des champs (par exemple combine deux documents ou remplit des données) alors pour que le document soit utile, tous les champs doivent idéalement être mis à jour.

Un champ est composé de:

• Les nœuds de début de champ et de séparateur sont utilisés pour englober le contenu qui constitue le code de champ (normalement sous forme de texte brut)
• Le séparateur de champ et la fin du champ englobent le résultat du champ. Celui-ci peut être composé de différents types de contenu allant des séquences de texte aux paragraphes en passant par les tableaux.
• Certains champs peuvent ne pas avoir de séparateur, ce qui signifie que tout le contenu constitue le code du champ.
• Le code de champ définit le comportement du champ et comprend l’identifiant du champ et souvent d’autres paramètres tels que le nom du champ et les commutateurs.
• Le résultat du champ contient l’évaluation la plus récente du champ. Cette valeur est stockée dans le résultat du champ et est ce qui est affiché à l’utilisateur. Certains champs peuvent ne pas avoir de résultat et n’afficheront donc rien dans le document. De même, certains champs peuvent ne pas encore être mis à jour et n’auront donc aucun résultat de champ.

Voici une vue de la façon dont un champ est stocké dans Aspose.Words en utilisant l’exemple “DocumentExplorer” qui peut être trouvé sur GitHub.

Aspose.Words est une bibliothèque de classes conçue pour le traitement côté serveur des documents Microsoft Word et prend en charge les champs des manières suivantes:

• Tous les champs d’un document sont conservés lors de l’ouverture/sauvegarde et des conversions.
• Il est possible de mettre à jour les résultats de certains des champs les plus populaires.

Champs dans Microsoft Word

Les champs des documents Microsoft Word sont complexes. Il existe plus de 50 types de champs (chacun nécessite sa propre procédure de calcul des résultats), des formules et expressions, des signets et des références, des fonctions et divers commutateurs. Les champs peuvent également être imbriqués. Normalement, lorsqu’un document est ouvert, le résultat du champ (la valeur du champ) est affiché pour tous les champs du document. Vous pouvez basculer l’affichage du résultat du champ ou des codes de champ dans Microsoft Word pour tous les champs en appuyant sur ALT+F9.

Code de champ	Résultat du champ

Insertion de champs dans Microsoft Word

Pour insérer un champ dans Microsoft Word:

1. Cliquez sur le menu Insert.
2. Cliquez sur le menu déroulant Quick Parts
3. Sélectionnez Field
4. Un écran vous permet de saisir les détails du champ. Sur le côté gauche, vous voyez une liste des champs possibles et sur le côté droit se trouve un écran pour modifier visuellement les propriétés du champ.
   
5. De plus, vous pouvez appuyer sur le bouton Field Codes qui vous permet d’écrire directement le code du champ.
   
6. Les commutateurs peuvent également être insérés à l’aide du bouton Options
   
7. Quelle que soit la méthode utilisée, remplissez les champs souhaités avec les informations appropriées, puis appuyez sur Ok.
8. Le champ est inséré dans le document à la position actuelle du curseur.
   

Mise à jour des champs dans Microsoft Word

Pour mettre à jour un seul champ dans Microsoft Word:

1. Déplacez le curseur dans le champ que vous souhaitez mettre à jour.
2. Appuyez sur F9 pour mettre à jour le champ.

Pour mettre à jour tous les champs dans Microsoft Word:

1. Appuyez sur Ctrl+A pour sélectionner tout le contenu du document.
2. Appuyez sur F9 pour mettre à jour tous les champs trouvés dans la sélection.

Basculement entre l’affichage du code de champ et le résultat du champ

Pour basculer les codes de champ d’un seul champ dans Microsoft Word:

1. Déplacez le curseur dans le champ souhaité.
2. Appuyez sur MAJ+F9 pour basculer le code de champ uniquement pour ce champ.

Pour basculer les codes de champ de tous les champs dans Microsoft Word:

1. Appuyez sur ALT+F9

Conversion de champs en texte statique dans Microsoft Word

Pour convertir un champ dynamique en texte statique dans Microsoft Word:

1. Déplacez le curseur dans le champ que vous souhaitez convertir.
2. Appuyez sur Ctrl+Maj+F9 pour convertir les champs en texte statique.

Supprimer un champ dans Microsoft Word

Pour supprimer un champ dans Microsoft Word:

1. Sélectionnez tout le contenu composant le champ. Si les codes de champ sont affichés, les accolades d’ouverture et de fin doivent également être sélectionnées.
2. Appuyez sur Delete pour supprimer tout le champ.

Champs dans Aspose.Words

Lorsqu’un document est chargé dans Aspose.Words, les champs du document sont chargés dans Aspose.Words Document Object Model sous la forme d’un ensemble de composants distincts (nœuds). Un seul champ est chargé sous la forme d’une collection de nœuds FieldStart, FieldSeparator et FieldEnd avec le contenu situé entre ces nœuds. Si un champ n’a pas de résultat de champ, il n’y aura pas de nœud FieldSeparator. Tous ces nœuds se trouvent toujours en ligne (en tant qu’enfants de Paragraph ou SmartTag.

Le contenu qui constitue le code du champ est stocké sous forme de nœuds Run entre le FieldStart et le FieldSeparator. Le résultat du champ est stocké entre les nœuds FieldSeparator et FieldEnd et peut être constitué de différents types de contenu. Normalement, le résultat du champ contient uniquement du texte composé de nœuds Run, mais il est possible que le nœud FieldEnd soit situé dans un paragraphe complètement différent, ce qui rend le résultat du champ également composé de nœuds de niveau bloc tels que les nœuds Table et Paragraph.

Dans Aspose.Words, chacun des nœuds FieldXXX dérive de FieldChar. Cette classe fournit une propriété pour vérifier le type de champ représenté par le nœud spécifié via la propriété FieldChar.field_type. Par exemple, FieldType.FIELD_MERGE_FIELD représente un champ de fusion dans le document.

Certains champs particuliers existent dans un document Word qui ne sont pas importés dans Aspose.Words en tant que collection de nœuds FieldXXX. Par exemple, le champ LINK et le champ INCLUDEPICTURE sont importés dans Aspose.Words en tant qu’objet Shape. Cet objet fournit des propriétés permettant de travailler avec les données d’image normalement stockées dans ces champs.

Les champs de formulaire sont également importés dans Aspose.Words en tant que classe spéciale. La classe FormField représente un champ de formulaire dans un document Word et fournit des méthodes supplémentaires spécifiques à un champ de formulaire.

Champs pris en charge lors de la mise à jour

Le calcul des champs suivants est pris en charge dans la version actuelle de Aspose.Words:

• = (champ de formule)
• ADDRESSBLOCK
• AUTHOR
• COMPARE
• CREATEDATE
• DATE
• DOCPROPERTY
• DOCVARIABLE
• GREETINGLINE
• IF
• INCLUDETEXT
• MERGEFIELD
• MERGEREC
• MERGESEQ
• NEXT
• NEXTIF
• NUMPAGES
• PAGE
• PAGEREF
• REF
• SECTION
• SECTIONPAGES
• SEQ
• SET
• STYLEREF
• TIME
• TITLE
• TOA
• TOC (y compris TOT et TOF)
• TC

Analyse sophistiquée

Aspose.Words suit la façon dont Microsoft Word traite les champs et, par conséquent, il gère correctement:

• Champs imbriqués : IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
• L’argument champ peut être le résultat d’un champ imbriqué.
• Les champs peuvent être imbriqués dans un code de champ ainsi que dans le résultat du champ.
• Espaces/pas d’espaces, guillemets/pas de guillemets, caractères d’échappement dans les champs etc.: MERGEFIELD \f"Text after""Field \n\ame with \" and \\\ and \\\*"\bTextBefor\e
• Champs qui s’étendent sur plusieurs paragraphes.

Champs de formule

Aspose.Words fournit une implémentation très sérieuse du moteur de formule et prend en charge les éléments suivants:

• Opérateurs arithmétiques et logiques: =(54+4*(6-77)-(5))+(-6-5)/4/5
• Les fonctions: =ABS(-01.4)+2.645/(5.6^3.5)+776457 \\\# "#,##0"
• Références aux signets: =IF(C>4, 5,ABS(A)*.76) +3.85
• Commutateurs de formatage des nombres: =00000000 \\\# "$#,##0.00;($#,##0.00)"

Les fonctions suivantes dans les expressions sont prises en charge: ABS, AND, AVERAGE, COUNT, DEFINED, FALSE, IF, INT, MAX, MIN, MOD, NOT, OR, PRODUCT, ROUND, SIGN, SUM, TRUE.

Champs IF et COMPARE

Quelques-unes des expressions IF que Aspose.Words peut facilement calculer devraient vous donner une idée de la puissance de cette fonctionnalité:

• 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

Champs DATE et TIME

Aspose.Words prend en charge tous les commutateurs de formatage de date et d’heure disponibles dans Microsoft Word, en voici quelques exemples:

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

Champs Mail Merge

Aspose.Words n’impose aucune limite à la complexité des champs mail merge dans vos documents et prend en charge les champs IF et de formule imbriqués et peut même calculer le nom du champ de fusion à l’aide d’une formule.

Quelques exemples de champs mail merge pris en charge par Aspose.Words:

• Commutateurs de champ Mail merge: MERGEFIELD FirstName \\\\\\\\* FirstCap \b "Mr. "
• Champs de fusion imbriqués dans une formule: IF { MERGEFIELDValue1 } >= {MERGEFIELD Value2 } True False
• Calculez le nom du champ de fusion au moment de l’exécution: MERGEFIELD { IF{MERGEFIELDValue1 } >= {MERGEFIELD Value2 } FirstName"LastName" }
• Déplacement conditionnel vers l’enregistrement suivant dans la source de données: NEXTIF { MERGEFIELDValue1 } <= { =IF(-2.45 >= 6*{MERGEFIELD Value2 }, 2, -.45) }

Commutateurs de format

Un champ dans un document peut avoir des commutateurs de formatage qui spécifient comment la valeur résultante doit être formatée. Aspose.Words prend en charge les commutateurs de format suivants:

• @ - formatage de la date et de l’heure
• \# - formatage des nombres
• \\\\* Casquettes
• \\\\* PremierCap
• \\\\* Inférieur
• \\\\* Supérieur
• \\\\* CHARFORMAT – formate le résultat en fonction du premier caractère du code de champ.
• \\\\* MERGEFORMAT – formate le résultat en fonction de la façon dont l’ancien résultat est formaté.

Date et formatage des nombres dans les champs

Lorsque Aspose.Words calcule un résultat de champ, il doit souvent analyser une chaîne en une valeur numérique ou de date et également la reformater en chaîne. Par défaut, Aspose.Words utilise la culture de thread actuelle pour effectuer l’analyse et le formatage lors du calcul des valeurs de champ lors de la mise à jour du champ. et mail merge. Il existe également des options fournies sous la forme de la classe FieldOptions qui permettent un contrôle plus approfondi sur la culture utilisée lors de la mise à jour des champs.

• Par défaut, la propriété FieldOptions.field_update_culture_source est définie sur FieldUpdateCultureSource.CURRENT_THREAD, ce qui formate les champs en utilisant la culture de thread actuelle.
• Cette propriété peut être définie sur FieldUpdateCultureSource.FIELD_CODE afin que la langue définie à partir du code de champ du champ soit utilisée pour le formatage.

Formatage à l’aide de la culture du fil de discussion actuel

Pour contrôler la culture utilisée lors du calcul du champ, utilisez simplement la méthode locale.setlocale pour définir la culture de votre choix avant d’appeler le calcul du champ. L’exemple ci-dessous montre comment modifier la culture utilisée dans le formatage des champs lors de la mise à jour.

L’utilisation de la culture actuelle pour formater les champs permet à un système de contrôler facilement et de manière cohérente la façon dont tous les champs du document sont formatés lors de la mise à jour des champs.

Formatage à l’aide de la culture du document

D’autre part, Microsoft Word formate chaque champ individuel en fonction de la langue du texte trouvé dans le champ (en particulier, les extraits du code du champ). Parfois, lors de la mise à jour des champs, cela peut être le comportement souhaité, par exemple si vous avez des documents globalisés contenant du contenu composé de nombreuses langues différentes et que vous souhaitez que chaque champ respecte les paramètres régionaux utilisés dans le texte. Aspose.Words prend également en charge cette fonctionnalité.

La classe Document fournit une propriété field_options qui contient des membres qui peuvent être utilisés pour contrôler la manière dont les champs sont mis à jour dans le document. L’exemple ci-dessous montre comment spécifier où est choisie la culture utilisée pour le formatage de la date lors de la mise à jour des champs et mail merge.

Recherche du code de champ et du résultat du champ

Un champ inséré à l’aide de DocumentBuilder.insert_field renvoie un objet Field. Il s’agit d’une classe de façade qui fournit des méthodes utiles pour trouver rapidement de telles propriétés d’un champ. Notez que si vous recherchez uniquement les noms des champs de fusion dans le document, vous pouvez utiliser la méthode MailMerge.get_field_names intégrée. L’exemple ci-dessous montre comment obtenir les noms de tous les champs de fusion dans un document.

Comment renommer les champs de fusion

L’exemple ci-dessous montre comment renommer les champs de fusion dans un document Word.