Aspose.Words Document Object Model (DOM)

O Aspose.Words Document Object Model (DOM) é uma representação na memória de um documento do Word. O Aspose.Words DOM permite ler, manipular e modificar programaticamente o conteúdo e a formatação de um documento do Word.

Esta seção descreve as principais classes do Aspose.Words DOM e seus relacionamentos. Ao usar as classes Aspose.Words DOM, você pode obter acesso programático aos elementos e formatação do documento.

Crie uma árvore de objetos Document

Quando um documento é lido no Aspose.Words DOM, uma árvore de objetos é construída e diferentes tipos de elementos do documento de origem têm seus próprios objetos de árvore DOM com várias propriedades.

Construir árvore de nós de documento

Quando o Aspose.Words lê um documento do Word na memória, ele cria objetos de diferentes tipos que representam vários elementos do documento. Cada execução de um texto, parágrafo, tabela ou seção é um nó, e até mesmo o próprio documento é um nó. Aspose.Words define uma classe para cada tipo de nó de documento.

A árvore de documentos em Aspose.Words segue o Composite Design Pattern:

• Todas as classes de nós derivam, em última análise, da classe Node, que é a classe base no Document Object Model Aspose.Words.
• Nós que podem conter outros nós, por exemplo, Section ou Paragraph, derivam da classe CompositeNode, que por sua vez deriva da classe Node.

O diagrama fornecido abaixo mostra a herança entre classes de nós do Aspose.Words Document Object Model (DOM). Os nomes das classes abstratas estão em itálico.

O Aspose.Words DOM também contém classes que não são de nós, como Style ou Font, que são usadas para personalizar a aparência e os estilos de um documento. Essas classes não são mostradas neste diagrama porque não são herdadas da classe Node.

Vejamos um exemplo. A imagem a seguir mostra um documento Microsoft Word com diferentes tipos de conteúdo.

Ao ler o documento acima no Aspose.Words DOM, é criada a árvore de objetos, conforme esquema abaixo.

Document, Section, Paragraph, Table, Shape, Run e todas as outras elipses no diagrama são objetos Aspose.Words que representam elementos do documento do Word.

Obtenha um Node tipo

Embora a classe Node seja suficiente para distinguir nós diferentes entre si, o Aspose.Words fornece a enumeração NodeType para simplificar algumas tarefas API, como selecionar nós de um tipo específico.

O tipo de cada nó pode ser obtido utilizando a propriedade NodeType. Esta propriedade retorna um valor de enumeração NodeType. Por exemplo, um nó de parágrafo representado pela classe Paragraph retorna NodeType.Paragraph e um nó de tabela representado pela classe Table retorna NodeType.Table.

O exemplo a seguir mostra como obter um tipo de nó usando a enumeração NodeType:

Navegação na árvore de documentos

Aspose.Words representa um documento como uma árvore de nós, que permite navegar entre os nós. Esta seção descreve como explorar e navegar na árvore de documentos em Aspose.Words.

Ao abrir o documento de amostra, apresentado anteriormente, no Document Explorer, a árvore de nós aparece exatamente como é representada em Aspose.Words.

Você pode aprender o projeto de amostra “Document Explorer” no Aspose.Words GitHub.

Relacionamentos de nós de documento

Os nós da árvore possuem relacionamentos entre eles:

• Um nó contendo outro nó é um parent.
• O nó contido no nó pai é um child. Os nós filhos do mesmo pai são nós sibling.
• O nó root é sempre o nó Document.

Os nós que podem conter outros nós derivam da classe CompositeNode e todos os nós derivam, em última análise, da classe Node. Essas duas classes base fornecem métodos e propriedades comuns para navegação e modificação da estrutura em árvore.

O diagrama de objetos UML a seguir mostra vários nós do documento de amostra e suas relações entre si por meio das propriedades pai, filho e irmão:

O documento é o proprietário do nó

Um nó sempre pertence a um documento específico, mesmo que tenha acabado de ser criado ou removido da árvore, porque estruturas vitais para todo o documento, como estilos e listas, são armazenadas no nó Document. Por exemplo, não é possível ter um Paragraph sem Document porque cada parágrafo possui um estilo atribuído que é definido globalmente para o documento. Esta regra é usada ao criar novos nós. Adicionar um novo Paragraph diretamente ao DOM requer um objeto de documento passado ao construtor.

A propriedade Node.Document retorna o documento ao qual o nó pertence.

Ao criar um novo parágrafo utilizando DocumentBuilder, o construtor sempre possui uma classe Document vinculada a ele através da propriedade DocumentBuilder.Document.

O exemplo de código a seguir mostra que ao criar qualquer nó, um documento que será o proprietário do nó é sempre definido:

Nó pai

Cada nó possui um pai especificado pela propriedade ParentNode. Um nó não possui nó pai, ou seja, ParentNode é nulo, nos seguintes casos:

• O nó acabou de ser criado e ainda não foi adicionado à árvore.
• O nó foi removido da árvore.
• Este é o nó Document raiz que sempre possui um nó pai nulo.

Você pode remover um nó de seu pai chamando o método Remove. O exemplo de código a seguir mostra como acessar o nó pai:

Nós filhos

A maneira mais eficiente de acessar os nós filhos de um CompositeNode é por meio das propriedades FirstChild e LastChild que retornam o primeiro e o último nós filhos, respectivamente. Se não houver nós filhos, essas propriedades retornarão null.

CompositeNode também fornece o método GetChildNodes permitindo acesso indexado ou enumerado aos nós filhos. A propriedade ChildNodes é uma coleção ativa de nós, o que significa que sempre que o documento é alterado, como quando nós são removidos ou adicionados, a coleção ChildNodes é atualizada automaticamente.

Se um nó não tiver filho, a propriedade ChildNodes retornará uma coleção vazia. Você pode verificar se o CompositeNode contém algum nó filho usando a propriedade HasChildNodes.

O exemplo de código a seguir mostra como enumerar nós filhos imediatos de um CompositeNode usando o enumerador fornecido pela coleção ChildNodes:

O exemplo de código a seguir mostra como enumerar nós filhos imediatos de um CompositeNode usando acesso indexado:

Nós irmãos

Você pode obter o nó que precede ou segue imediatamente um nó específico usando as propriedades PreviousSibling e NextSibling, respectivamente. Se um nó for o último filho de seu pai, a propriedade NextSibling será null. Por outro lado, se o nó for o primeiro filho de seu pai, a propriedade PreviousSibling será null.

O exemplo de código a seguir mostra como visitar com eficiência todos os nós filhos diretos e indiretos de um nó composto:

Acesso digitado a nós filho e pai

Até agora, discutimos as propriedades que retornam um dos tipos base – Node ou CompositeNode. Mas às vezes há situações em que pode ser necessário converter valores para uma classe de nó específica, como Run ou Paragraph. Ou seja, você não pode fugir completamente da transmissão ao trabalhar com o Aspose.Words DOM, que é composto.

Para reduzir a necessidade de conversão, a maioria das classes Aspose.Words fornece propriedades e coleções que fornecem acesso fortemente digitado. Existem três padrões básicos de acesso digitado:

• Um nó pai expõe propriedades FirstXXX e LastXXX digitadas. Por exemplo, o Document possui propriedades FirstSection e LastSection. Da mesma forma, o Table possui propriedades como FirstRow, LastRow e outras.
• Um nó pai expõe uma coleção digitada de nós filhos, como Document.Sections, Body.Paragraphs e outros.
• Um nó filho fornece acesso digitado ao seu pai, como Run.ParentParagraph, Paragraph.ParentSection e outros.

Propriedades digitadas são apenas atalhos úteis que às vezes fornecem acesso mais fácil do que propriedades genéricas herdadas de Node.ParentNode e CompositeNode.FirstChild.

O exemplo de código a seguir mostra como usar propriedades digitadas para acessar nós da árvore de documentos: