Comment travailler avec les liens et références Word dans .NET
Ce guide montre comment insérer des hyperliens, des renvois croisés vers des signets, des champs à valeur sollicitée et des champs de citation dans Aspose.Words FOSS pour .NET, en utilisant FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, et les autres liens et références Field sous-classes dans le Aspose.Words.Fields espace de noms. Il couvre l’insertion d’un hyperlien simple, la création de signets et leur renvoi croisé, la sollicitation de valeurs lors d’une mise à jour de champ, et la citation de sources bibliographiques.
Guide étape par étape
Étape 1: Installer le package
Aspose.Words FOSS for .NET ne publie pas encore de package NuGet — compilez la bibliothèque à partir des sources à la place. Clonez https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, puis construisez Aspose.Words.sln en configuration Release avec le SDK .NET et référencez l’assembly Aspose.Words résultant depuis votre projet. La bibliothèque cible .NET Standard 2.0, elle s’exécute donc sur le Framework .NET 4.6.2+ et .NET 6/8/10.
Étape 2: Importer les classes requises
Ajoutez une directive using Aspose.Words; pour Document et DocumentBuilder, ainsi qu’une directive using Aspose.Words.Fields; pour FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography, et les autres classes de champs couvertes par ce guide.
Étape 3: Insérer un hyperlien
Pour un hyperlien simple, appelez DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) — transmettez isBookmark: false pour une cible URL ou true pour créer un lien vers un signet dans le même document. Passez à la construction d’un FieldHyperlink directement lorsque des propriétés que le raccourci n’expose pas sont nécessaires: Address et SubAddress contiennent l’URL cible ou l’emplacement dans le document, ScreenTip définit l’infobulle au survol, OpenInNewWindow et IsImageMap sont des indicateurs d’affichage, et Target nomme un cadre de navigateur.
Étape 4: Créer un signet à référencer
Appelez DocumentBuilder.StartBookmark(bookmarkName) avant le contenu que le signet doit couvrir, et DocumentBuilder.EndBookmark(bookmarkName) après, en utilisant le même nom pour les deux appels. DocumentBuilder.MoveToBookmark(bookmarkName) déplace le curseur vers un signet déjà existant — pratique pour naviguer vers un emplacement avant d’insérer un champ de renvoi croisé à proximité.
Étape 5: Insérer une référence croisée vers ce signet
FieldRef (le champ REF), FieldPageRef (PAGEREF) et FieldNoteRef (NOTEREF) résolvent chacun le contenu d’un signet nommé via leur propriété BookmarkName. Définissez InsertHyperlink pour rendre la référence cliquable, et InsertRelativePosition pour indiquer une position relative («au-dessus» / «au-dessous») au lieu du texte référencé lui-même. FieldRef prend également en charge les options de numérotation de paragraphes — InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator — et IncludeNoteOrComment. FieldStyleRef (STYLEREF) résout le paragraphe le plus proche formaté avec un StyleName donné au lieu d’un signet, avec SearchFromBottom pour rechercher en arrière à partir de la position du champ. FieldSet (SET) définit une valeur de texte signet — BookmarkName et BookmarkText — qu’un champ REF ailleurs peut résoudre.
Étape 6: Demander une valeur lors d’une mise à jour
FieldAsk (ASK) et FieldFillIn (FILLIN) demande une valeur à la personne qui met à jour le champ : définir PromptText au texte affiché à l’utilisateur, DefaultResponse pour une valeur de secours, et PromptOnceOnMailMerge pour limiter les sollicitations répétées lors d’une fusion de courrier. FieldAsk stocke également sa réponse à BookmarkName afin que d’autres champs puissent s’y référer. Pour les mises à jour de champs automatisées, fournissez les réponses par programme plutôt que d’inviter interactivement ; consultez le guide des champs pour l’interface de rappel qui fait cela.
Étape 7: Référencer du contenu externe ou lié
FieldDde (DDE) et FieldDdeAuto (DDEAUTO) créent un lien vers du contenu dans une autre application via ProgId, SourceFullName et SourceItem, avec InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode et InsertAsBitmap sélectionnant la représentation insérée, et AutoUpdate / IsLinked contrôlant le comportement de rafraîchissement. FieldLink (LINK) est l’équivalent du lien OLE, ajoutant FormatUpdateType. FieldImport (IMPORT) et FieldIncludePicture (INCLUDEPICTURE) intègrent un graphique externe via SourceFullName et GraphicFilter. FieldInclude (INCLUDE) et FieldIncludeText (INCLUDETEXT) intègrent du contenu de document externe, avec BookmarkName pour délimiter la plage incluse et LockFields pour empêcher son rafraîchissement; FieldIncludeText prend également en charge les sources XML via Encoding, MimeType, NamespaceMappings, XPath et XslTransformation.
Étape 8: Référencer les blocs de construction et les entrées du glossaire
FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) et FieldGlossary (GLOSSARY) font tous référence à une entrée de bloc de construction nommée via EntryName; FieldAutoTextList ajoute ListStyle et ScreenTip pour sa présentation de type liste.
Étape 9: Insérer des champs de citation et de bibliographie
FieldCitation (CITATION) et FieldBibliography (BIBLIOGRAPHY) rendre le contenu provenant des données de bibliographie du document. Définir FieldCitation.SourceTag (ou l’alternative AnotherSourceTag) pour identifier quelle source il cite, et utiliser Prefix, Suffix, PageNumber, VolumeNumber, et le Suppress* drapeaux (SuppressAuthor, SuppressTitle, SuppressYear) pour contrôler comment la citation est formatée. FieldBibliography.SourceTag, FilterLanguageId, et FormatLanguageId contrôlent quelles sources apparaissent dans la bibliographie rendue et dans quelle langue. Ces champs ne s’affichent correctement qu’une fois la correspondance Source les enregistrements existent – voir le guide de la bibliographie pour les créer.
Problèmes courants et solutions
Le champ REF, PAGEREF ou NOTEREF affiche un résultat d’erreur Le BookmarkName la cible n’existe pas dans le document. Créez le signet avec DocumentBuilder.StartBookmark() / EndBookmark() avant de mettre à jour le champ.
Le champ ASK ou FILLIN bloque une mise à jour non assistée Aucun rappel n’est assigné pour fournir une réponse de manière programmatique. Assignez le rappel de mise à jour du champ décrit dans le guide des champs, ou définissez DefaultResponse sur le champ afin qu’il ait une valeur de secours.
Le champ CITATION ou BIBLIOGRAPHY s’affiche vide Le SourceTag ne correspond à aucun Source dans les données de bibliographie du document. Ajoutez le correspondant Source – voir le guide de bibliographie.
Le champ DDE, DDEAUTO ou LINK ne se rafraîchit pas Ces champs font référence à une source OLE externe qui n’est pas disponible en dehors du contexte Windows/OLE d’origine. Traitez le résultat stocké du champ comme la dernière valeur connue dans cette situation.
Un hyperlien inséré avec InsertHyperlink manque une propriété dont j’ai besoin DocumentBuilder.InsertHyperlink() est un raccourci qui n’expose pas chaque FieldHyperlink propriété. Construire ou récupérer le FieldHyperlink directement pour définir des propriétés telles que ScreenTip or IsImageMap.
Foire aux questions
Quelle est la différence entre FieldRef et FieldStyleRef?
FieldRef renvoie au contenu d’un signet nommé (BookmarkName); FieldStyleRef renvoie, quant à lui, au paragraphe le plus proche formaté avec un StyleName donné, indépendamment des signets.
Comment insérer un hyperlien simple sans créer un Field à la main?
Appelez DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
Ces classes de champ de lien et de référence sont-elles dans un espace de noms séparé des autres champs?
Non — FieldHyperlink, FieldRef, FieldCitation et le reste des classes présentées ici sont des sous-classes ordinaires de Field dans l’espace de noms Aspose.Words.Fields, le même espace de noms utilisé pour tout autre type de champ.
Comment les champs de citation se rapportent-ils au modèle de données de la bibliographie?
FieldCitation and FieldBibliography rendre le contenu en le recherchant SourceTag contre le Source enregistrements décrits dans le guide de la bibliographie – ces classes de champ gèrent le rendu, tandis que le Source and Contributor classes contiennent les données sous-jacentes.
Comment créer un signet avant de le référencer?
Appelez DocumentBuilder.StartBookmark(bookmarkName) avant le contenu, et DocumentBuilder.EndBookmark(bookmarkName) après celui-ci, en utilisant le même nom pour les deux appels.
