Chargement de documents avec LoadOptions

Chargement de documents avec LoadOptions

Ce guide montre comment contrôler le chargement de documents au-delà d’un simple chemin de fichier ou d’un flux, en utilisant la classe LoadOptions. Document possède des surcharges de constructeur qui acceptent une instance LoadOptions — Document(fileName, loadOptions) et Document(stream, loadOptions) — de sorte que tous les paramètres décrits ici s’appliquent au moment du chargement, avant que l’objet document ne soit retourné à votre code.

La classe LoadOptions

LoadOptions transporte les paramètres Aspose.Words dont FOSS a besoin lors du chargement d’un document dans un objet Document. Ses constructeurs incluent un LoadOptions() sans paramètre, LoadOptions(password) pour ouvrir directement un fichier protégé par mot de passe, et LoadOptions(loadFormat, password, baseUri) pour spécifier explicitement le format. Au-delà de Password et BaseUri (utilisés pour résoudre les références relatives telles que les ressources liées), LoadOptions expose Encoding pour les formats basés sur du texte, TempFolder pour le traitement de documents volumineux, MswVersion pour indiquer quelle version de Word s’applique aux conventions de format, et UpdateDirtyFields, IgnoreOleData et UseSystemLcid pour un contrôle plus fin du comportement de chargement. LoadOptions.FontSettings vous permet de fournir FontSettings au moment du chargement plutôt que de configurer les polices uniquement après le chargement du document.

Options de chargement spécifiques au format

Certains formats possèdent leur propre sous-classe LoadOptions exposant des paramètres spécifiques à ce format. TxtLoadOptions (pour le texte brut) ajoute AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection, ainsi que des LeadingSpacesOptions/TrailingSpacesOptions distincts de type TxtLeadingSpacesOptions/TxtTrailingSpacesOptions pour contrôler la manière dont les espaces blancs initiaux et finaux de chaque ligne sont gérés. MarkdownLoadOptions ajoute PreserveEmptyLines, ImportUnderlineFormatting et SoftLineBreakCharacter pour contrôler la façon dont les conventions de saut de ligne de Markdown sont mappées aux paragraphes et aux segments du document. Les deux sous-classes héritent de chaque propriété générale LoadOptions, de sorte qu’un mot de passe ou un rappel de chargement de ressource défini sur une instance TxtLoadOptions ou MarkdownLoadOptions se comporte de la même manière que sur la classe de base.

Rappels de chargement de ressources

LoadOptions.ResourceLoadingCallback accepte une implémentation de IResourceLoadingCallback, qui est notifiée lorsque le chargeur résout les ressources externes référencées par le document en cours de chargement. Le rappel reçoit un ResourceLoadingArgs décrivant le ResourceType de la ressource chargée, et renvoie un ResourceLoadingAction pour indiquer au chargeur s’il doit charger la ressource normalement, l’ignorer ou substituer des données personnalisées. C’est le point d’extension pour contrôler ou intercepter la résolution des ressources pendant le chargement, indépendamment du format lu.

Paramètres de langue, de direction et de récupération

LoadOptions.LanguagePreferences est un objet LanguagePreferences dont le DefaultEditingLanguage (une valeur d’énumération EditingLanguage) définit la langue Aspose.Words que FOSS suppose lorsqu’un document n’en spécifie pas explicitement ; AddEditingLanguage(language) et AddEditingLanguages(languages) enregistrent des langues supplémentaires que le document peut utiliser. DocumentDirection (également exposé directement sur TxtLoadOptions) est une énumération avec les valeurs LeftToRight, RightToLeft et Auto pour contrôler la direction du flux de texte lors du chargement. LoadOptions.RecoveryMode accepte une valeur DocumentRecoveryMode, qui détermine la façon dont le chargeur réagit lorsqu’il rencontre un document mal formé ou partiellement corrompu.

Rappels de progression et d’avertissement

Au-delà du chargement des ressources, LoadOptions.WarningCallback et LoadOptions.ProgressCallback acceptent des implémentations de rappels qui sont notifiées respectivement des problèmes non fatals rencontrés lors du chargement et de la progression du chargement — utiles pour exposer les problèmes récupérables au code appelant ou pour rapporter la progression sur de gros documents sans interroger périodiquement.

Conseils et bonnes pratiques

• Passez LoadOptions(password) (ou définissez LoadOptions.Password) plutôt que d’intercepter une exception de chargement et de réessayer — Aspose.Words FOSS a besoin du mot de passe avant de pouvoir analyser le document.
• Définissez LanguagePreferences.DefaultEditingLanguage lors du chargement de documents dont les métadonnées de langue sont manquantes ou peu fiables, afin que le traitement en aval dépendant de la langue se comporte de manière prévisible.
• Préférez la classe d’options spécifique au format (TxtLoadOptions, MarkdownLoadOptions) plutôt que la classe de base LoadOptions lors du chargement de ces formats, car la sous-classe spécifique expose des paramètres pertinents au format que la classe de base n’expose pas.
• Mettez en œuvre IResourceLoadingCallback lorsque vous devez rediriger, mettre en cache ou bloquer la résolution de ressources externes pendant le chargement plutôt qu’après que le document soit déjà en mémoire.
• Définissez LoadOptions.RecoveryMode délibérément pour les pipelines qui traitent des documents provenant de sources non fiables ou tierces, plutôt que de vous fier au comportement de récupération par défaut.

Problèmes courants

FAQ

Comment charger un document protégé par mot de passe?

Construisez LoadOptions avec le mot de passe — new LoadOptions(password) — ou définissez LoadOptions.Password, puis transmettez-le à new Document(fileName, loadOptions) ou new Document(stream, loadOptions).

Ai-je besoin d’une sous-classe LoadOptions spécifique au format, ou la classe de base suffit-elle?

La classe de base LoadOptions couvre les paramètres communs à chaque format (mot de passe, encodage, callbacks). Utilisez une sous-classe spécifique à un format comme TxtLoadOptions ou MarkdownLoadOptions lorsque vous avez besoin de paramètres propres à ce format, comme la gestion des espaces blancs pour les fichiers texte ou les conventions de saut de ligne pour le Markdown.

Comment intercepter ou rediriger les ressources qu’un document référence lors du chargement ?

Implémentez IResourceLoadingCallback et affectez-le à LoadOptions.ResourceLoadingCallback avant le chargement. Le callback reçoit un ResourceLoadingArgs par ressource et renvoie un ResourceLoadingAction qui décide de la suite du processus de chargement.

Comment contrôler la langue que Aspose.Words FOSS suppose pour un document chargé ?

Définissez LoadOptions.LanguagePreferences.DefaultEditingLanguage sur une valeur EditingLanguage avant le chargement ; utilisez AddEditingLanguage/AddEditingLanguages pour enregistrer des langues supplémentaires que le document peut contenir.

Que se passe-t-il si le chargeur rencontre un document mal formé ?

Le comportement est contrôlé par LoadOptions.RecoveryMode, une valeur DocumentRecoveryMode qui détermine comment le chargeur réagit aux problèmes structurels du document source.

API Reference Résumé

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation