Trabalhando com Documentos

Aspose.Words FOSS para .NET representa cada arquivo Word como um modelo de objeto em memória enraizado na classe Document, com DocumentBuilder fornecendo um API de alto nível baseado em cursor para autoria de conteúdo. Este guia cobre a criação e o carregamento de documentos, autoria com DocumentBuilder, a estrutura de seção/corpo, a navegação pela árvore de nós, a combinação de documentos e a proteção deles.

Criando e Carregando Documentos

Crie um documento em branco com new Document(), ou abra um arquivo existente passando um caminho ou Stream para o construtor Document(fileName) ou Document(stream). Sobrecargas que aceitam um argumento LoadOptions permitem controlar o comportamento de carregamento, como fornecer uma senha para um arquivo criptografado.

Antes de carregar um arquivo de uma fonte desconhecida ou não confiável, FileFormatUtil.DetectFileFormat(fileName) (ou a sobrecarga Stream) retorna um FileFormatInfo descrevendo o LoadFormat detectado, e se o arquivo IsEncrypted, HasDigitalSignature ou HasMacros.

Autoria com DocumentBuilder

DocumentBuilder envolve um Document e expõe um cursor que você move pelo documento enquanto insere conteúdo. Write(text) e Writeln(text) inserem texto no cursor; InsertParagraph() inicia um novo parágrafo. As propriedades de formatação no construtor — Font, ParagraphFormat, ListFormat, PageSetup — aplicam-se ao que for escrito a seguir.

Mova o cursor com MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) ou MoveToParagraph(paragraphIndex, characterIndex). As propriedades CurrentNode, CurrentParagraph e CurrentSection do construtor relatam sua posição atual na árvore.

Estrutura do Documento: Seções e Corpo

Um Document contém um SectionCollection (Document.Sections, mais FirstSection / LastSection); cada Section tem um Body, uma coleção opcional de cabeçalhos/rodapés e seu próprio PageSetup. Section.AppendContent(sourceSection) e PrependContent(sourceSection) copiam conteúdo entre seções, e ClearContent() reinicia uma seção sem removê-la do documento.

Dentro de um Body, o conteúdo é exposto através de Body.Paragraphs (um ParagraphCollection) e Body.Tables. Um Range — disponível a partir de Document, Section, Paragraph e outros nós — representa uma área contígua da árvore; Range.Text lê seu texto simples e Range.Replace(pattern, replacement) realiza uma busca-substituição apenas nessa área.

Percorrendo a Árvore de Nós com DocumentVisitor

Cada parte de um documento — seções, parágrafos, runs, tabelas, campos, formas, comentários, notas de rodapé — é um Node em uma árvore composta com raiz em Document. Para processar cada nó de um determinado tipo sem recursão manual, crie uma subclasse do DocumentVisitor abstrato e substitua os callbacks Visit*Start / Visit*End que precisar, como VisitParagraphStart(paragraph) ou VisitRun(run), então chame document.Accept(visitor). Cada callback pode retornar um VisitorAction (Continue, SkipThisNode ou Stop) para controlar como a travessia prossegue.

Clonagem, Importação e Anexação de Conteúdo

Document.Clone() produz uma cópia profunda de um documento inteiro. Para mover conteúdo entre duas instâncias diferentes de Document, chame ImportNode(srcNode, isImportChildren) no documento de destino para trazer um nó de uma árvore externa, ou chame Document.AppendDocument(srcDoc, importFormatMode) para anexar as seções de um documento a outro usando um ImportFormatMode escolhido — KeepSourceFormatting, UseDestinationStyles ou KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) insere o conteúdo de um documento fonte no cursor do construtor em vez de no final do destino.

Protegendo Documentos

Document.Protect(type, password) restringe a edição de acordo com um valor ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields ou NoProtection para remover a proteção. Unprotect() (com ou sem senha) reverte isso. Esta é uma restrição de edição aplicada pelo Word, separada da criptografia de senha OOXML que OoxmlSaveOptions.Password aplica ao salvar um arquivo.

Dicas e Melhores Práticas

Prefira DocumentBuilder para construir novo conteúdo; recorra à manipulação direta de nós (AppendChild, InsertAfter, Clone) quando precisar de controle fino sobre uma árvore existente.
Chame FileFormatUtil.DetectFileFormat antes de carregar um arquivo de uma fonte não confiável ou fornecida pelo usuário, para que você possa verificar LoadFormat e rejeitar entrada não suportada ou criptografada logo no início.
Ao combinar documentos com AppendDocument ou InsertDocument, escolha o ImportFormatMode deliberadamente — KeepSourceFormatting preserva a aparência da origem, UseDestinationStyles combina com o conjunto de estilos do documento de destino.
Use uma subclasse DocumentVisitor em vez de percorrer recursivamente a árvore manualmente quando precisar processar cada instância de um tipo de nó de forma consistente.
Document.Protect é uma restrição de edição, não criptografia — combine-a com OoxmlSaveOptions.Password se o próprio arquivo salvo precisar exigir uma senha para ser aberto.

Problemas Comuns

Problema	Causa	Correção
`Document(fileName)` lança um erro para um arquivo que abre bem no Word	O formato do arquivo não é suportado por esta edição para carregamento	Chame `FileFormatUtil.DetectFileFormat` primeiro e verifique o `LoadFormat` retornado antes de carregar
O conteúdo anexado adquire fontes ou estilos errados	Incompatibilidade de `ImportFormatMode` entre os conjuntos de estilos de origem e destino	Passe `KeepSourceFormatting` ou `UseDestinationStyles` explicitamente em vez de depender de um padrão
A travessia de `DocumentVisitor` interrompe cedo ou ignora conteúdo	Uma substituição de `VisitStart` / `VisitEnd` retorna `SkipThisNode` ou `Stop` involuntariamente	Retorne `VisitorAction.Continue` de cada substituição, a menos que você tenha a intenção específica de pular ou interromper
`Unprotect()` não tem efeito	O documento não foi protegido com uma senha, ou a senha fornecida está incorreta	Chame `Unprotect()` sem argumentos se `Protect` foi chamado sem senha, caso contrário passe a senha correspondente

FAQ

Qual é a diferença entre `Document.Clone()` e `ImportNode`?

Clone() copia um documento inteiro para uma nova instância de Document. ImportNode(srcNode, isImportChildren) traz um único nó (e opcionalmente seus filhos) da árvore de um documento para outro, que é o que você usa ao combinar conteúdo específico em vez de documentos inteiros.

Quais formatos de arquivo `Document(fileName)` pode carregar?

Document(fileName) carrega DOCX, DOCM, DOTX, DOTM, Flat OPC (incluindo suas variantes com macros e de modelo), Markdown e texto simples. Formatos antigos de processamento de texto e da web são excluídos dos carregadores desta edição.

Como descubro onde um `DocumentBuilder` está atualmente posicionado?

Leia CurrentNode, CurrentParagraph ou CurrentSection na instância do construtor.

O `Document.Protect` criptografa o arquivo salvo?

Não — é uma restrição de edição imposta pelo Word quando o arquivo é aberto. Para exigir uma senha apenas para abrir o arquivo, defina OoxmlSaveOptions.Password ao salvar.

Como faço para ler apenas os parágrafos no corpo de um documento?

Use a coleção Body.Paragraphs, ou Body.GetChildNodes(nodeType, isDeep) para outros tipos de nós.

API Reference Resumo

Classe/Método	Descrição
`Document`	Raiz do modelo de objeto de documento; os construtores carregam de um arquivo ou fluxo, ou criam um documento em branco.
`Document.Save`	Grava o documento em um arquivo, fluxo ou resposta HTTP em um formato escolhido.
`Document.Clone()`	Produz uma cópia profunda de todo o documento.
`Document.Protect(type, password)` / `Unprotect()`	Aplica ou remove uma restrição de edição.
`Document.AppendDocument(srcDoc, importFormatMode)`	Anexa as seções de outro documento a este.
`DocumentBuilder`	Baseado em cursor API para escrever texto e inserir conteúdo em um documento.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Insere o conteúdo de um documento fonte no cursor.
`Section` / `SectionCollection`	Uma única seção de um documento e a coleção de todas as seções.
`Body`	Contêiner para o texto principal (parágrafos e tabelas) de uma seção.
`Range`	Uma área contígua da árvore de documentos; suporta `Text` e `Replace`.
`DocumentVisitor`	Classe base abstrata para percorrer cada nó na árvore de documentos.
`ProtectionType`	Enum das restrições de edição ao nível do documento.
`FileFormatUtil.DetectFileFormat`	Detecta o formato de um arquivo ou fluxo antes de carregá-lo.

Ver também

Aspose.Words for .NET — Enterprise Documentation

Trabalhando com Documentos