Как загрузить документы Word в .NET
Как загрузить документы Word в .NET
Aspose.Words FOSS for .NET считывает документ в память сразу же, как только вы создаёте Document объект — каждый путь загрузки в библиотеке проходит через Document’s перегрузки конструктора и LoadOptions класс. Это руководство показывает, как загрузить документ из файла или потока, предоставить пароль или настройки, специфичные для формата, и управлять тем, что происходит, когда загрузка сталкивается с внешним ресурсом или документом, который может быть испорчен. Aspose.Words FOSS for .NET собирается из исходного кода и напрямую подключается в проекте, а не устанавливается из пакета — см. Руководство по установке для шагов сборки перед выполнением нижеуказанных задач.
Пошаговое руководство
Шаг 1: Загрузить документ из файла или потока
Document имеет пять конструкторов. Document() создаёт новый пустой документ, а не загружает его. Document(fileName) загружает напрямую из пути на диске, а Document(stream) загружает из любого читаемого Stream — удобно, когда источник не является файлом, например содержимое уже в памяти или полученное по сетевому соединению. У обоих есть сопутствующая перегрузка, принимающая второй аргумент, Document(fileName, loadOptions) и Document(stream, loadOptions), которые являются точкой входа для всех остальных задач в этом руководстве.
Шаг 2: Загрузить документ, защищённый паролем
Создайте LoadOptions с паролем перед вызовом Document(fileName, loadOptions) (или перегрузкой потока). new LoadOptions(password) устанавливает LoadOptions.Password напрямую; альтернативно, установите Password в экземпляре LoadOptions() без параметров перед передачей. Передайте пароль заранее, а не загружайте сначала и реагируйте на ошибку — Aspose.Words FOSS для .NET требует пароль для разбора защищённого файла, поэтому нет частично загруженного состояния для восстановления.
Шаг 3: Применить параметры, специфичные для формата, к текстовым и Markdown-источникам
Текстовые и Markdown-источники принимают настройки, которые базовый LoadOptions не раскрывает. TxtLoadOptions добавляет AutoNumberingDetection и DetectNumberingWithWhitespaces для распознавания нумерованных списков в обычном тексте, DetectHyperlinks для преобразования голых URL-ов в гиперссылки, DocumentDirection (LeftToRight, RightToLeft или Auto) для направления потока текста, а также отдельные LeadingSpacesOptions/TrailingSpacesOptions (типа TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) для обработки пробелов в начале и в конце каждой строки. MarkdownLoadOptions добавляет PreserveEmptyLines, ImportUnderlineFormatting и SoftLineBreakCharacter для управления тем, как правила разрыва строк в Markdown отображаются на абзацы и фрагменты. Обе подклассы наследуются от LoadOptions, поэтому пароль или обратный вызов загрузки ресурса, установленный в любом из них, ведёт себя так же, как в базовом классе — передайте экземпляр, специфичный для формата, в Document(fileName, loadOptions) точно так же, как вы бы передали обычный LoadOptions.
Шаг 4: Перенаправить или перехватить внешние ресурсы во время загрузки
Установите LoadOptions.ResourceLoadingCallback в реализацию IResourceLoadingCallback, когда необходимо контролировать, как внешняя ссылка в документе разрешается во время загрузки. Его метод ResourceLoading(args) получает ResourceLoadingArgs, описывающий ResourceType ресурса (Image, Font, CssStyleSheet или Document) вместе с Uri и OriginalUri, и возвращает ResourceLoadingAction — Default для обычной загрузки ресурса, Skip для его пропуска, или UserProvided для замены данными, предоставленными через ResourceLoadingArgs.SetData(data).
Шаг 5: Установить значения по умолчанию для языка и поведение восстановления
Если метаданные языка документа отсутствуют или ненадёжны, установите LoadOptions.LanguagePreferences.DefaultEditingLanguage в значение EditingLanguage перед загрузкой и используйте AddEditingLanguage(language) или AddEditingLanguages(languages) на LanguagePreferences для регистрации дополнительных языков, которые документ может содержать. Для источников, которые могут быть некорректными, установите LoadOptions.RecoveryMode в значение DocumentRecoveryMode — None для загрузки без попытки восстановления, или TryRecover чтобы загрузчик обходил некоторые структурные проблемы вместо полного отказа.
Распространённые проблемы и решения
Загрузка документа, защищённого паролем, всё равно вызывает исключение после предоставления пароля. Подтвердите, что пароль был установлен точно LoadOptions экземпляр, переданный в Document(fileName, loadOptions) (или перегрузка потока) — через new LoadOptions(password) или установкой Password после этого — и что именно этот объект передаётся конструктору. A LoadOptions который был создан, но никогда не передан Document не влияет на загрузку.
Настройки, специфичные для текста или Markdown, похоже, не применяются. Убедитесь, что TxtLoadOptions or MarkdownLoadOptions экземпляр — не базовый LoadOptions — был передан в Document конструктор. Только подкласс раскрывает свойства, специфичные для формата; передача базового класса компилируется, но безмолвно отбрасывает их.
Внешние ресурсы не перехватываются и не перенаправляются. ResourceLoadingCallback должен быть установлен на том же LoadOptions объекте, переданном в Document конструктор, и его необходимо назначить до вызова load. Назначение его после завершения загрузки не оказывает никакого эффекта.
Некорректный документ по-прежнему не загружается после установки RecoveryMode. DocumentRecoveryMode.TryRecover позволяет загрузчику обходить некоторые структурные проблемы в документе, но более серьёзные повреждения всё равно могут помешать успешной загрузке документа.
Документ, загруженный из Stream ведёт себя иначе, чем тот же файл, загруженный по пути. Убедитесь, что позиция потока находится в начале, прежде чем передавать его в Document(stream) or Document(stream, loadOptions) — поток, оставленный в середине содержимого, загружает только оставшиеся байты.
Часто задаваемые вопросы
Как загрузить документ без каких-либо специальных параметров?
Передайте путь к файлу или Stream непосредственно в Document(fileName) или Document(stream) — LoadOptions требуется только когда нужен пароль, настройки, специфичные для формата, или обратный вызов.
В чем разница между LoadOptions, TxtLoadOptions и MarkdownLoadOptions?
TxtLoadOptions и MarkdownLoadOptions оба наследуются от LoadOptions и добавляют настройки, специфичные соответственно для обычного текста и источников Markdown. Каждое общее свойство LoadOptions — пароль, кодировка, обратные вызовы — остаётся доступным в обоих подклассах.
Могу ли я загрузить документ непосредственно из массива байтов?
Оберните байты в MemoryStream и передайте этот поток в Document(stream) или Document(stream, loadOptions) — конструктора, принимающего массив байтов напрямую, нет.
Как я могу контролировать, что происходит, когда загрузчик не может разрешить внешний ресурс?
Реализуйте IResourceLoadingCallback и назначьте его LoadOptions.ResourceLoadingCallback. Верните ResourceLoadingAction.Skip из ResourceLoading(args), чтобы пропустить ресурс вместо того, чтобы загрузка завершилась ошибкой.
Изменит ли установка RecoveryMode способ загрузки корректно сформированного документа?
Нет. DocumentRecoveryMode меняет поведение только тогда, когда загрузчик действительно сталкивается со структурными проблемами — корректно сформированный документ загружается одинаково независимо от настройки.
