Modelo de objetos de documento Aspose.Words (DOM)

El modelo de objetos de documento (DOM) Aspose.Words es una representación en memoria de un documento de Word. Aspose.Words DOM le permite leer, manipular y modificar mediante programación el contenido y el formato de un documento de Word.

Esta sección describe las principales clases del Aspose.Words DOM y sus relaciones. Al utilizar las clases Aspose.Words DOM, puede obtener acceso programático a los elementos y el formato del documento.

Crear un árbol de objetos Document

Cuando se lee un documento en Aspose.Words DOM, se crea un árbol de objetos y los diferentes tipos de elementos del documento fuente tienen sus propios objetos de árbol DOM con varias propiedades.

Construir árbol de nodos de documentos

Cuando Aspose.Words lee un documento de Word en la memoria, crea objetos de diferentes tipos que representan varios elementos del documento. Cada ejecución de un texto, párrafo, tabla o sección es un nodo, e incluso el documento en sí es un nodo. Aspose.Words define una clase para cada tipo de nodo de documento.

El árbol de documentos en Aspose.Words sigue el patrón de diseño compuesto:

  • Todas las clases de nodos derivan en última instancia de la clase Node, que es la clase base en el modelo de objetos de documento Aspose.Words.
  • Los nodos que pueden contener otros nodos, por ejemplo, Section o Paragraph, derivan de la clase CompositeNode, que a su vez deriva de la clase Node.

El diagrama que se proporciona a continuación muestra la herencia entre clases de nodos del modelo de objetos de documento (DOM) Aspose.Words. Los nombres de las clases abstractas están en cursiva.

aspose-palabras-dom

Veamos un ejemplo. La siguiente imagen muestra un documento Microsoft Word con diferentes tipos de contenido.

documento-ejemplo-aspose-palabras

Al leer el documento anterior en Aspose.Words DOM, se crea el árbol de objetos, como se muestra en el siguiente esquema.

dom-aspose-palabras

Document, Section, Paragraph, Table, Shape, Run y todas las demás elipses del diagrama son objetos Aspose.Words que representan elementos del documento de Word.

Obtenga un Node tipo

Aunque la clase Node es suficiente para distinguir diferentes nodos entre sí, Aspose.Words proporciona la enumeración NodeType para simplificar algunas tareas API, como seleccionar nodos de un tipo específico.

El tipo de cada nodo se puede obtener utilizando la propiedad NodeType. Esta propiedad devuelve un valor de enumeración NodeType. Por ejemplo, un nodo de párrafo representado por la clase Paragraph devuelve NodeType.Paragraph y un nodo de tabla representado por la clase Table devuelve NodeType.Table.

El siguiente ejemplo muestra cómo obtener un tipo de nodo utilizando la enumeración NodeType:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
// Returns NodeType.Document
NodeType type = doc.NodeType;

Navegación por el árbol de documentos

Aspose.Words representa un documento como un árbol de nodos, lo que le permite navegar entre nodos. Esta sección describe cómo explorar y navegar por el árbol de documentos en Aspose.Words.

Cuando abre el documento de muestra, presentado anteriormente, en el Explorador de documentos, el árbol de nodos aparece exactamente como está representado en Aspose.Words.

explorador de documentos en documentos

Relaciones de nodo de documento

Los nodos del árbol tienen relaciones entre ellos:

  • Un nodo que contiene otro nodo es un parent.
  • El nodo contenido en el nodo padre es un child.. Los nodos secundarios del mismo padre son nodos sibling.
  • El nodo root es siempre el nodo Document.

Los nodos que pueden contener otros nodos derivan de la clase CompositeNode y, en última instancia, todos los nodos derivan de la clase Node. Estas dos clases base proporcionan métodos y propiedades comunes para la navegación y modificación de la estructura de árbol.

El siguiente diagrama de objetos UML muestra varios nodos del documento de muestra y sus relaciones entre sí a través de las propiedades padre, hijo y hermano:

documentos-nodos-relaciones-aspose-palabras

El documento es propietario del nodo

Un nodo siempre pertenece a un documento en particular, incluso si acaba de crearse o eliminarse del árbol, porque las estructuras vitales de todo el documento, como estilos y listas, se almacenan en el nodo Document. Por ejemplo, no es posible tener un Paragraph sin un Document porque cada párrafo tiene asignado un estilo que se define globalmente para el documento. Esta regla se utiliza al crear nuevos nodos. Agregar un nuevo Paragraph directamente al DOM requiere pasar un objeto de documento al constructor.

Al crear un nuevo párrafo usando DocumentBuilder, el constructor siempre tiene una clase Document vinculada a través de la propiedad DocumentBuilder.Document.

El siguiente ejemplo de código muestra que al crear cualquier nodo, siempre se define un documento que será propietario del nodo:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Open a file from disk.
Document doc = new Document();
// Creating a new node of any type requires a document passed into the constructor.
Paragraph para = new Paragraph(doc);
// The new paragraph node does not yet have a parent.
Console.WriteLine("Paragraph has no parent node: " + (para.ParentNode == null));
// But the paragraph node knows its document.
Console.WriteLine("Both nodes' documents are the same: " + (para.Document == doc));
// The fact that a node always belongs to a document allows us to access and modify
// Properties that reference the document-wide data such as styles or lists.
para.ParagraphFormat.StyleName = "Heading 1";
// Now add the paragraph to the main text of the first section.
doc.FirstSection.Body.AppendChild(para);
// The paragraph node is now a child of the Body node.
Console.WriteLine("Paragraph has a parent node: " + (para.ParentNode != null));

Nodo principal

Cada nodo tiene un padre especificado por la propiedad ParentNode. Un nodo no tiene nodo padre, es decir, ParentNode es nulo, en los siguientes casos:

  • El nodo acaba de crearse y aún no se ha agregado al árbol.
  • El nodo ha sido eliminado del árbol.
  • Este es el nodo Document raíz que siempre tiene un nodo principal nulo.

Puede eliminar un nodo de su padre llamando al método Remove. El siguiente ejemplo de código muestra cómo acceder al nodo principal:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Create a new empty document. It has one section.
Document doc = new Document();
// The section is the first child node of the document.
Node section = doc.FirstChild;
// The section's parent node is the document.
Console.WriteLine("Section parent is the document: " + (doc == section.ParentNode));

Nodos secundarios

La forma más eficaz de acceder a los nodos secundarios de un CompositeNode es a través de las propiedades FirstChild y LastChild que devuelven el primer y último nodo secundario, respectivamente. Si no hay nodos secundarios, estas propiedades devuelven null.

CompositeNode también proporciona el método GetChildNodes que permite el acceso indexado o enumerado a los nodos secundarios. La propiedad ChildNodes es una colección activa de nodos, lo que significa que cada vez que se cambia el documento, como cuando se eliminan o agregan nodos, la colección ChildNodes se actualiza automáticamente.

Si un nodo no tiene hijos, la propiedad ChildNodes devuelve una colección vacía. Puede comprobar si el CompositeNode contiene nodos secundarios utilizando la propiedad HasChildNodes.

El siguiente ejemplo de código muestra cómo enumerar nodos secundarios inmediatos de un CompositeNode utilizando el enumerador proporcionado por la colección ChildNodes:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph paragraph = (Paragraph)doc.GetChild(NodeType.Paragraph, 0, true);
NodeCollection children = paragraph.ChildNodes;
foreach (Node child in children)
{
// Paragraph may contain children of various types such as runs, shapes and so on.
if (child.NodeType.Equals(NodeType.Run))
{
// Say we found the node that we want, do something useful.
Run run = (Run)child;
Console.WriteLine(run.Text);
}
}

El siguiente ejemplo de código muestra cómo enumerar nodos secundarios inmediatos de un CompositeNode mediante acceso indexado:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph paragraph = (Paragraph)doc.GetChild(NodeType.Paragraph, 0, true);
NodeCollection children = paragraph.ChildNodes;
for (int i = 0; i < children.Count; i++)
{
Node child = children[i];
// Paragraph may contain children of various types such as runs, shapes and so on.
if (child.NodeType.Equals(NodeType.Run))
{
// Say we found the node that we want, do something useful.
Run run = (Run)child;
Console.WriteLine(run.Text);
}
}

Nodos hermanos

Puede obtener el nodo que precede o sigue inmediatamente a un nodo en particular utilizando las propiedades PreviousSibling y NextSibling, respectivamente. Si un nodo es el último hijo de su padre, entonces la propiedad NextSibling es null. Por el contrario, si el nodo es el primer hijo de su padre, la propiedad PreviousSibling es null.

El siguiente ejemplo de código muestra cómo visitar de manera eficiente todos los nodos secundarios directos e indirectos de un nodo compuesto:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
public static void RecurseAllNodes()
{
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithNode();
// Open a document.
Document doc = new Document(dataDir + "Node.RecurseAllNodes.doc");
// Invoke the recursive function that will walk the tree.
TraverseAllNodes(doc);
}
/// <summary>
/// A simple function that will walk through all children of a specified node recursively
/// And print the type of each node to the screen.
/// </summary>
public static void TraverseAllNodes(CompositeNode parentNode)
{
// This is the most efficient way to loop through immediate children of a node.
for (Node childNode = parentNode.FirstChild; childNode != null; childNode = childNode.NextSibling)
{
// Do some useful work.
Console.WriteLine(Node.NodeTypeToString(childNode.NodeType));
// Recurse into the node if it is a composite node.
if (childNode.IsComposite)
TraverseAllNodes((CompositeNode)childNode);
}
}

Acceso escrito a nodos secundarios y principales

Hasta ahora, hemos analizado las propiedades que devuelven uno de los tipos base: Node o CompositeNode. Pero a veces hay situaciones en las que es posible que necesites convertir valores a una clase de nodo específica, como Run o Paragraph. Es decir, no se puede evitar por completo la conversión cuando se trabaja con Aspose.Words DOM, que es compuesto.

Para reducir la necesidad de conversión, la mayoría de las clases Aspose.Words proporcionan propiedades y colecciones que brindan acceso fuertemente tipado. Hay tres patrones básicos de acceso mecanografiado:

Las propiedades escritas son simplemente atajos útiles que a veces proporcionan un acceso más fácil que las propiedades genéricas heredadas de Node.ParentNode y CompositeNode.FirstChild.

El siguiente ejemplo de código muestra cómo utilizar propiedades escritas para acceder a los nodos del árbol del documento:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Section section = doc.FirstSection;
// Quick typed access to the Body child node of the Section.
Body body = section.Body;
// Quick typed access to all Table child nodes contained in the Body.
TableCollection tables = body.Tables;
foreach (Table table in tables)
{
// Quick typed access to the first row of the table.
if (table.FirstRow != null)
table.FirstRow.Remove();
// Quick typed access to the last row of the table.
if (table.LastRow != null)
table.LastRow.Remove();
}