Como trabalhar com documentos em .NET
Este guia mostra como trabalhar com o modelo de objeto Document em Aspose.Words FOSS para .NET: criar um documento em branco, carregar um existente com segurança, percorrer sua estrutura de seção/corpo, combinar documentos e aplicar uma restrição de edição. Aspose.Words FOSS para .NET está disponível via NuGet ou compilando a partir do código-fonte.
Guia Passo a Passo
Etapa 1: Obter a Biblioteca
Clone o repositório e compile Aspose.Words.sln na configuração Release, então adicione uma referência de projeto a Aspose.Words.csproj do seu próprio projeto .NET. Os comandos completos de clonagem e compilação estão no guia de Instalação. Depois de referenciado, adicione using Aspose.Words; no topo de qualquer arquivo que trabalhe com documentos.
Etapa 2: Criar ou Carregar um Documento
Chame new Document() para um documento em branco, ou passe um caminho de arquivo ou Stream ao construtor Document(fileName) / Document(stream) para abrir um existente. Uma sobrecarga que aceita um argumento LoadOptions permite fornecer uma senha para um arquivo criptografado. Antes de carregar um arquivo cujo formato você ainda não confia, chame FileFormatUtil.DetectFileFormat(fileName) — ele retorna um FileFormatInfo que relata o LoadFormat detectado e se o arquivo IsEncrypted, HasDigitalSignature ou HasMacros, para que você possa rejeitar entradas inesperadas antes que Document tente analisá-lo.
Etapa 3: Criar Conteúdo com DocumentBuilder
DocumentBuilder envolve um Document com um cursor que você move pela árvore enquanto insere conteúdo. Write(text) e Writeln(text) inserem texto no cursor, e InsertParagraph() inicia um novo parágrafo. A formatação definida nas propriedades Font, ParagraphFormat, ListFormat e PageSetup do construtor se aplica ao que você escrever a seguir. Reposicione o cursor com MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) ou MoveToParagraph(paragraphIndex, characterIndex), e leia CurrentNode / CurrentParagraph / CurrentSection para confirmar onde o construtor está posicionado.
Etapa 4: Inspecionar a Estrutura da Seção e do Corpo
Um Document expõe um SectionCollection através de Document.Sections (mais FirstSection / LastSection). Cada Section tem exatamente um Body, cujo conteúdo principal é acessível através de Body.Paragraphs (um ParagraphCollection) e Body.Tables. Para ler ou buscar texto sem percorrer nós manualmente, use o Range disponível em Document, Section, Paragraph e outros nós — Range.Text devolve seu texto puro, e Range.Replace(pattern, replacement) executa uma busca e substituição limitada apenas a esse intervalo.
Etapa 5: Combinar Dois Documentos
Para copiar um documento inteiro, chame Document.Clone(). Para trazer conteúdo específico de uma instância Document para outra, chame ImportNode(srcNode, isImportChildren) no documento de destino, ou chame Document.AppendDocument(srcDoc, importFormatMode) para anexar cada seção de um documento fonte ao final do atual. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) faz o mesmo, mas insere no cursor do construtor em vez de no final. Nos três casos, escolha o valor ImportFormatMode — KeepSourceFormatting, UseDestinationStyles ou KeepDifferentStyles — deliberadamente, pois ele decide quais estilos do documento prevalecem onde os dois colidem.
Etapa 6: Aplicar uma Restrição de Edição
Chame Document.Protect(type, password) com um valor ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions ou AllowOnlyFormFields — para restringir quais edições o Word aceita para o documento. Unprotect() (com ou sem a senha correspondente) remove a restrição. Isso afeta apenas a edição dentro do Word; não criptografa o arquivo salvo. Para exigir uma senha apenas para abrir o arquivo, defina OoxmlSaveOptions.Password ao salvar.
Problemas Comuns e Soluções
Document(fileName) lança uma exceção para um arquivo que abre normalmente no Word. O formato do arquivo não é suportado pelos carregadores desta edição. Chame FileFormatUtil.DetectFileFormat(fileName) primeiro e verifique o retornado LoadFormat antes de tentar carregar.
O conteúdo copiado entre documentos adquire fontes ou estilos incorretos. O ImportFormatMode passado para AppendDocument or InsertDocument não corresponde ao que você esperava. Passe KeepSourceFormatting or UseDestinationStyles explicitamente em vez de depender de um padrão.
Unprotect() parece não ter efeito. Ou o documento não foi protegido com uma senha (chame Unprotect() sem argumentos), ou a senha fornecida não corresponde à que Protect() foi chamada com.
Formatação aplicada através de DocumentBuilder não aparece onde esperado. Formatação ao nível do Builder (Font, ParagraphFormat) só se aplica ao conteúdo escrito after quando está definido. Mova o cursor e defina a formatação antes de chamar Write/Writeln, não depois.
Perguntas Frequentes
Como criar um novo documento Word vazio?
Chame new Document(). Envolva-o com um DocumentBuilder para começar a inserir conteúdo imediatamente.
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 para combinar conteúdo específico em vez de documentos inteiros.
Como posso verificar com segurança o formato de um arquivo antes de carregá-lo?
Chame FileFormatUtil.DetectFileFormat(fileName) (ou a sobrecarga Stream) e inspecione as propriedades LoadFormat, IsEncrypted, HasDigitalSignature e HasMacros do FileFormatInfo retornado antes de passar o arquivo para Document.
Como ler apenas os parágrafos dentro do corpo de um documento?
Use a coleção Body.Paragraphs no Body da seção, ou Body.GetChildNodes(nodeType, isDeep) para outros tipos de nós.
O Document.Protect criptografa o arquivo salvo?
Não — é uma restrição de edição que o Word impõe quando o arquivo é aberto. Para exigir uma senha para abrir o próprio arquivo, defina OoxmlSaveOptions.Password ao chamar Document.Save.
