Travailler avec des documents

Aspose.Words FOSS pour .NET représente chaque fichier Word comme un modèle d’objet en mémoire enraciné dans la classe Document, DocumentBuilder fournissant un API de haut niveau basé sur le curseur pour la création de contenu. Ce guide couvre la création et le chargement de documents, la création avec DocumentBuilder, la structure section/corps, la traversée de l’arbre de nœuds, la combinaison de documents et leur protection.

Création et chargement de documents

Créez un document vierge avec new Document(), ou ouvrez un fichier existant en passant un chemin ou Stream au constructeur Document(fileName) ou Document(stream). Les surcharges qui acceptent un argument LoadOptions vous permettent de contrôler le comportement du chargement, comme fournir un mot de passe pour un fichier chiffré.

Avant de charger un fichier provenant d’une source inconnue ou non fiable, FileFormatUtil.DetectFileFormat(fileName) (ou la surcharge Stream) renvoie un FileFormatInfo décrivant le LoadFormat détecté, et indique si le fichier IsEncrypted, HasDigitalSignature ou HasMacros.

Rédaction avec DocumentBuilder

DocumentBuilder encapsule un Document et expose un curseur que vous déplacez à travers le document tout en insérant du contenu. Write(text) et Writeln(text) insèrent du texte au curseur; InsertParagraph() commence un nouveau paragraphe. Les propriétés de formatage sur le constructeur — Font, ParagraphFormat, ListFormat, PageSetup — s’appliquent à tout ce qui est écrit ensuite.

Déplacez le curseur avec MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) ou MoveToParagraph(paragraphIndex, characterIndex). Les propriétés CurrentNode, CurrentParagraph et CurrentSection du constructeur indiquent sa position actuelle dans l’arbre.

Structure du document: Sections et corps

Un Document contient un SectionCollection (Document.Sections, plus FirstSection / LastSection); chaque Section possède un Body, une collection facultative d’en-têtes/pieds de page, et son propre PageSetup. Section.AppendContent(sourceSection) et PrependContent(sourceSection) copient le contenu entre les sections, et ClearContent() réinitialise une section sans la supprimer du document.

Dans un Body, le contenu est exposé via Body.Paragraphs (un ParagraphCollection) et Body.Tables. Un Range — disponible depuis Document, Section, Paragraph et d’autres nœuds — représente une zone contiguë de l’arbre; Range.Text lit son texte brut et Range.Replace(pattern, replacement) effectue une recherche-remplacement uniquement sur cette zone.

Parcourir l’arbre des nœuds avec DocumentVisitor

Chaque partie d’un document — sections, paragraphes, exécutions, tableaux, champs, formes, commentaires, notes de bas de page — est un Node dans un arbre composite dont la racine est Document. Pour traiter chaque nœud d’un type donné sans récursion manuelle, sous-classez l’DocumentVisitor abstrait et surchargez les rappels Visit*Start / Visit*End dont vous avez besoin, comme VisitParagraphStart(paragraph) ou VisitRun(run), puis appelez document.Accept(visitor). Chaque rappel peut renvoyer un VisitorAction (Continue, SkipThisNode ou Stop) pour contrôler la façon dont le parcours se poursuit.

Clonage, importation et ajout de contenu

Document.Clone() produit une copie profonde d’un document complet. Pour déplacer du contenu entre deux instances Document différentes, appelez ImportNode(srcNode, isImportChildren) sur le document de destination pour importer un nœud d’un arbre externe, ou appelez Document.AppendDocument(srcDoc, importFormatMode) pour ajouter les sections d’un document à un autre en utilisant un ImportFormatMode choisi — KeepSourceFormatting, UseDestinationStyles ou KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) insère le contenu du document source au curseur du constructeur au lieu de la fin du document de destination.

Protection des documents

Document.Protect(type, password) restreint la modification selon une valeur ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields ou NoProtection pour supprimer la protection. Unprotect() (avec ou sans mot de passe) l’inverse. Il s’agit d’une restriction d’édition imposée par Word, distincte du chiffrement par mot de passe OOXML que OoxmlSaveOptions.Password applique lors de l’enregistrement d’un fichier.

Conseils et bonnes pratiques

Préférez DocumentBuilder pour la construction de nouveau contenu; passez à la manipulation directe des nœuds (AppendChild, InsertAfter, Clone) lorsque vous avez besoin d’un contrôle fin sur un arbre existant.
Appelez FileFormatUtil.DetectFileFormat avant de charger un fichier provenant d’une source non fiable ou fournie par l’utilisateur afin de pouvoir vérifier LoadFormat et rejeter tôt les entrées non prises en charge ou chiffrées.
Lors de la combinaison de documents avec AppendDocument ou InsertDocument, choisissez délibérément le ImportFormatMode — KeepSourceFormatting préserve l’apparence de la source, UseDestinationStyles correspond à l’ensemble de styles du document cible.
Utilisez une sous-classe DocumentVisitor plutôt qu’une traversée récursive manuelle de l’arbre lorsque vous devez traiter chaque instance d’un type de nœud de manière cohérente.
Document.Protect est une restriction d’édition, pas un chiffrement — associez-le à OoxmlSaveOptions.Password si le fichier enregistré doit lui-même nécessiter un mot de passe pour être ouvert.

Problèmes courants

Problème	Cause	Correction
`Document(fileName)` lance une exception pour un fichier qui s’ouvre correctement dans Word	Le format du fichier n’est pas pris en charge par cette édition pour le chargement	Appelez `FileFormatUtil.DetectFileFormat` d’abord et vérifiez le `LoadFormat` retourné avant de charger
Le contenu ajouté utilise les mauvaises polices ou styles	Mauvaise correspondance de `ImportFormatMode` entre les ensembles de styles source et destination	Passez `KeepSourceFormatting` ou `UseDestinationStyles` explicitement au lieu de vous fier à une valeur par défaut
Le parcours `DocumentVisitor` s’arrête prématurément ou saute du contenu	Une substitution `VisitStart` / `VisitEnd` renvoie `SkipThisNode` ou `Stop` de manière non intentionnelle	Retournez `VisitorAction.Continue` pour chaque substitution, sauf si vous avez spécifiquement l’intention de sauter ou d’arrêter
`Unprotect()` n’a aucun effet	Le document n’était pas protégé par un mot de passe, ou le mauvais mot de passe a été fourni	Appelez `Unprotect()` sans arguments si `Protect` a été appelé sans mot de passe, sinon transmettez le mot de passe correspondant

FAQ

Quelle est la différence entre `Document.Clone()` et `ImportNode`?

Clone() copie un document entier dans une nouvelle instance Document. ImportNode(srcNode, isImportChildren) transfère un nœud unique (et éventuellement ses enfants) d’un arbre de document à un autre, ce qui est ce que vous utilisez lorsque vous combinez un contenu spécifique plutôt que des documents entiers.

Quels formats de fichier `Document(fileName)` peut charger?

Document(fileName) charge DOCX, DOCM, DOTX, DOTM, Flat OPC (plus ses variantes macro-activées et de modèle), Markdown et texte brut. Les formats de traitement de texte et Web plus anciens sont exclus des chargeurs de cette édition.

Comment trouver où un `DocumentBuilder` est actuellement positionné?

Lisez CurrentNode, CurrentParagraph ou CurrentSection sur l’instance du constructeur.

Est-ce que `Document.Protect` chiffre le fichier enregistré?

Non — il s’agit d’une restriction d’édition imposée par Word lors de l’ouverture du fichier. Pour exiger un mot de passe uniquement pour ouvrir le fichier, définissez OoxmlSaveOptions.Password lors de l’enregistrement.

Comment lire uniquement les paragraphes dans le corps d’un document?

Utilisez la collection Body.Paragraphs, ou Body.GetChildNodes(nodeType, isDeep) pour d’autres types de nœuds.

API Reference Résumé

Class/Method	Description
`Document`	Racine du modèle d’objet de document ; les constructeurs chargent depuis un fichier ou un flux, ou créent un document vierge.
`Document.Save`	Écrit le document dans un fichier, un flux ou une réponse HTTP au format choisi.
`Document.Clone()`	Produit une copie profonde de l’intégralité du document.
`Document.Protect(type, password)` / `Unprotect()`	Applique ou supprime une restriction d’édition.
`Document.AppendDocument(srcDoc, importFormatMode)`	Ajoute les sections d’un autre document à celui-ci.
`DocumentBuilder`	Fonction API basée sur le curseur pour écrire du texte et insérer du contenu dans un document.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Insère le contenu d’un document source au curseur.
`Section` / `SectionCollection`	Une seule section d’un document, ainsi que l’ensemble de toutes les sections.
`Body`	Conteneur du texte principal (paragraphes et tableaux) d’une section.
`Range`	Une zone contiguë de l’arborescence du document ; prend en charge `Text` et `Replace`.
`DocumentVisitor`	Classe de base abstraite pour parcourir chaque nœud de l’arborescence du document.
`ProtectionType`	Énumération des restrictions d’édition au niveau du document.
`FileFormatUtil.DetectFileFormat`	Détecte le format d’un fichier ou d’un flux avant de le charger.

Voir aussi

Aspose.Words for .NET — Enterprise Documentation

Travailler avec des documents