Laden von Dokumenten mit LoadOptions

Dokumente laden mit LoadOptions

Dieser Leitfaden zeigt, wie Sie das Laden von Dokumenten über einen einfachen Dateipfad oder Stream hinaus steuern können, indem Sie die Klasse LoadOptions verwenden. Document verfügt über Konstruktor-Überladungen, die eine LoadOptions-Instanz akzeptieren – Document(fileName, loadOptions) und Document(stream, loadOptions) – sodass alle hier beschriebenen Einstellungen zur Ladezeit gelten, bevor das Dokumentobjekt an Ihren Code zurückgegeben wird.

Die Klasse LoadOptions

LoadOptions übernimmt die Einstellungen Aspose.Words, die FOSS beim Laden eines Dokuments in ein Document-Objekt benötigt. Zu seinen Konstruktoren gehören ein parameterloser LoadOptions(), LoadOptions(password) zum direkten Öffnen einer passwortgeschützten Datei und LoadOptions(loadFormat, password, baseUri) zum expliziten Angeben des Formats. Zusätzlich zu Password und BaseUri (die zur Auflösung relativer Verweise wie verknüpfter Ressourcen verwendet werden), stellt LoadOptions Encoding für textbasierte Formate, TempFolder für die Verarbeitung großer Dokumente, MswVersion zur Angabe, welche Word-Version-Formatkonventionen gelten, sowie UpdateDirtyFields, IgnoreOleData und UseSystemLcid für eine feinere Steuerung des Ladevorgangs bereit. LoadOptions.FontSettings ermöglicht es, FontSettings bereits beim Laden bereitzustellen, anstatt Schriftarten erst nach dem Laden des Dokuments zu konfigurieren.

Formatspezifische Ladeoptionen

Einige Formate besitzen ihre eigene LoadOptions-Unterklasse, die ein formatspezifische Einstellungen offenlegt. TxtLoadOptions (für Klartext) fügt AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection sowie separate LeadingSpacesOptions/TrailingSpacesOptions vom Typ TxtLeadingSpacesOptions/TxtTrailingSpacesOptions hinzu, um zu steuern, wie führende und abschließende Leerzeichen jeder Zeile behandelt werden. MarkdownLoadOptions ergänzt PreserveEmptyLines, ImportUnderlineFormatting und SoftLineBreakCharacter, um zu bestimmen, wie die Zeilenumbruch-Konventionen von Markdown auf Dokumentabsätze und -läufe abgebildet werden. Beide Unterklassen erben jede allgemeine LoadOptions-Eigenschaft, sodass ein Passwort- oder Ressourcen-Lade-Callback, das auf einer TxtLoadOptions- oder MarkdownLoadOptions-Instanz gesetzt wird, sich genauso verhält wie in der Basisklasse.

Ressourcen-Lade-Callbacks

LoadOptions.ResourceLoadingCallback akzeptiert eine Implementierung von IResourceLoadingCallback, die benachrichtigt wird, wenn der Loader externe Ressourcen auflöst, die im zu ladenden Dokument referenziert werden. Der Callback erhält ein ResourceLoadingArgs, das die ResourceType der zu ladenden Ressource beschreibt, und gibt ein ResourceLoadingAction zurück, um dem Loader mitzuteilen, ob die Ressource normal geladen, übersprungen oder durch benutzerdefinierte Daten ersetzt werden soll. Dies ist der Erweiterungspunkt zur Steuerung oder Abfangung der Ressourcenauflösung während des Ladens, unabhängig davon, welches Format gelesen wird.

Einstellungen für Sprache, Richtung und Wiederherstellung

LoadOptions.LanguagePreferences ist ein LanguagePreferences-Objekt, dessen DefaultEditingLanguage (ein EditingLanguage-Enum-Wert) die Sprache Aspose.Words festlegt, die FOSS annimmt, wenn ein Dokument keine explizite Angabe enthält; AddEditingLanguage(language) und AddEditingLanguages(languages) registrieren zusätzliche Sprachen, die das Dokument verwenden kann. DocumentDirection (auch direkt auf TxtLoadOptions verfügbar) ist ein Enum mit den Werten LeftToRight, RightToLeft und Auto zur Steuerung der Textflussrichtung beim Laden. LoadOptions.RecoveryMode nimmt einen DocumentRecoveryMode-Wert entgegen, der bestimmt, wie der Loader reagiert, wenn er auf ein fehlerhaftes oder teilweise beschädigtes Dokument stößt.

Fortschritts- und Warnungs-Callbacks

Über das Laden von Ressourcen hinaus akzeptieren LoadOptions.WarningCallback und LoadOptions.ProgressCallback Callback-Implementierungen, die jeweils über nicht-fatale Probleme benachrichtigt werden, die beim Laden auftreten, und über den Ladevorgang selbst — nützlich, um wiederherstellbare Probleme dem Aufrufcode zugänglich zu machen oder den Fortschritt bei großen Dokumenten ohne Polling zu melden.

Tipps und bewährte Vorgehensweisen

• Übergeben Sie LoadOptions(password) (oder setzen Sie LoadOptions.Password), anstatt eine Ladeausnahme abzufangen und erneut zu versuchen — Aspose.Words FOSS benötigt das Passwort, bevor es das Dokument überhaupt parsen kann.
• Setzen Sie LanguagePreferences.DefaultEditingLanguage, wenn Sie Dokumente laden, deren Sprachmetadaten fehlen oder unzuverlässig sind, damit nachgelagerte sprachabhängige Verarbeitungen vorhersehbar funktionieren.
• Bevorzuge die formatspezifische Options-Klasse (TxtLoadOptions, MarkdownLoadOptions) gegenüber der Basis-LoadOptions beim Laden dieser Formate, da die spezialisierte Unterklasse formatbezogene Einstellungen bereitstellt, die die Basisklasse nicht hat.
• Implementiere IResourceLoadingCallback, wenn du während des Ladens die Weiterleitung, das Caching oder das Blockieren der Auflösung externer Ressourcen benötigst, anstatt dies erst zu tun, nachdem das Dokument bereits im Speicher ist.
• Setze LoadOptions.RecoveryMode bewusst für Pipelines, die Dokumente aus nicht vertrauenswürdigen oder Drittanbieter-Quellen verarbeiten, anstatt sich auf das Standard-Recovery-Verhalten zu verlassen.

Häufige Probleme

FAQ

Wie lade ich ein passwortgeschütztes Dokument?

Erstelle LoadOptions mit dem Passwort — new LoadOptions(password) — oder setze LoadOptions.Password, und übergebe es anschließend an new Document(fileName, loadOptions) oder new Document(stream, loadOptions).

Benötige ich eine formatspezifische LoadOptions-Unterklasse, oder reicht die Basisklasse aus?

Die Basisklasse LoadOptions enthält Einstellungen, die für jedes Format gemeinsam sind (Passwort, Kodierung, Callbacks). Verwenden Sie eine formatbezogene Unterklasse wie TxtLoadOptions oder MarkdownLoadOptions, wenn Sie formatspezifische Einstellungen benötigen, etwa die Behandlung von Leerzeichen bei Textdateien oder Zeilenumbruch-Konventionen für Markdown.

Wie kann ich während des Ladevorgangs Ressourcen, auf die ein Dokument verweist, abfangen oder umleiten?

Implementieren Sie IResourceLoadingCallback und weisen Sie es LoadOptions.ResourceLoadingCallback vor dem Einlesen zu. Der Callback erhält pro Ressource ein ResourceLoadingArgs und gibt ein ResourceLoadingAction zurück, das bestimmt, wie der Loader fortfährt.

Wie lege ich fest, welche Sprache Aspose.Words FOSS für ein eingelesenes Dokument annimmt?

Setzen Sie LoadOptions.LanguagePreferences.DefaultEditingLanguage auf einen EditingLanguage-Wert vor dem Einlesen; verwenden Sie AddEditingLanguage/AddEditingLanguages, um weitere Sprachen zu registrieren, die das Dokument enthalten könnte.

Was geschieht, wenn der Loader auf ein fehlerhaftes Dokument trifft?

Das Verhalten wird von LoadOptions.RecoveryMode gesteuert, einem DocumentRecoveryMode-Wert, der bestimmt, wie der Loader auf strukturelle Probleme im Quelldokument reagiert.

API Reference Zusammenfassung

Siehe auch

• Aspose.Words for .NET — Enterprise Documentation