Salvando e Exportando Documentos

Salvando e Exportando Documentos

Document.Save grava um documento em um arquivo ou fluxo em um formato-alvo. O formato pode ser deduzido a partir da extensão do arquivo, especificado explicitamente como um valor SaveFormat, ou controlado por uma subclasse SaveOptions — OoxmlSaveOptions, MarkdownSaveOptions ou TxtSaveOptions — para ajuste específico ao tipo. Este guia aborda as sobrecargas Save, o enum SaveFormat, opções de salvamento OOXML, exportação para Markdown e texto simples, além da detecção de um formato antes da conversão.

Salvando com Document.Save

A chamada mais simples, Document.Save(fileName), deduz o formato-alvo a partir da extensão do arquivo. Save(fileName, saveFormat) define o formato explicitamente, independentemente da extensão, e Save(fileName, saveOptions) (ou as sobrecargas correspondentes Stream) aceita uma subclasse SaveOptions para configurações específicas ao formato. SaveOptions.CreateSaveOptions(saveFormat) é uma fábrica estática que devolve a subclasse de opções correta para um determinado SaveFormat, já com seus valores padrão configurados.

Escolhendo um Formato com SaveFormat

O enum SaveFormat enumera todos os identificadores de formatos de salvamento reconhecidos pela biblioteca. Document.Save grava integralmente tanto para quanto a partir dos formatos de documento principais desta edição — DOCX, DOCM, DOTX, DOTM e Flat OPC (incluindo suas variantes com macros e de modelo) — além de Markdown e texto simples. FileFormatUtil.SaveFormatToExtension(saveFormat) e ExtensionToSaveFormat(extension) convertem entre o enum e uma string de extensão de arquivo.

Alguns valores de SaveFormat estão presentes no enum para garantir a completude de API, mas correspondem a formatos que esta edição reduzida e de código aberto não implementa nem leitor nem gravador funcional — tentar salvar em um desses gera um resultado que não equivale ao documento original. Use apenas os formatos citados acima para garantir uma conversão confiável.

Opções OOXML: DOCX, DOCM, DOTX, DOTM e Flat OPC

OoxmlSaveOptions configura a gravação em qualquer um dos formatos Open XML. Sua propriedade SaveFormat define qual variante específica será escrita; Password define uma senha de abertura para o arquivo salvo (independente das restrições de edição de Document.Protect); Compliance escolhe o nível de rigor do OOXML; e CompressionLevel / Zip64Mode controlam o empacotamento ZIP subjacente. Crie um com new OoxmlSaveOptions(saveFormat) ou via SaveOptions.CreateSaveOptions(saveFormat).

Exportando para Markdown

MarkdownSaveOptions controla a exportação para Markdown: ListExportMode e LinkExportMode definem como listas e hyperlinks são renderizados, ImagesFolder / ImagesFolderAlias determinam onde as imagens extraídas são gravadas e como são referenciadas, ExportImagesAsBase64 as incorpora em linha, e TableContentAlignment influencia a marcação de tabelas gerada. Passe uma instância de MarkdownSaveOptions para Document.Save(fileName, saveOptions) com um nome de arquivo .md, ou configure seu SaveFormat explicitamente.

Exportando para Texto Simples

TxtSaveOptions (por meio de seu TxtSaveOptionsBase base, compartilhado com MarkdownSaveOptions) controla a exportação de texto simples: Encoding define a codificação de caracteres, ParagraphBreak define a sequência de terminação de linha, MaxCharactersPerLine quebra linhas longas, SimplifyListLabels normaliza marcadores/números de listas para caracteres simples, e PreserveTableLayout tenta manter as colunas das tabelas alinhadas usando espaços.

Detectando um Formato Antes de Converter

Antes de converter um arquivo cujo formato você ainda não conhece, FileFormatUtil.DetectFileFormat(fileName) devolve um FileFormatInfo contendo o LoadFormat detectado. Combine isso com FileFormatUtil.LoadFormatToSaveFormat(loadFormat) para decidir se é viável fazer um percurso completo pelos formatos suportados nesta edição antes de tentar Document.Save.

Dicas e Melhores Práticas

• Use Save(fileName, saveOptions) em vez da sobrecarga simples Save(fileName, saveFormat) sempre que precisar controlar o comportamento específico de formato, como renderização de listas Markdown ou compressão OOXML.
• Defina OoxmlSaveOptions.Password para um arquivo protegido por senha aberta; isso é separado de Document.Protect, que restringe a edição mas não criptografa o arquivo.
• Escolha MarkdownSaveOptions.ExportImagesAsBase64 para um único arquivo Markdown autônomo, ou ImagesFolder quando desejar uma pasta com arquivos de imagem extraídos ao lado do Markdown.
• Chame SaveOptions.CreateSaveOptions(saveFormat) em vez de selecionar manualmente a classe de opções concreta quando o formato de destino é determinado em tempo de execução.
• Verifique um formato de destino com FileFormatUtil antes da conversão, em vez de confiar apenas na extensão do arquivo, que pode estar errada ou ser enganosa.

Problemas Comuns

FAQ

Como salvo um documento em um formato específico independentemente da sua extensão de arquivo?

Chame Save(fileName, saveFormat) com um valor SaveFormat explícito, ou Save(fileName, saveOptions) com uma subclasse SaveOptions correspondente.

Quais formatos esta edição lê e grava em ambas as direções?

DOCX, DOCM, DOTX, DOTM, Flat OPC (com suas variantes habilitadas para macro e de modelo), Markdown e texto simples.

Como protejo um arquivo salvo com senha?

Defina Password em uma instância OoxmlSaveOptions e passe-a para Document.Save(fileName, saveOptions).

Como controlo as terminações de linha em um arquivo de texto exportado?

Defina ParagraphBreak em uma instância TxtSaveOptions antes de salvar.

Como verifico qual é o formato de um arquivo antes de convertê-lo?

Chame FileFormatUtil.DetectFileFormat(fileName) e leia o FileFormatInfo.LoadFormat retornado.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation