Aspose.Words Modèle d'objet de document (DOM)
Le Aspose.Words Modèle d’objet de document (DOM) est une représentation en mémoire d’un document Word. Le DOM Aspose.Words vous permet de lire, manipuler et modifier par programmation le contenu et la mise en forme d’un document Word.
Cette section décrit les principales classes du DOM Aspose.Words et leurs relations. En utilisant les classes DOM Aspose.Words, vous pouvez obtenir un accès par programmation aux éléments et à la mise en forme du document.
Créer une Arborescence d’Objets de Document
Lorsqu’un document est lu dans le DOM Aspose.Words, une arborescence d’objets est construite et différents types d’éléments du document source ont leurs propres objets d’arborescence DOM avec diverses propriétés.
Construire l’Arborescence des Nœuds de Document
Lorsque Aspose.Words lit un document Word en mémoire, il crée des objets de différents types qui représentent divers éléments du document. Chaque série de texte, paragraphe, tableau ou section est un nœud, et même le document lui-même est un nœud. Aspose.Words définit une classe pour chaque type de nœud de document.
L’arborescence du document dans Aspose.Words suit le modèle de conception composite:
- Toutes les classes de nœuds dérivent finalement de la classe Node, qui est la classe de base du modèle d’objet de document Aspose.Words.
- Les nœuds qui peuvent contenir d’autres nœuds, par exemple Section ou Paragraph, dérivent de la classe CompositeNode, qui à son tour dérive de la classe Node.
Le diagramme fourni ci-dessous montre l’héritage entre les classes de nœuds du Aspose.Words Document Object Model (DOM). Les noms des classes abstraites sont en italique.
Node
.
Regardons un exemple. L’image suivante montre un document Microsoft Word avec différents types de contenu.
Lors de la lecture du document ci-dessus dans le DOM Aspose.Words, l’arborescence des objets est créée, comme indiqué dans le schéma ci-dessous.
Document, Section, Paragraph, Table, Shape, Run, et toutes les autres ellipses du diagramme sont Aspose.Words objets qui représentent des éléments du document Word.
Obtenez un Node
de type
Bien que la classe Node soit suffisante pour distinguer différents nœuds les uns des autres, Aspose.Words fournit l’énumération NodeType pour simplifier certaines tâches de l’API, telles que la sélection de nœuds d’un type spécifique.
Le type de chaque nœud peut être obtenu à l’aide de la propriété NodeType. Cette propriété renvoie un NodeType enumeration value. For example, a paragraph node represented by the Paragraph class returns NodeType.Paragraph et un nœud de table représenté par le Table class returns NodeType.Table.
L’exemple suivant montre comment obtenir un type de nœud à l’aide de l’énumération NodeType:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
// Returns NodeType.Document | |
NodeType type = doc->get_NodeType(); |
Navigation dans l’Arborescence des Documents
Aspose.Words représente un document sous la forme d’une arborescence de nœuds, ce qui vous permet de naviguer entre les nœuds. Cette section décrit comment explorer et naviguer dans l’arborescence du document dans Aspose.Words.
Lorsque vous ouvrez l’exemple de document, présenté précédemment, dans l’Explorateur de documents, l’arborescence des nœuds apparaît exactement telle qu’elle est représentée dans Aspose.Words.
Relations de nœud de document
Les nœuds de l’arbre ont des relations entre eux:
- Un nœud contenant un autre nœud est un parent.
- Le nœud contenu dans le nœud parent est un child. Les nœuds enfants du même parent sont des nœuds sibling.
- Le nœud root est toujours le nœud Document.
Les nœuds qui peuvent contenir d’autres nœuds dérivent de la classe CompositeNode, et tous les nœuds dérivent finalement de la classe Node. Ces deux classes de base fournissent des méthodes et des propriétés communes pour la navigation et la modification de la structure arborescente.
Le diagramme d’objet UML suivant montre plusieurs nœuds de l’exemple de document et leurs relations les uns avec les autres via les propriétés parent, child et sibling:
Le Document est le propriétaire du nœud
Un nœud appartient toujours à un document particulier, même s’il vient d’être créé ou supprimé de l’arborescence, car des structures vitales à l’échelle du document telles que des styles et des listes sont stockées dans le nœud Document. Par exemple, il n’est pas possible d’avoir un Paragraph sans Document car chaque paragraphe a un style attribué qui est défini globalement pour le document. Cette règle est utilisée lors de la création de nouveaux nœuds. L’ajout d’un nouveau Paragraph directement au DOM nécessite un objet document transmis au constructeur.
Lors de la création d’un nouveau paragraphe à l’aide de DocumentBuilder, le générateur a toujours une classe Document qui lui est liée via la propriété DocumentBuilder.Document.
L’exemple de code suivant montre que lors de la création d’un nœud, un document qui possédera le nœud est toujours défini:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
// Open a file from disk. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
// Creating a new node of any type requires a document passed into the constructor. | |
System::SharedPtr<Paragraph> para = System::MakeObject<Paragraph>(doc); | |
// The new paragraph node does not yet have a parent. | |
std::cout << "Paragraph has no parent node: " << System::ObjectExt::Box<bool>((para->get_ParentNode() == nullptr))->ToString().ToUtf8String() << std::endl; | |
// But the paragraph node knows its document. | |
std::cout << "Both nodes' documents are the same: " << System::ObjectExt::Box<bool>((para->get_Document() == doc))->ToString().ToUtf8String() << std::endl; | |
// 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->get_ParagraphFormat()->set_StyleName(u"Heading 1"); | |
// Now add the paragraph to the main text of the first section. | |
doc->get_FirstSection()->get_Body()->AppendChild(para); | |
// The paragraph node is now a child of the Body node. | |
std::cout << "Paragraph has a parent node: " << System::ObjectExt::Box<bool>((para->get_ParentNode() != nullptr))->ToString().ToUtf8String() << std::endl; |
Nœud Parent
Chaque nœud a un parent spécifié par la propriété ParentNode. Un nœud n’a pas de nœud parent, c’est-à-dire que ParentNode est null, dans les cas suivants:
- Le nœud vient d’être créé et n’a pas encore été ajouté à l’arborescence.
- Le nœud a été supprimé de l’arborescence.
- C’est le nœud racine Document qui a toujours un nœud parent nul.
Vous pouvez supprimer un nœud de son parent en appelant la méthode Remove.L’exemple de code suivant montre comment accéder au nœud parent:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
// Create a new empty document. It has one section. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
// The section is the first child node of the document. | |
System::SharedPtr<Node> section = doc->get_FirstChild(); | |
// The section's parent node is the document. | |
std::cout << "Section parent is the document: " << System::ObjectExt::Box<bool>((doc == section->get_ParentNode()))->ToString().ToUtf8String() << std::endl; |
Nœuds Enfants
Le moyen le plus efficace d’accéder aux nœuds enfants d’un CompositeNode est via les propriétés FirstChild et LastChild qui renvoient respectivement les premier et dernier nœuds enfants. S’il n’y a pas de nœuds enfants, ces propriétés renvoient null.
CompositeNode
Si un nœud n’a pas d’enfant, la propriété ChildNodes renvoie une collection vide. Vous pouvez vérifier si le CompositeNode contient des nœuds enfants en utilisant la propriété HasChildNodes.
L’exemple de code suivant montre comment énumérer les nœuds enfants immédiats d’un CompositeNode
à l’aide de l’énumérateur fourni par la collection ChildNodes
:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<Paragraph> paragraph = System::DynamicCast<Paragraph>(doc->GetChild(NodeType::Paragraph, 0, true)); | |
System::SharedPtr<NodeCollection> children = paragraph->get_ChildNodes(); | |
for (System::SharedPtr<Node> child : System::IterateOver(children)) | |
{ | |
if (System::ObjectExt::Equals(child->get_NodeType(), NodeType::Run)) | |
{ | |
// Say we found the node that we want, do something useful. | |
System::SharedPtr<Run> run = System::DynamicCast<Run>(child); | |
std::cout << run->get_Text().ToUtf8String() << std::endl; | |
} | |
} |
L’exemple de code suivant montre comment énumérer les nœuds enfants immédiats d’un CompositeNode
à l’aide d’un accès indexé:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<Paragraph> paragraph = System::DynamicCast<Paragraph>(doc->GetChild(NodeType::Paragraph, 0, true)); | |
System::SharedPtr<NodeCollection> children = paragraph->get_ChildNodes(); | |
for (int32_t i = 0; i < children->get_Count(); i++) | |
{ | |
System::SharedPtr<Node> child = children->idx_get(i); | |
// Paragraph may contain children of various types such as runs, shapes and so on. | |
if (System::ObjectExt::Equals(child->get_NodeType(), NodeType::Run)) | |
{ | |
// Say we found the node that we want, do something useful. | |
System::SharedPtr<Run> run = System::DynamicCast<Run>(child); | |
std::cout << run->get_Text().ToUtf8String() << std::endl; | |
} | |
} |
Nœuds Frères
Vous pouvez obtenir le nœud qui précède ou suit immédiatement un nœud particulier en utilisant les propriétés PreviousSibling et NextSibling, respectivement. Si un nœud est le dernier enfant de son parent, alors la propriété NextSibling est null. Inversement, si le nœud est le premier enfant de son parent, la propriété PreviousSibling est null.
L’exemple de code suivant montre comment visiter efficacement tous les nœuds enfants directs et indirects d’un nœud composite:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
void TraverseAllNodes(System::SharedPtr<CompositeNode> parentNode) | |
{ | |
// This is the most efficient way to loop through immediate children of a node. | |
for (System::SharedPtr<Node> childNode = parentNode->get_FirstChild(); childNode != nullptr; childNode = childNode->get_NextSibling()) | |
{ | |
// Do some useful work. | |
std::cout << Node::NodeTypeToString(childNode->get_NodeType()).ToUtf8String() << std::endl; | |
// Recurse into the node if it is a composite node. | |
if (childNode->get_IsComposite()) | |
{ | |
TraverseAllNodes(System::DynamicCast<CompositeNode>(childNode)); | |
} | |
} | |
} | |
void RecurseAllNodes(System::String const &inputDataDir) | |
{ | |
// Open a document. | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(inputDataDir + u"Node.RecurseAllNodes.doc"); | |
// Invoke the recursive function that will walk the tree. | |
TraverseAllNodes(doc); | |
} |
Accès typé aux Nœuds Enfants et Parents
Jusqu’à présent, nous avons discuté des propriétés qui renvoient l’un des types de base – Node ou CompositeNode. Mais parfois, il y a des situations où vous pourriez avoir besoin de convertir des valeurs en une classe de nœud spécifique, telle que Run ou Paragraph. C’est-à-dire que vous ne pouvez pas complètement vous éloigner du casting lorsque vous travaillez avec le Aspose.Words DOM, qui est composite.
Pour réduire le besoin de conversion, la plupart des classes Aspose.Words fournissent des propriétés et des collections qui fournissent un accès fortement typé. Il existe trois modèles de base d’accès typé:
- Un nœud parent expose les propriétés typées FirstXXX et LastXXX. Par exemple, le Document a les propriétés FirstSection et LastSection. De même, Table a des propriétés telles que FirstRow, LastRow et autres.
- Un nœud parent expose une collection typée de nœuds enfants, tels que Document.Sections, Body.Paragraphs et autres.
- Un nœud enfant fournit un accès typé à son parent, tel que Run.ParentParagraph, Paragraph.ParentSection et autres.
Les propriétés typées sont simplement des raccourcis utiles qui fournissent parfois un accès plus facile que les propriétés génériques héritées de Node.ParentNode et CompositeNode.FirstChild.
L’exemple de code suivant montre comment utiliser les propriétés typées pour accéder aux nœuds de l’arborescence du document:
For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C | |
System::SharedPtr<Document> doc = System::MakeObject<Document>(); | |
System::SharedPtr<Section> section = doc->get_FirstSection(); | |
// Quick typed access to the Body child node of the Section. | |
System::SharedPtr<Body> body = section->get_Body(); | |
// Quick typed access to all Table child nodes contained in the Body. | |
System::SharedPtr<TableCollection> tables = body->get_Tables(); | |
for (System::SharedPtr<Table> table : System::IterateOver<System::SharedPtr<Table>>(tables)) | |
{ | |
// Quick typed access to the first row of the table. | |
if (table->get_FirstRow() != nullptr) | |
{ | |
table->get_FirstRow()->Remove(); | |
} | |
// Quick typed access to the last row of the table. | |
if (table->get_LastRow() != nullptr) | |
{ | |
table->get_LastRow()->Remove(); | |
} | |
} |