Завантаження документів за допомогою LoadOptions

Завантаження документів за допомогою LoadOptions

У цьому посібнику показано, як керувати завантаженням документів, виходячи за межі простого шляху до файлу або потоку, використовуючи клас LoadOptions. У Document є перевантаження конструкторів, які приймають екземпляр LoadOptions — Document(fileName, loadOptions) і Document(stream, loadOptions) — тому будь-які налаштування, описані тут, застосовуються під час завантаження, ще до того, як об’єкт документа буде повернуто вашому коду.

Клас LoadOptions

LoadOptions містить налаштування Aspose.Words, які потрібні FOSS під час завантаження документа у об’єкт Document. Його конструктори включають безпараметричний LoadOptions(), LoadOptions(password) для безпосереднього відкриття файлу, захищеного паролем, та LoadOptions(loadFormat, password, baseUri) для явного зазначення формату. Окрім Password і BaseUri (використовуються для розв’язання відносних посилань, таких як пов’язані ресурси), LoadOptions відкриває Encoding для текстових форматів, TempFolder для обробки великих документів, MswVersion для вказання, які правила формату Word застосовуються, і UpdateDirtyFields, IgnoreOleData і UseSystemLcid для більш точного керування поведінкою завантаження. LoadOptions.FontSettings дозволяє передати FontSettings під час завантаження, а не налаштовувати шрифти лише після завантаження документа.

Параметри завантаження, специфічні для формату

Деякі формати мають власний підклас LoadOptions, який відкриває налаштування, специфічні для цього формату. TxtLoadOptions (для простого тексту) додає AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection та окремі LeadingSpacesOptions/TrailingSpacesOptions типу TxtLeadingSpacesOptions/TxtTrailingSpacesOptions для керування тим, як обробляються початкові та кінцеві пробіли у кожному рядку. MarkdownLoadOptions додає PreserveEmptyLines, ImportUnderlineFormatting і SoftLineBreakCharacter для керування тим, як правила розриву рядків у Markdown відображаються на абзаци та ділянки документа. Обидва підкласи успадковують усі загальні властивості LoadOptions, тому пароль або зворотний виклик завантаження ресурсів, встановлені в екземплярі TxtLoadOptions або MarkdownLoadOptions, поводяться так само, як у базовому класі.

Зворотні виклики завантаження ресурсів

LoadOptions.ResourceLoadingCallback приймає реалізацію IResourceLoadingCallback, яка сповіщається під час того, як завантажувач розв’язує зовнішні ресурси, на які посилається завантажуваний документ. Зворотний виклик отримує ResourceLoadingArgs, що описує ResourceType ресурсу, який завантажується, і повертає ResourceLoadingAction, щоб повідомити завантажувач, чи завантажувати ресурс звичайним способом, пропустити його чи підставити власні дані. Це точка розширення для керування або перехоплення розв’язання ресурсів під час завантаження, незалежно від того, який формат читається.

Налаштування мови, напрямку та відновлення

LoadOptions.LanguagePreferences — це об’єкт LanguagePreferences, у якого DefaultEditingLanguage (значення перерахування EditingLanguage) встановлює мову Aspose.Words, яку FOSS припускає, коли документ явно не вказує її; 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 під час завантаження документів, у яких відсутні або ненадійні метадані мови, щоб подальша обробка, залежна від мови, працювала передбачувано.
• Віддавайте перевагу класу параметрів, специфічному для формату (TxtLoadOptions, MarkdownLoadOptions), а не базовому LoadOptions під час завантаження цих форматів, оскільки конкретний підклас надає налаштування, що стосуються формату, яких не має базовий клас.
• Використовуйте IResourceLoadingCallback, коли потрібно перенаправляти, кешувати або блокувати розв’язання зовнішніх ресурсів під час завантаження, а не після того, як документ вже знаходиться в пам’яті.
• Навмисно встановлюйте LoadOptions.RecoveryMode для конвеєрів, що обробляють документи з ненадійних або сторонніх джерел, замість того, щоб покладатися на поведінку відновлення за замовчуванням.

Типові проблеми

FAQ

Як завантажити документ, захищений паролем?

Створіть LoadOptions з паролем — new LoadOptions(password) — або встановіть LoadOptions.Password, потім передайте його до new Document(fileName, loadOptions) або new Document(stream, loadOptions).

Чи потрібен мені підклас LoadOptions, специфічний для формату, чи базового класу достатньо?

Базовий клас LoadOptions охоплює налаштування, спільні для всіх форматів (пароль, кодування, зворотні виклики). Використовуйте підклас, специфічний для формату, такий як TxtLoadOptions або MarkdownLoadOptions, коли потрібні налаштування, специфічні для цього формату, наприклад обробка пробілів у текстових файлах або правила розриву рядків для Markdown.

Як перехопити або перенаправити ресурси, на які посилається документ під час завантаження?

Реалізуйте 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