Ładowanie dokumentów przy użyciu LoadOptions

Ładowanie dokumentów przy użyciu LoadOptions

Ten przewodnik pokazuje, jak kontrolować ładowanie dokumentów poza samą ścieżką pliku lub strumieniem, używając klasy LoadOptions. Document posiada przeciążenia konstruktorów, które przyjmują instancję LoadOptions — Document(fileName, loadOptions) i Document(stream, loadOptions) — tak że wszystkie opisane tutaj ustawienia mają zastosowanie w czasie ładowania, zanim obiekt dokumentu zostanie zwrócony do twojego kodu.

Klasa LoadOptions

LoadOptions zawiera ustawienia Aspose.Words potrzebne FOSS podczas ładowania dokumentu do obiektu Document. Jego konstruktory obejmują konstruktor bez parametrów LoadOptions(), LoadOptions(password) umożliwiający bezpośrednie otwarcie pliku zabezpieczonego hasłem oraz LoadOptions(loadFormat, password, baseUri) pozwalający na jawne określenie formatu. Oprócz Password i BaseUri (używanych do rozwiązywania względnych odwołań, takich jak połączone zasoby), LoadOptions udostępnia Encoding dla formatów tekstowych, TempFolder do przetwarzania dużych dokumentów, MswVersion aby określić, które konwencje formatu wersji Worda mają zastosowanie, oraz UpdateDirtyFields, IgnoreOleData i UseSystemLcid dla bardziej precyzyjnej kontroli zachowania podczas ładowania. LoadOptions.FontSettings pozwala dostarczyć FontSettings w czasie ładowania, zamiast konfigurować czcionki dopiero po załadowaniu dokumentu.

Opcje ładowania specyficzne dla formatu

Niektóre formaty mają własną podklasę LoadOptions, udostępniającą ustawienia specyficzne dla tego formatu. TxtLoadOptions (dla zwykłego tekstu) dodaje AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection oraz oddzielne LeadingSpacesOptions/TrailingSpacesOptions typu TxtLeadingSpacesOptions/TxtTrailingSpacesOptions, służące do kontrolowania, jak obsługiwana jest wiodąca i końcowa biała spacja w każdej linii. MarkdownLoadOptions dodaje PreserveEmptyLines, ImportUnderlineFormatting i SoftLineBreakCharacter, aby kontrolować, jak konwencje podziału linii w Markdown mapują się na paragrafy i uruchomienia w dokumencie. Obie podklasy dziedziczą każde ogólne własności LoadOptions, więc hasło lub wywołanie zwrotne ładowania zasobów ustawione na instancji TxtLoadOptions lub MarkdownLoadOptions zachowuje się tak samo jak w klasie bazowej.

Wywołania zwrotne ładowania zasobów

LoadOptions.ResourceLoadingCallback akceptuje implementację IResourceLoadingCallback, która jest powiadamiana w miarę jak loader rozwiązuje zewnętrzne zasoby odwoływane przez ładowany dokument. Wywołanie zwrotne otrzymuje ResourceLoadingArgs opisujący ResourceType zasobu będącego w trakcie ładowania i zwraca ResourceLoadingAction, aby poinformować loader, czy załadować zasób normalnie, pominąć go lub zastąpić własnymi danymi. Jest to punkt rozszerzenia służący do kontrolowania lub przechwytywania rozwiązywania zasobów podczas ładowania, niezależnie od tego, jaki format jest odczytywany.

Ustawienia języka, kierunku i odzyskiwania

LoadOptions.LanguagePreferences jest obiektem LanguagePreferences, którego DefaultEditingLanguage (wartość wyliczeniowa EditingLanguage) ustawia język, który Aspose.Words FOSS przyjmuje, gdy dokument nie określa go jawnie; AddEditingLanguage(language) i AddEditingLanguages(languages) rejestrują dodatkowe języki, które dokument może używać. DocumentDirection (również udostępniony bezpośrednio na TxtLoadOptions) jest wyliczeniem z wartościami LeftToRight, RightToLeft i Auto służącymi do kontrolowania kierunku przepływu tekstu przy ładowaniu. LoadOptions.RecoveryMode przyjmuje wartość DocumentRecoveryMode, która kontroluje, jak loader reaguje, gdy napotka nieprawidłowy lub częściowo uszkodzony dokument.

Wywołania zwrotne postępu i ostrzeżeń

Poza ładowaniem zasobów, LoadOptions.WarningCallback i LoadOptions.ProgressCallback akceptują implementacje wywołań zwrotnych, które są powiadamiane odpowiednio o niekrytycznych problemach napotkanych podczas ładowania oraz o postępie ładowania — przydatne do udostępniania odzyskiwalnych problemów kodowi wywołującemu lub raportowania postępu przy dużych dokumentach bez konieczności ciągłego odpytywania.

Wskazówki i najlepsze praktyki

• Przekaż LoadOptions(password) (lub ustaw LoadOptions.Password) zamiast łapać wyjątek ładowania i ponawiać próbę — Aspose.Words FOSS potrzebuje hasła, zanim będzie w stanie w ogóle przetworzyć dokument.
• Ustaw LanguagePreferences.DefaultEditingLanguage podczas ładowania dokumentów, których metadane językowe są brakujące lub niewiarygodne, aby dalsze przetwarzanie zależne od języka zachowywało się przewidywalnie.
• Preferuj klasę opcji specyficznych dla formatu (TxtLoadOptions, MarkdownLoadOptions) zamiast bazowego LoadOptions przy ładowaniu tych formatów, ponieważ konkretna podklasa udostępnia ustawienia istotne dla formatu, których klasa bazowa nie posiada.
• Zaimplementuj IResourceLoadingCallback, gdy potrzebujesz przekierować, buforować lub zablokować rozwiązywanie zasobów zewnętrznych podczas ładowania, a nie po tym, jak dokument już znajduje się w pamięci.
• Ustaw LoadOptions.RecoveryMode celowo dla potoków przetwarzających dokumenty pochodzące z niezaufanych lub zewnętrznych źródeł, zamiast polegać na domyślnym zachowaniu przywracania.

Typowe problemy

FAQ

Jak załadować dokument zabezpieczony hasłem?

Utwórz LoadOptions z hasłem — new LoadOptions(password) — lub ustaw LoadOptions.Password, a następnie przekaż go do new Document(fileName, loadOptions) lub new Document(stream, loadOptions).

Czy potrzebuję podklasy LoadOptions specyficznej dla formatu, czy klasa bazowa jest wystarczająca?

Podstawowa klasa LoadOptions obejmuje ustawienia wspólne dla każdego formatu (hasło, kodowanie, wywołania zwrotne). Użyj podklasy specyficznej dla formatu, takiej jak TxtLoadOptions lub MarkdownLoadOptions, gdy potrzebujesz ustawień specyficznych dla tego formatu, na przykład obsługi białych znaków w plikach tekstowych lub konwencji podziału linii w Markdown.

Jak mogę przechwycić lub przekierować zasoby, do których odwołuje się dokument podczas ładowania?

Zaimplementuj IResourceLoadingCallback i przypisz go do LoadOptions.ResourceLoadingCallback przed ładowaniem. Wywołanie zwrotne otrzymuje ResourceLoadingArgs dla każdego zasobu i zwraca ResourceLoadingAction, określający, jak loader ma kontynuować.

Jak mogę kontrolować, jaki język Aspose.Words FOSS zakłada dla załadowanego dokumentu?

Ustaw LoadOptions.LanguagePreferences.DefaultEditingLanguage na wartość EditingLanguage przed ładowaniem; użyj AddEditingLanguage/AddEditingLanguages, aby zarejestrować dodatkowe języki, które dokument może zawierać.

Co się stanie, jeśli loader napotka nieprawidłowy dokument?

Zachowanie jest kontrolowane przez LoadOptions.RecoveryMode, wartość DocumentRecoveryMode, która określa, jak loader reaguje na problemy strukturalne w dokumencie źródłowym.

API Reference Podsumowanie

Zobacz także

• Aspose.Words for .NET — Enterprise Documentation