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.
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 Node.node_type. 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.
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.
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 parent_node. Um nó não possui nó pai, ou seja, parent_node é None, 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 Nenhum.
Você pode remover um nó de seu pai chamando o método Node.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 first_child e last_child que retornam o primeiro e o último nós filhos, respectivamente. Se não houver nós filhos, essas propriedades retornarão None.
CompositeNode também fornece a coleção get_child_nodes permitindo acesso indexado ou enumerado aos nós filhos. O método get_child_nodes retorna 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 get_child_nodes é atualizada automaticamente.
Se um nó não tiver filho, o método get_child_nodes retornará uma coleção vazia. Você pode verificar se o CompositeNode contém algum nó filho usando a propriedade has_child_nodes.
O exemplo de código a seguir mostra como enumerar nós filhos imediatos de um CompositeNode usando o enumerador fornecido pela coleção get_child_nodes:
Nós irmãos
Você pode obter o nó que precede ou segue imediatamente um nó específico usando as propriedades previous_sibling e next_sibling, respectivamente. Se um nó for o último filho de seu pai, a propriedade next_sibling será None. Por outro lado, se o nó for o primeiro filho de seu pai, a propriedade previous_sibling será None.
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 primeiro_XXX e último_XXX digitadas. Por exemplo, o Document possui propriedades first_section e last_section. Da mesma forma, o Table possui propriedades como first_row, last_row 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.parent_paragraph, Paragraph.parent_section 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.parent_node e CompositeNode.first_child.
O exemplo de código a seguir mostra como usar propriedades digitadas para acessar nós da árvore de documentos: