LoadOptions を使用したドキュメントの読み込み

LoadOptions を使用したドキュメントの読み込み

このガイドでは、LoadOptions クラスを使用して、単なるファイルパスやストリームを超えてドキュメントの読み込みを制御する方法を示します。Document には、LoadOptions インスタンス（Document(fileName, loadOptions) と Document(stream, loadOptions)）を受け取るコンストラクタのオーバーロードがあり、ここで説明する設定はすべて、ドキュメントオブジェクトがコードに返される前のロード時に適用されます。

LoadOptions クラス

LoadOptions は、Document オブジェクトにドキュメントをロードする際に Aspose.Words FOSS が必要とする設定を保持します。そのコンストラクタには、パラメータなしの LoadOptions()、パスワード保護されたファイルを直接開くための LoadOptions(password)、およびフォーマットを明示的に指定するための LoadOptions(loadFormat, password, baseUri) が含まれます。Password と BaseUri（リンクされたリソースなどの相対参照を解決するために使用）に加えて、LoadOptions はテキストベースのフォーマット用の Encoding、大規模ドキュメント処理用の TempFolder、適用される Word バージョンのフォーマット規則を指定する MswVersion、そしてロード動作をより細かく制御するための UpdateDirtyFields、IgnoreOleData、UseSystemLcid を公開しています。LoadOptions.FontSettings を使用すると、ドキュメントがロードされた後にフォントを設定するのではなく、ロード時に FontSettings を提供できます。

フォーマット固有のロードオプション

一部のフォーマットには、そのフォーマット固有の設定を公開する独自の LoadOptions サブクラスがあります。TxtLoadOptions（プレーンテキスト用）は、AutoNumberingDetection、DetectNumberingWithWhitespaces、DetectHyperlinks、DocumentDirection を追加し、各行の先頭と末尾の空白文字の処理方法を制御するための TxtLeadingSpacesOptions/TxtTrailingSpacesOptions 型の個別の LeadingSpacesOptions/TrailingSpacesOptions を提供します。MarkdownLoadOptions は、Markdown の改行規則がドキュメントの段落やランにどのようにマッピングされるかを制御するための PreserveEmptyLines、ImportUnderlineFormatting、SoftLineBreakCharacter を追加します。両サブクラスはすべての一般的な LoadOptions プロパティを継承するため、TxtLoadOptions または MarkdownLoadOptions インスタンスに設定されたパスワードやリソースロードコールバックは、ベースクラスと同様に動作します。

リソースロードコールバック

LoadOptions.ResourceLoadingCallback は IResourceLoadingCallback の実装を受け取ります。この実装はローダーがロード中のドキュメントが参照する外部リソースを解決する際に通知されます。コールバックはロード対象リソースの ResourceType を記述した ResourceLoadingArgs を受け取り、ローダーに対しリソースを通常通りロードするか、スキップするか、カスタムデータに置き換えるかを指示する ResourceLoadingAction を返します。これは、読み込むフォーマットに依存せず、ロード中のリソース解決を制御または介入するための拡張ポイントです。

言語、方向、リカバリ設定

LoadOptions.LanguagePreferences は LanguagePreferences オブジェクトで、DefaultEditingLanguage（EditingLanguage 列挙値）が、ドキュメントが明示的に言語を指定しない場合に FOSS が想定する言語 Aspose.Words を設定します。AddEditingLanguage(language) と AddEditingLanguages(languages) は、ドキュメントが使用できる追加の言語を登録します。DocumentDirection（TxtLoadOptions 上でも直接利用可能）は、ロード時のテキストフロー方向を制御するための列挙型で、LeftToRight、RightToLeft、Auto の値を持ちます。LoadOptions.RecoveryMode は DocumentRecoveryMode 値を受け取り、これによりロード時に不正または部分的に破損したドキュメントに遭遇した際のローダーの応答方法を制御します。

進捗および警告コールバック

リソースのロード以外にも、LoadOptions.WarningCallback と LoadOptions.ProgressCallback は、ロード中に発生した致命的でない問題とロード進捗についてそれぞれ通知されるコールバック実装を受け付けます。これは、呼び出し側コードに回復可能な問題を提示したり、ポーリングせずに大きなドキュメントの進捗を報告したりするのに便利です。

ヒントとベストプラクティス

• LoadOptions(password) を渡す（または LoadOptions.Password を設定する）ことで、ロード例外を捕捉してリトライするよりも良いです — Aspose.Words FOSS はドキュメントを解析する前にパスワードが必要です。
• 言語メタデータが欠如しているか信頼できないドキュメントをロードする際は、LanguagePreferences.DefaultEditingLanguage を設定してください。これにより、下流の言語依存処理が予測可能に動作します。
• それらのフォーマットを読み込む際は、ベースの LoadOptions よりも、フォーマット固有のオプションクラス (TxtLoadOptions, MarkdownLoadOptions) を使用してください。特定のサブクラスは、ベースクラスにはないフォーマットに関連する設定を公開しています。
• ドキュメントがメモリにロードされた後ではなく、ロード中に外部リソースの解決をリダイレクト、キャッシュ、またはブロックする必要がある場合は、IResourceLoadingCallback を実装してください。
• 信頼できない、またはサードパーティのソースからのドキュメントを処理するパイプラインでは、デフォルトのリカバリ動作に依存せず、LoadOptions.RecoveryMode を明示的に設定してください。

よくある問題

FAQ

パスワードで保護されたドキュメントを読み込むにはどうすればよいですか？

パスワード — new LoadOptions(password) — を使用して LoadOptions を作成するか、LoadOptions.Password を設定し、そしてそれを new Document(fileName, loadOptions) または new Document(stream, loadOptions) に渡してください。

フォーマット固有の LoadOptions サブクラスが必要ですか、それともベースクラスだけで十分ですか？

基本の LoadOptions クラスは、すべてのフォーマットに共通する設定（パスワード、エンコーディング、コールバック）をカバーします。テキストファイルの空白処理や Markdown の改行規則など、特定のフォーマットに固有の設定が必要な場合は、TxtLoadOptions や MarkdownLoadOptions のようなフォーマット固有のサブクラスを使用してください。

ドキュメントの読み込み中に、参照しているリソースをどのようにインターセプトまたはリダイレクトできますか？

ロードする前に IResourceLoadingCallback を実装し、LoadOptions.ResourceLoadingCallback に割り当てます。コールバックはリソースごとに ResourceLoadingArgs を受け取り、ローダーの動作を決定する ResourceLoadingAction を返します。

ロードされたドキュメントに対して、Aspose.Words FOSS が想定する言語をどのように制御できますか？

ロードする前に LoadOptions.LanguagePreferences.DefaultEditingLanguage を EditingLanguage の値に設定します。AddEditingLanguage/AddEditingLanguages を使用して、ドキュメントが含む可能性のある追加の言語を登録してください。

ローダーが不正な形式のドキュメントに遭遇した場合、何が起こりますか？

動作は LoadOptions.RecoveryMode によって制御されます。これは DocumentRecoveryMode の値で、ローダーがソースドキュメントの構造的問題にどのように応答するかを決定します。

API Reference 概要

参照

• Aspose.Words for .NET — Enterprise Documentation