Comment travailler avec les champs dans .NET

Étape 1: obtenir la bibliothèque

Clonez le dépôt et compilez Aspose.Words.sln en configuration Release, puis ajoutez une référence de projet à Aspose.Words.csproj de votre propre projet .NET, comme décrit dans le Guide d’installation. Ajoutez using Aspose.Words; and using Aspose.Words.Fields; au début de tout fichier qui travaille avec des champs.

Étape 2: insérer un champ et lire son résultat

DocumentBuilder.InsertField() insère un nouveau champ au curseur, avec des surcharges qui mettent soit à jour le résultat du champ immédiatement, soit le laissent pour un passage de mise à jour ultérieur. Chaque champ est une instance Field composée de trois nœuds marqueurs — FieldStart, Separator et FieldEnd, exposés comme Field.Start / Field.Separator / Field.End. Field.Type identifie quel FieldType il représente, Field.Result et Field.DisplayResult contiennent la dernière valeur calculée, Field.Format contient les commutateurs de format attachés au code, et Field.GetFieldCode() renvoie le texte brut du code du champ.

Étape 3: Mettre à jour les champs après une modification programmatique

Aspose.Words FOSS ne recalcule pas les champs lors du chargement ou de l’enregistrement du document. Après une modification qui devrait changer le résultat d’un champ, appelez Range.UpdateFields() pour recalculer chaque champ dans cette plage — utilisez Document.Range.UpdateFields() pour l’ensemble du document — ou Field.Update() pour un seul champ. Range.UnlinkFields() convertit chaque champ de la plage en texte statique en un seul appel, et Range.NormalizeFieldTypes() réconcilie le code de type stocké d’un champ avec son code de champ réel après une modification manuelle.

Étape 4: Configurer le comportement de mise à jour des champs avec FieldOptions

Document.FieldOptions (une instance FieldOptions) contrôle la façon dont les champs de l’ensemble du document se comportent pendant une mise à jour: CurrentUser (une instance UserInformation — Name, Initials, Address) fournit l’identité dont lisent les champs liés aux noms d’auteur et d’utilisateur, DefaultDocumentAuthor alimente les résultats liés à l’auteur, et LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource contrôlent le formatage des nombres et des dates. Pour les pipelines non supervisés, affectez FieldOptions.UserPromptRespondent (un IFieldUserPromptRespondent) afin que les champs guidés par des invites comme ASK et FILLIN ne bloquent pas en attendant une saisie interactive, et assignez un IFieldDatabaseProvider personnalisé à FieldOptions.FieldDatabaseProvider pour fournir les lignes du champ DATABASE depuis votre propre source de données au lieu d’une vraie connexion à une base de données.

Étape 5: Suivre les mises à jour des champs avec un rappel

Implémentez IFieldUpdatingCallback (FieldUpdating et FieldUpdated) et affectez-le à FieldOptions pour exécuter du code immédiatement avant et après chaque recalcul de champ — utile pour auditer exactement quels champs ont changé dans un travail par lots. Pour le reporting de progression dans un document volumineux, implémentez IFieldUpdatingProgressCallback (Notify), qui reçoit un FieldUpdatingProgressArgs exposant TotalFieldsCount, UpdatedFieldsCount et UpdateCompleted.

Étape 6: Convertir ou supprimer un champ

Field.Unlink() remplace le champ par son dernier résultat calculé sous forme de texte statique ordinaire, en éliminant le code de champ sous-jacent — utilisez-le lorsque vous souhaitez que la valeur soit incorporée de façon permanente dans le document. Field.Remove() supprime les nœuds FieldStart, Separator et FieldEnd ainsi que le code et le résultat du champ, supprimant le champ entièrement. Privilégiez ces deux méthodes plutôt que de supprimer directement les nœuds marqueurs, car enlever manuellement seulement une partie de la structure d’un champ peut rendre l’arbre du document incohérent.