Загрузка документов с помощью 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