Travailler avec les champs

Vue d’ensemble

Un champ Word – DATE, IF, DATABASE, REF, et des dizaines d’autres – est représenté dans Aspose.Words FOSS for .NET par le Field classe et ses sous-classes, toutes dans le Aspose.Words.Fields espace de noms. Cette page couvre le moteur de champ principal : le Field modèle d’objet lui-même, la façon dont les champs sont collectés et mis à jour, et les interfaces de rappel qui vous permettent d’intégrer des données et un comportement personnalisés lors d’une mise à jour de champ. Les familles de champs spécifiques – hyperliens et renvois, champs date/heure, champs de fusion de courrier, champs d’index et de table des matières – ont chacune leur propre page de guide du développeur.


Le modèle d’objet de champ

Chaque champ d’un document est une instance Field composée de trois nœuds marqueurs — FieldStart, Separator et FieldEnd — exposés comme les propriétés Field.Start, Field.Separator et Field.End. Field.Type identifie quel FieldType le champ représente, Field.Result et Field.DisplayResult exposent la valeur calculée en dernier, et Field.Format contient les commutateurs (tels que des chaînes de format numérique ou date-heure) attachés au code du champ. Field.IsLocked et Field.IsDirty indiquent l’état verrouillé et obsolète du champ. Appelez Field.GetFieldCode() pour lire le texte brut du code du champ, Field.Update() pour recalculer le résultat, Field.Unlink() pour remplacer le champ par du texte statique, et Field.Remove() pour le supprimer entièrement.


Accéder aux champs et les mettre à jour dans un document

Document.Range.Fields renvoie un FieldCollection — les champs contenus dans cette plage, avec Count, Remove(), RemoveAt() et Clear() pour une suppression en masse. Range.UpdateFields() recalcule chaque champ de la plage, Range.UnlinkFields() convertit chaque champ de la plage en texte statique, et Range.NormalizeFieldTypes() réconcilie le code de type stocké d’un champ avec son code de champ réel après des modifications manuelles. DocumentBuilder.InsertField() insère un nouveau champ au curseur, avec des surcharges qui soit mettent à jour immédiatement le résultat du nouveau champ, soit le laissent pour un passage Range.UpdateFields() ultérieur.


Options de mise à jour des champs et culture

Document.FieldOptions est une instance FieldOptions qui régit la façon dont les champs de l’ensemble du document se comportent lors d’une mise à jour: CurrentUser fournit le UserInformation utilisé par les champs d’identité, DefaultDocumentAuthor alimente les résultats liés à l’auteur, LegacyNumberFormat et UseInvariantCultureNumberFormat contrôlent le formatage des nombres, et PreProcessCulture et FieldUpdateCultureSource (associés au rappel IFieldUpdateCultureProvider) déterminent la culture qui gouverne le formatage des dates et des nombres pendant une mise à jour. TemplateName, FileName et BuiltInTemplatesPaths fournissent des valeurs que les champs sensibles aux modèles et aux noms de fichiers lisent.


Suivi et personnalisation des mises à jour de champs

Implémentez IFieldUpdatingCallback (FieldUpdating et FieldUpdated) sur FieldOptions pour exécuter du code immédiatement avant et après chaque recalcul de champ — utile pour auditer quels champs ont changé lors d’un traitement par lots. Implémentez IFieldUpdatingProgressCallback (Notify) pour suivre la progression globale d’un grand document; il reçoit un FieldUpdatingProgressArgs avec TotalFieldsCount, UpdatedFieldsCount et UpdateCompleted. Pour modifier la façon dont le résultat numérique ou général d’un champ est rendu en texte, implémentez IFieldResultFormatter (Format(value, format) et FormatNumeric(value, format)) et assignez-le à FieldOptions.ResultFormatter.


Fourniture de données externes aux champs

Le champ DATABASE lit ses lignes via IFieldDatabaseProvider.GetQueryResult(), qui renvoie un FieldDatabaseDataTable (ColumnNames, Rows) construit à partir d’instances FieldDatabaseDataRow (Values) — affectez votre implémentation à FieldOptions.FieldDatabaseProvider. Les champs de comparaison tels que IF évaluent leur condition via IComparisonExpressionEvaluator.Evaluate(), qui reçoit un ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) et renvoie un ComparisonEvaluationResult (Result, ErrorMessage); assignez un évaluateur personnalisé à FieldOptions.ComparisonExpressionEvaluator pour remplacer la logique de comparaison par défaut. Les champs qui demandent normalement à l’utilisateur une saisie lors d’une mise à jour — comme ASK et FILLIN — appellent IFieldUserPromptRespondent.Respond() lorsqu’un tel champ est assigné à FieldOptions.UserPromptRespondent, de sorte qu’une mise à jour non assistée ne bloque pas en attendant une entrée interactive.


Identité de l’utilisateur et du document pour les champs

UserInformation (Name, Initials, Address et le UserInformation.DefaultUser statique) fournit l’identité que les champs liés au nom de l’auteur et de l’utilisateur lisent. Assignez une instance à Document.FieldOptions.CurrentUser avant de mettre à jour les champs qui dépendent de l’auteur du document ou de l’identité de l’utilisateur.


Conseils et meilleures pratiques

  • Aspose.Words FOSS ne recalcule pas les champs automatiquement au chargement ou à l’enregistrement comme le fait Word — appelez Range.UpdateFields() (ou Field.Update() pour un champ unique) explicitement après toute modification programmatique qui doit se refléter dans les résultats des champs.
  • FieldStart, Separator et FieldEnd sont de vrais nœuds dans l’arbre du document; supprimez un champ via Field.Remove() ou Field.Unlink() plutôt qu’en supprimant directement les nœuds marqueurs, sinon la structure du champ peut devenir incohérente.
  • Les champs dont le résultat dépend de la mise en page — PAGE, NUMPAGES et les entrées de numéros de page de la TOC — évaluent à un espace réservé 0, car cette édition ne comprend pas le moteur de mise en page/rendu.
  • Enregistrez IFieldUpdatingCallback avant d’exécuter Range.UpdateFields() sur un document volumineux ou inconnu si vous devez consigner ou auditer exactement quels champs ont changé.
  • Définissez FieldOptions.UserPromptRespondent (ou fournissez les valeurs DefaultResponse sur les classes de champs pilotées par invite individuelles) avant de mettre à jour un document dans une chaîne automatisée, afin que les champs ASK/FILLIN ne se bloquent pas en attendant une entrée interactive.

Problèmes courants

ProblèmeCauseCorrection
Le résultat du champ n’est plus à jour après la modification du documentAspose.Words FOSS ne met pas à jour automatiquement les champs au chargement ou à l’enregistrementAppelez Range.UpdateFields() ou Field.Update() explicitement
PAGE, NUMPAGES, ou les numéros de page du TOC affichent 0La mise en page/rendu de la page ne fait pas partie de cette éditionComportement attendu — utilisez la version commerciale Aspose.Words pour .NET si vous avez besoin de numéros de page calculés
Le champ DATABASE ne produit aucune ligneAucun IFieldDatabaseProvider n’est attribué à FieldOptions.FieldDatabaseProviderImplémentez IFieldDatabaseProvider et assignez-le avant d’appeler Range.UpdateFields()
La mise à jour par lot du champ semble se bloquerUn champ piloté par invite (ASK, FILLIN) n’a aucun IFieldUserPromptRespondent assignéAttribuez FieldOptions.UserPromptRespondent, ou définissez DefaultResponse sur l’instance du champ

FAQ

Est-ce que Aspose.Words FOSS évalue tous les types de champs Word?

Le modèle d’objet Field représente chaque valeur FieldType et met à jour la plupart d’entre elles, mais les champs dont le résultat dépend de la mise en page — tels que PAGE et NUMPAGES — évaluent à un 0 de remplacement parce que cette édition n’inclut pas le moteur de mise en page/rendu.

Comment réévaluer les champs après avoir modifié un document par programmation?

Appelez Range.UpdateFields() sur la plage qui couvre le contenu modifié, ou Document.Range.UpdateFields() pour mettre à jour chaque champ du document.

Puis-je convertir un champ en texte simple et statique?

Oui — Field.Unlink() remplace le champ par son résultat calculé en dernier comme texte ordinaire, en supprimant le code de champ sous-jacent.

Comment supprimer complètement un champ, y compris son résultat?

Appelez Field.Remove(). Il supprime les nœuds FieldStart, Separator et FieldEnd ainsi que le code et le contenu du résultat du champ.

Comment fournir des données personnalisées au champ DATABASE?

Implémentez IFieldDatabaseProvider et assignez-le à Document.FieldOptions.FieldDatabaseProvider. Votre implémentation GetQueryResult() renvoie un FieldDatabaseDataTable construit à partir d’instances FieldDatabaseDataRow.


Résumé API Reference

Classe / InterfaceDescription
FieldClasse de base pour un champ Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionLes champs dans une plage, via Range.Fields; Count, Remove(), Clear()
FieldTypeEnum identifiant quel champ Word une instance Field représente
FieldOptionsConfiguration de mise à jour de champ à l’échelle du document, via Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hooks autour de chaque mise à jour de champ
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsRapport de progression lors d’une mise à jour massive de champs
IFieldResultFormatterMise en forme personnalisée du résultat calculé d’un champ
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowSource de données externe pour le champ DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultÉvaluation personnalisée des expressions de champ de type comparaison
IFieldUserPromptRespondentFournit des réponses pour les champs déclenchés par invite lors des mises à jour non supervisées
IFieldUpdateCultureProvider / FieldUpdateCultureSourceSélection de la culture lors des mises à jour de champ
UserInformationIdentité de l’auteur/utilisateur (Name, Initials, Address) lu par les champs d’identité

Voir aussi

 Français