Especifique opções de carregamento

Ao carregar um documento, você pode definir algumas propriedades avançadas. Aspose.Words fornece a classe LoadOptions, que permite um controle mais preciso do processo de carregamento. Alguns formatos de carregamento possuem uma classe correspondente que contém opções de carregamento para este formato de carregamento, por exemplo, há PdfLoadOptions para carregar em formato PDF ou TxtLoadOptions para carregar em TXT. Este artigo fornece exemplos de como trabalhar com opções da classe LoadOptions.

Defina a versão Microsoft Word para alterar a aparência

Diferentes versões do aplicativo Microsoft Word podem exibir documentos de maneira diferente. Por exemplo, há um problema bem conhecido com documentos OOXML, como DOCX ou DOTX, produzidos usando o WPS Office. Nesse caso, elementos essenciais de marcação do documento podem estar faltando ou podem ser interpretados de forma diferente, fazendo com que o Microsoft Word 2019 mostre tal documento de forma diferente em comparação com o Microsoft Word 2010.

Por padrão, o Aspose.Words abre documentos usando as regras do Microsoft Word 2019. Se você precisar fazer com que o carregamento do documento apareça como aconteceria em uma das versões anteriores da aplicação Microsoft Word, você deve especificar explicitamente a versão desejada usando a propriedade MswVersion da classe LoadOptions.

O exemplo de código a seguir mostra como definir a versão Microsoft Word com opções de carregamento:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Create a new LoadOptions object, which will load documents according to MS Word 2019 specification by default
// and change the loading version to Microsoft Word 2010.
LoadOptions loadOptions = new LoadOptions { MswVersion = MsWordVersion.Word2010 };
            
Document doc = new Document(MyDir + "Document.docx", loadOptions);

doc.Save(ArtifactsDir + "WorkingWithLoadOptions.SetMsWordVersion.docx");

Defina preferências de idioma para alterar a aparência

Os detalhes da exibição de um documento em Microsoft Word dependem não apenas da versão do aplicativo e do valor da propriedade MswVersion, mas também das configurações de idioma. Microsoft Word pode mostrar documentos de forma diferente dependendo das configurações da caixa de diálogo “Preferências de idioma do Office”, que podem ser encontradas em “Arquivo → Opções → Idioma”. Usando esta caixa de diálogo, um usuário pode selecionar, por exemplo, o idioma principal, os idiomas de revisão, os idiomas de exibição e assim por diante. Aspose.Words fornece a propriedade LanguagePreferences como equivalente a esta caixa de diálogo. Se a saída Aspose.Words for diferente da saída Microsoft Word, defina o valor apropriado para EditingLanguage – isso pode melhorar o documento de saída.

O exemplo de código a seguir mostra como definir o japonês como EditingLanguage:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
LoadOptions loadOptions = new LoadOptions();
// Set language preferences that will be used when document is loading.
loadOptions.LanguagePreferences.AddEditingLanguage(EditingLanguage.Japanese);

Document doc = new Document(MyDir + "No default editing language.docx", loadOptions);

int localeIdFarEast = doc.Styles.DefaultFont.LocaleIdFarEast;
Console.WriteLine(
    localeIdFarEast == (int)EditingLanguage.Japanese
        ? "The document either has no any FarEast language set in defaults or it was set to Japanese originally."
        : "The document default FarEast language was set to another than Japanese language originally, so it is not overridden.");

Use WarningCallback para controlar problemas ao carregar um documento

Alguns documentos podem estar corrompidos, conter entradas inválidas ou ter recursos não suportados atualmente pelo Aspose.Words. Se você deseja saber sobre problemas ocorridos ao carregar um documento, Aspose.Words disponibiliza a interface IWarningCallback.

O exemplo de código a seguir mostra a implementação da interface IWarningCallback:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
public class DocumentLoadingWarningCallback : IWarningCallback
{
    public void Warning(WarningInfo info)
    {
        // Prints warnings and their details as they arise during document loading.
        Console.WriteLine($"WARNING: {info.WarningType}, source: {info.Source}");
        Console.WriteLine($"\tDescription: {info.Description}");
    }
}

Para obter informações sobre todos os problemas durante o tempo de carregamento, use a propriedade WarningCallback.

O exemplo de código a seguir mostra como usar essa propriedade:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
LoadOptions loadOptions = new LoadOptions { WarningCallback = new DocumentLoadingWarningCallback() };
            
Document doc = new Document(MyDir + "Document.docx", loadOptions);

Use ResourceLoadingCallback para controlar o carregamento de recursos externos

Um documento pode conter links externos para imagens localizadas em algum lugar de um disco local, rede ou Internet. Aspose.Words carrega automaticamente essas imagens em um documento, mas há situações em que esse processo precisa ser controlado. Por exemplo, para decidir se realmente precisamos carregar uma determinada imagem ou talvez ignorá-la. A opção de carregamento ResourceLoadingCallback permite controlar isso.

O exemplo de código a seguir mostra a implementação da interface IResourceLoadingCallback:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
private class HtmlLinkedResourceLoadingCallback : IResourceLoadingCallback
{
    public ResourceLoadingAction ResourceLoading(ResourceLoadingArgs args)
    {
        switch (args.ResourceType)
        {
            case ResourceType.CssStyleSheet:
            {
                Console.WriteLine($"External CSS Stylesheet found upon loading: {args.OriginalUri}");
 
                // CSS file will don't used in the document.
                return ResourceLoadingAction.Skip;
            }
            case ResourceType.Image:
            {
                // Replaces all images with a substitute.
                Image newImage = Image.FromFile(ImagesDir + "Logo.jpg");
                
                ImageConverter converter = new ImageConverter();
                byte[] imageBytes = (byte[])converter.ConvertTo(newImage, typeof(byte[]));

                args.SetData(imageBytes);
 
                // New images will be used instead of presented in the document.
                return ResourceLoadingAction.UserProvided;
            }
            case ResourceType.Document:
            {
                Console.WriteLine($"External document found upon loading: {args.OriginalUri}");
 
                // Will be used as usual.
                return ResourceLoadingAction.Default;
            }
            default:
                throw new InvalidOperationException("Unexpected ResourceType value.");
        }
    }
}

O exemplo de código a seguir mostra como usar a propriedade ResourceLoadingCallback:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
LoadOptions loadOptions = new LoadOptions { ResourceLoadingCallback = new HtmlLinkedResourceLoadingCallback() };

// When we open an Html document, external resources such as references to CSS stylesheet files
// and external images will be handled customarily by the loading callback as the document is loaded.
Document doc = new Document(MyDir + "Images.html", loadOptions);

doc.Save(ArtifactsDir + "WorkingWithLoadOptions.ResourceLoadingCallback.pdf");

Use TempFolder para evitar uma exceção de memória

Aspose.Words suporta documentos extremamente grandes que possuem milhares de páginas cheias de conteúdo rico. Carregar esses documentos pode exigir muita RAM. No processo de carregamento, o Aspose.Words precisa de ainda mais memória para armazenar estruturas temporárias usadas para analisar um documento.

Se você tiver um problema com a exceção de memória insuficiente ao carregar um documento, tente usar a propriedade TempFolder. Nesse caso, o Aspose.Words armazenará alguns dados em arquivos temporários em vez de na memória, e isso pode ajudar a evitar tal exceção.

O exemplo de código a seguir mostra como definir TempFolder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
LoadOptions loadOptions = new LoadOptions { TempFolder = ArtifactsDir };

Document doc = new Document(MyDir + "Document.docx", loadOptions);

Defina a codificação explicitamente

A maioria dos formatos de documentos modernos armazena seu conteúdo em Unicode e não requer tratamento especial. Por outro lado, ainda existem muitos documentos que usam alguma codificação pré-Unicode e, às vezes, perdem informações de codificação ou nem mesmo suportam a codificação de informações por natureza. Aspose.Words tenta detectar automaticamente a codificação apropriada por padrão, mas em casos raros você pode precisar usar uma codificação diferente daquela detectada pelo nosso algoritmo de reconhecimento de codificação. Neste caso, use a propriedade Encoding para obter ou definir a codificação.

O exemplo de código a seguir mostra como definir a codificação para substituir a codificação escolhida automaticamente:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
LoadOptions loadOptions = new LoadOptions { Encoding = Encoding.UTF7 };

Document doc = new Document(MyDir + "Encoded in UTF-7.txt", loadOptions);

Carregar documentos criptografados

Você pode carregar documentos do Word criptografados com uma senha. Para fazer isso, use uma sobrecarga de construtor especial, que aceita um objeto LoadOptions. Este objeto contém a propriedade Password, que especifica a string da senha.

O exemplo de código a seguir mostra como carregar um documento criptografado com senha:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document(MyDir + "Encrypted.docx", new LoadOptions("docPassword"));

Se você não souber antecipadamente se o arquivo está criptografado, poderá usar a classe FileFormatUtil, que fornece métodos utilitários para trabalhar com formatos de arquivo, como detectar o formato do arquivo ou converter extensões de arquivo de/para enumerações de formato de arquivo. Para detectar se o documento está criptografado e requer uma senha para abri-lo, use a propriedade IsEncrypted.

O exemplo de código a seguir mostra como verificar se o OpenDocument está criptografado ou não:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
FileFormatInfo info = FileFormatUtil.DetectFileFormat(MyDir + "Encrypted.odt");
Console.WriteLine(info.IsEncrypted);