Carregando documentos com LoadOptions

Carregando Documentos com LoadOptions

Este guia mostra como controlar o carregamento de documentos além de um simples caminho de arquivo ou fluxo, usando a classe LoadOptions. Document possui sobrecargas de construtor que aceitam uma instância LoadOptions — Document(fileName, loadOptions) e Document(stream, loadOptions) — de modo que quaisquer das configurações descritas aqui se aplicam no momento do carregamento, antes que o objeto do documento seja devolvido ao seu código.

A Classe LoadOptions

LoadOptions contém as configurações Aspose.Words que o FOSS precisa ao carregar um documento em um objeto Document. Seus construtores incluem um LoadOptions() sem parâmetros, LoadOptions(password) para abrir diretamente um arquivo protegido por senha, e LoadOptions(loadFormat, password, baseUri) para especificar o formato explicitamente. Além de Password e BaseUri (usados para resolver referências relativas, como recursos vinculados), LoadOptions expõe Encoding para formatos baseados em texto, TempFolder para processamento de documentos grandes, MswVersion para especificar quais convenções de formato da versão do Word se aplicam, e UpdateDirtyFields, IgnoreOleData e UseSystemLcid para controle mais refinado do comportamento de carregamento. LoadOptions.FontSettings permite que você forneça FontSettings no momento do carregamento, em vez de configurar fontes somente após o documento ser carregado.

Opções de Carregamento Específicas de Formato

Alguns formatos têm sua própria subclasse LoadOptions que expõe configurações específicas para esse formato. TxtLoadOptions (para texto simples) adiciona AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection e LeadingSpacesOptions/TrailingSpacesOptions separados do tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions para controlar como o espaço em branco inicial e final em cada linha é tratado. MarkdownLoadOptions adiciona PreserveEmptyLines, ImportUnderlineFormatting e SoftLineBreakCharacter para controlar como as convenções de quebra de linha do Markdown são mapeadas para parágrafos e trechos do documento. Ambas as subclasses herdam todas as propriedades gerais LoadOptions, de modo que uma senha ou callback de carregamento de recursos definido em uma instância TxtLoadOptions ou MarkdownLoadOptions se comporta da mesma forma que na classe base.

Callbacks de Carregamento de Recursos

LoadOptions.ResourceLoadingCallback aceita uma implementação de IResourceLoadingCallback, que é notificada à medida que o carregador resolve recursos externos referenciados pelo documento sendo carregado. O callback recebe um ResourceLoadingArgs descrevendo o ResourceType do recurso sendo carregado e retorna um ResourceLoadingAction para informar ao carregador se deve carregar o recurso normalmente, ignorá-lo ou substituir por dados personalizados. Este é o ponto de extensão para controlar ou interceptar a resolução de recursos durante o carregamento, independentemente do formato que está sendo lido.

Configurações de Idioma, Direção e Recuperação

LoadOptions.LanguagePreferences é um objeto LanguagePreferences cujo DefaultEditingLanguage (um valor enum EditingLanguage) define o idioma Aspose.Words que o FOSS assume quando um documento não especifica um explicitamente; AddEditingLanguage(language) e AddEditingLanguages(languages) registram idiomas adicionais que o documento pode usar. DocumentDirection (também exposto diretamente em TxtLoadOptions) é um enum com valores LeftToRight, RightToLeft e Auto para controlar a direção do fluxo de texto ao carregar. LoadOptions.RecoveryMode recebe um valor DocumentRecoveryMode, que controla como o carregador responde ao encontrar um documento malformado ou parcialmente corrompido.

Callbacks de Progresso e Aviso

Além do carregamento de recursos, LoadOptions.WarningCallback e LoadOptions.ProgressCallback aceitam implementações de callbacks que são notificadas sobre problemas não fatais encontrados durante o carregamento e sobre o progresso do carregamento, respectivamente — úteis para expor problemas recuperáveis ao código chamador ou relatar o progresso em documentos grandes sem necessidade de polling.

Dicas e Melhores Práticas

• Passe LoadOptions(password) (ou defina LoadOptions.Password) em vez de capturar uma exceção de carregamento e tentar novamente — Aspose.Words FOSS precisa da senha antes de poder analisar o documento.
• Defina LanguagePreferences.DefaultEditingLanguage ao carregar documentos cujo metadado de idioma está ausente ou não confiável, para que o processamento dependente de idioma a jusante se comporte de forma previsível.
• Prefira a classe de opções específicas do formato (TxtLoadOptions, MarkdownLoadOptions) em vez da LoadOptions base ao carregar esses formatos, pois a subclasse específica expõe configurações relevantes ao formato que a classe base não possui.
• Implemente IResourceLoadingCallback quando precisar redirecionar, armazenar em cache ou bloquear a resolução de recursos externos durante o carregamento, em vez de após o documento já estar na memória.
• Defina LoadOptions.RecoveryMode deliberadamente para pipelines que processam documentos de fontes não confiáveis ou de terceiros, em vez de confiar no comportamento padrão de recuperação.

Problemas comuns

FAQ

Como faço para carregar um documento protegido por senha?

Construa LoadOptions com a senha — new LoadOptions(password) — ou defina LoadOptions.Password, então passe-o para new Document(fileName, loadOptions) ou new Document(stream, loadOptions).

Preciso de uma subclasse LoadOptions específica do formato, ou a classe base é suficiente?

A classe base LoadOptions cobre configurações comuns a todos os formatos (senha, codificação, callbacks). Use uma subclasse específica de formato, como TxtLoadOptions ou MarkdownLoadOptions, quando precisar de configurações específicas desse formato, como tratamento de espaços em branco para arquivos de texto ou convenções de quebra de linha para Markdown.

Como interceptar ou redirecionar recursos que um documento referencia durante o carregamento?

Implemente IResourceLoadingCallback e atribua-o a LoadOptions.ResourceLoadingCallback antes do carregamento. O callback recebe um ResourceLoadingArgs por recurso e retorna um ResourceLoadingAction que decide como o carregador prossegue.

Como controlar qual idioma o Aspose.Words FOSS assume para um documento carregado?

Defina LoadOptions.LanguagePreferences.DefaultEditingLanguage como um valor EditingLanguage antes do carregamento; use AddEditingLanguage/AddEditingLanguages para registrar idiomas adicionais que o documento possa conter.

O que acontece se o carregador encontrar um documento malformado?

O comportamento é controlado por LoadOptions.RecoveryMode, um valor DocumentRecoveryMode que determina como o carregador responde a problemas estruturais no documento de origem.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation