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()(ouField.Update()pour un champ unique) explicitement après toute modification programmatique qui doit se refléter dans les résultats des champs. FieldStart,SeparatoretFieldEndsont de vrais nœuds dans l’arbre du document; supprimez un champ viaField.Remove()ouField.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,NUMPAGESet 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
IFieldUpdatingCallbackavant d’exécuterRange.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 valeursDefaultResponsesur les classes de champs pilotées par invite individuelles) avant de mettre à jour un document dans une chaîne automatisée, afin que les champsASK/FILLINne se bloquent pas en attendant une entrée interactive.
Problèmes courants
| Problème | Cause | Correction |
|---|---|---|
| Le résultat du champ n’est plus à jour après la modification du document | Aspose.Words FOSS ne met pas à jour automatiquement les champs au chargement ou à l’enregistrement | Appelez Range.UpdateFields() ou Field.Update() explicitement |
PAGE, NUMPAGES, ou les numéros de page du TOC affichent 0 | La mise en page/rendu de la page ne fait pas partie de cette édition | Comportement 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 ligne | Aucun IFieldDatabaseProvider n’est attribué à FieldOptions.FieldDatabaseProvider | Implémentez IFieldDatabaseProvider et assignez-le avant d’appeler Range.UpdateFields() |
| La mise à jour par lot du champ semble se bloquer | Un 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 / Interface | Description |
|---|---|
Field | Classe de base pour un champ Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Les champs dans une plage, via Range.Fields; Count, Remove(), Clear() |
FieldType | Enum identifiant quel champ Word une instance Field représente |
FieldOptions | Configuration de mise à jour de champ à l’échelle du document, via Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hooks autour de chaque mise à jour de champ |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Rapport de progression lors d’une mise à jour massive de champs |
IFieldResultFormatter | Mise en forme personnalisée du résultat calculé d’un champ |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Source de données externe pour le champ DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Évaluation personnalisée des expressions de champ de type comparaison |
IFieldUserPromptRespondent | Fournit des réponses pour les champs déclenchés par invite lors des mises à jour non supervisées |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Sélection de la culture lors des mises à jour de champ |
UserInformation | Identité de l’auteur/utilisateur (Name, Initials, Address) lu par les champs d’identité |