Aspose.Words Document Object Model (DOM)

Aspose.Words Document Object Model (DOM) è una rappresentazione in memoria di un documento Word. Aspose.Words DOM consente di leggere, manipolare e modificare a livello di codice il contenuto e la formattazione di un documento Word.

Questa sezione descrive le principali classi del Aspose.Words DOM e le loro relazioni. Utilizzando le classi DOM Aspose.Words, è possibile ottenere l’accesso a livello di codice agli elementi e alla formattazione del documento.

Crea un albero di oggetti Document

Quando un documento viene letto nel Aspose.Words DOM, viene creato un albero di oggetti e diversi tipi di elementi del documento di origine hanno i propri oggetti dell’albero DOM con varie proprietà.

Costruisci l’albero dei nodi del documento

Quando Aspose.Words legge un documento Word in memoria, crea oggetti di diverso tipo che rappresentano vari elementi del documento. Ogni sequenza di un testo, paragrafo, tabella o sezione è un nodo e anche il documento stesso è un nodo. Aspose.Words definisce una classe per ogni tipo di nodo del documento.

L’albero del documento in Aspose.Words segue il Composite Design Pattern:

  • Tutte le classi dei nodi derivano in definitiva dalla classe Node, che è la classe base nell’Document Object Model Aspose.Words.
  • I nodi che possono contenere altri nodi, ad esempio Section o Paragraph, derivano dalla classe CompositeNode, che a sua volta deriva dalla classe Node.

Il diagramma fornito di seguito mostra l’ereditarietà tra le classi di nodi del Aspose.Words Document Object Model (DOM). I nomi delle classi astratte sono in corsivo.

aspose-parole-dom

Diamo un’occhiata a un esempio. L’immagine seguente mostra un documento Microsoft Word con diversi tipi di contenuto.

documento-esempio-aspose-parole

Durante la lettura del documento di cui sopra nel Aspose.Words DOM, viene creato l’albero degli oggetti, come mostrato nello schema seguente.

dom-aspose-parole

Document, Section, Paragraph, Table, Shape, Run e tutte le altre ellissi nel diagramma sono oggetti Aspose.Words che rappresentano elementi del documento Word.

Ottieni un file {#get-a-node-type} di tipo Node

Sebbene la classe Node sia sufficiente per distinguere diversi nodi tra loro, Aspose.Words fornisce l’enumerazione NodeType per semplificare alcune attività API, come la selezione di nodi di un tipo specifico.

Il tipo di ciascun nodo può essere ottenuto utilizzando la proprietà Node.node_type. Questa proprietà restituisce un valore di enumerazione NodeType. Ad esempio, un nodo di paragrafo rappresentato dalla classe Paragraph restituisce NodeType.PARAGRAPH e un nodo di tabella rappresentato dalla classe Table restituisce NodeType.TABLE.

L’esempio seguente mostra come ottenere un tipo di nodo utilizzando l’enumerazione NodeType:

Navigazione nell’albero dei documenti

Aspose.Words rappresenta un documento come un albero di nodi, che consente di navigare tra i nodi. Questa sezione descrive come esplorare e navigare nell’albero del documento in Aspose.Words.

Quando si apre il documento di esempio, presentato in precedenza, in Document Explorer, la struttura dei nodi appare esattamente come rappresentata in Aspose.Words.

esploratore di documenti in documenti

Relazioni tra nodi documento

I nodi nell’albero hanno relazioni tra loro:

  • Un nodo che contiene un altro nodo è un parent.
  • Il nodo contenuto nel nodo genitore è un child.. I nodi figli dello stesso genitore sono nodi sibling.
  • Il nodo root è sempre il nodo Document.

I nodi che possono contenere altri nodi derivano dalla classe CompositeNode e tutti i nodi derivano infine dalla classe Node. Queste due classi base forniscono metodi e proprietà comuni per la navigazione e la modifica della struttura ad albero.

Il seguente diagramma dell’oggetto UML mostra diversi nodi del documento di esempio e le loro relazioni reciproche tramite le proprietà parent, child e sibling:

documento-nodi-relazioni-aspose-parole

Il documento è proprietario del nodo

Un nodo appartiene sempre a un particolare documento, anche se è stato appena creato o rimosso dall’albero, perché strutture vitali a livello di documento come stili ed elenchi sono archiviate nel nodo Document. Ad esempio, non è possibile avere un Paragraph senza un Document perché a ogni paragrafo è assegnato uno stile definito globalmente per il documento. Questa regola viene utilizzata durante la creazione di nuovi nodi. L’aggiunta di un nuovo Paragraph direttamente all’DOM richiede un oggetto documento passato al costruttore.

Quando si crea un nuovo paragrafo utilizzando DocumentBuilder, il builder ha sempre una classe Document collegata ad esso tramite la proprietà DocumentBuilder.document.

Il seguente esempio di codice mostra che durante la creazione di qualsiasi nodo, viene sempre definito un documento che sarà proprietario del nodo:

Nodo genitore

Ogni nodo ha un genitore specificato dalla proprietà parent_node. Un nodo non ha un nodo genitore, ovvero parent_node è None, nei seguenti casi:

  • Il nodo è stato appena creato e non è stato ancora aggiunto all’albero.
  • Il nodo è stato rimosso dall’albero.
  • Questo è il nodo root Document che ha sempre un nodo genitore Nessuno.

Puoi rimuovere un nodo dal suo genitore chiamando il metodo Node.remove. Il seguente esempio di codice mostra come accedere al nodo genitore:

Nodi figli

Il modo più efficiente per accedere ai nodi figlio di un CompositeNode è tramite le proprietà first_child e last_child che restituiscono rispettivamente il primo e l’ultimo nodo figlio. Se non sono presenti nodi figlio, queste proprietà restituiscono None.

CompositeNode fornisce anche la raccolta get_child_nodes che consente l’accesso indicizzato o enumerato ai nodi figlio. Il metodo get_child_nodes restituisce una raccolta live di nodi, il che significa che ogni volta che il documento viene modificato, ad esempio quando i nodi vengono rimossi o aggiunti, la raccolta get_child_nodes viene aggiornata automaticamente.

Se un nodo non ha figli, il metodo get_child_nodes restituisce una raccolta vuota. Puoi verificare se il CompositeNode contiene nodi figlio utilizzando la proprietà has_child_nodes.

L’esempio di codice seguente mostra come enumerare i nodi figlio immediati di un CompositeNode utilizzando l’enumeratore fornito dalla raccolta get_child_nodes:

Nodi fratelli

È possibile ottenere il nodo che precede o segue immediatamente un nodo particolare utilizzando rispettivamente le proprietà previous_sibling e next_sibling. Se un nodo è l’ultimo figlio del suo genitore, la proprietà next_sibling è None. Al contrario, se il nodo è il primo figlio del suo genitore, la proprietà previous_sibling è None.

Il seguente esempio di codice mostra come visitare in modo efficiente tutti i nodi figlio diretti e indiretti di un nodo composito:

Accesso digitato ai nodi figlio e padre

Finora abbiamo discusso delle proprietà che restituiscono uno dei tipi base: Node o CompositeNode. Ma a volte ci sono situazioni in cui potresti dover trasmettere valori a una classe di nodo specifica, come Run o Paragraph. Cioè, non puoi allontanarti completamente dal casting quando lavori con Aspose.Words DOM, che è composito.

Per ridurre la necessità di cast, la maggior parte delle classi Aspose.Words fornisce proprietà e raccolte che forniscono accesso fortemente tipizzato. Esistono tre modelli base di accesso digitato:

-Un nodo padre espone le proprietà primo_XXX e ultimo_XXX digitate. Ad esempio, l'Document ha proprietà first_section e last_section. Allo stesso modo, Table ha proprietà come first_row, last_row e altre.

Le proprietà tipizzate sono semplicemente scorciatoie utili che a volte forniscono un accesso più semplice rispetto alle proprietà generiche ereditate da Node.parent_node e CompositeNode.first_child.

Il seguente esempio di codice mostra come utilizzare le proprietà tipizzate per accedere ai nodi dell’albero del documento: