Belge Düğüm Ağacı ile Çalışma

Belge Düğüm Ağacıyla Çalışma

Bu kılavuz, bir belgenin yapısını doğrudan düğüm ağacı üzerinden nasıl gezileceğini ve manipüle edileceğini gösterir — Document, Section, Paragraph, Run, Table ve diğer tüm belge öğelerinin üzerine kurulu nesne modeli. Bir belgedeki her öğe Node‘den türetilir ve çocuk tutabilen her öğe CompositeNode‘dan türetilir, bu yüzden bu iki temel sınıfı anlamak, henüz özel bir yardımcı API tarafından kapsanmayan içerikle nasıl çalışılacağını açıklar.

Düğüm ve CompositeNode Temel Sınıfları

Node, bir belge ağacındaki her nesnenin soyut temel sınıfıdır. NodeType‘i (bu düğümün ne tür bir düğüm olduğunu tanımlayan enum değeri), ParentNode‘yi (içeren CompositeNode), Document‘ü (sahip belge), ve aynı seviyedeki düğümler arasında hareket etmek için PreviousSibling/NextSibling‘ı ortaya çıkarır. Node.IsComposite, verilen bir düğümün çocuk tutup tutamayacağını rapor eder. CompositeNode, kapsayıcı öğeler için Node‘u genişletir — FirstChild, LastChild ve Count onun doğrudan çocuklarını tanımlar ve HasChildNodes herhangi birinin olup olmadığını rapor eder. CompositeNode.GetChildNodes(nodeType, isDeep), verilen bir NodeType‘in tüm çocuklarını alır, isteğe bağlı olarak tam alt ağaçta (isDeep) arama yapar, yalnızca doğrudan çocukları değil, ve CompositeNode.GetChild(nodeType, index, isDeep) bir tanesini indeksle getirir.

NodeType Enum’ı

NodeType, belge modelinin tanımladığı her düğüm türünü sıralar — Document, Section, Body, Paragraph, Table, Row ve Cell gibi yapısal tipler; Run, Shape ve Comment gibi satır içi içerik tipleri; ve FieldStart, FieldSeparator ve FieldEnd gibi alan-makinesi tipleri, ki bunlar bir Word alanının sınırlarını ve geçiş metnini koşu akışı içinde işaretler. Bir NodeType değerini GetChildNodes ya da GetChild içine geçirerek aramayı tam olarak o tipteki düğümlere sınırlandırabilirsiniz, ya da NodeType.Any geçirerek her düğüm tipini eşleştirebilirsiniz.

Ağacı Gezinme ve Değiştirme

CompositeNode.GetEnumerator() bir düğümün doğrudan çocukları üzerinde yineleme yapmanızı sağlar ve CompositeNode ayrıca alt ağaçta XPath tabanlı sorgular için SelectNodes(xpath) ve SelectSingleNode(xpath) uygular. Ağacı değiştirmek için AppendChild(newChild) ve PrependChild(newChild) bir düğümü çocukların başına veya sonuna ekler, InsertBefore(newChild, refChild) ve InsertAfter(newChild, refChild) mevcut bir çocuğa göre ekleme yapar ve RemoveChild(oldChild) veya RemoveAllChildren() düğümleri kaldırır. CompositeNode.IndexOf(child) bir çocuğun konumunu döndürür. Node üzerinde, Clone(isCloneChildren) bir kopya oluşturur — isteğe bağlı olarak derin — ve Remove() düğümü ebeveyninden ayırır. Node.NextPreOrder(rootNode) ve PreviousPreOrder(rootNode) ağaçta belge sırasına göre, verilen bir kök düğümle sınırlı olarak adım atar; bu, özyinelemeli kod olmadan tüm alt ağacı düğüm döngüsüyle taramanın yaygın bir yoludur.

Düğüm Koleksiyonları ve Değişiklik Bildirimleri

NodeCollection, Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node), IndexOf(node) ve ToArray() destekleyen somut, değiştirilebilir bir düğüm koleksiyonudur ve ayrıca bir Count özelliği bulunur. NodeList ve NodeEnumerator, SelectNodes tarafından döndürülen düğümler gibi sorgu sonuçları üzerinde okuma-stili yineleme destekler. Yapısal değişiklikleri anlık olarak gözlemlemek için INodeChangingCallback uygulayın — onun NodeInserting(args), NodeInserted(args), NodeRemoving(args) ve NodeRemoved(args) yöntemleri, etkilenen Nodeı tanımlayan bir NodeChangingArgs alır, ayrıca OldParent/NewParent ve gerçekleşen NodeChangingAction.

DocumentVisitor ile Düğümleri Ziyaret Etmek

Ağacı manuel olarak dolaşmadan her düğüm tipini yapılandırılmış bir şekilde işlemek için DocumentVisitor sınıfını alt sınıf olarak oluşturun ve ilgilendiğiniz düğüm tipleri için Visit*Start/Visit*End yöntemlerini geçersiz kılın — VisitParagraphStart/VisitParagraphEnd, VisitTableStart/VisitTableEnd, VisitRun vb. — ardından Node.Accept(visitor) metodunu alt ağacın kökünde çağırarak çalıştırın. Bu, her kullanım durumu için özel özyinelemeli geçiş kodu yazmadan bir belgeyi dışa aktarmak, dönüştürmek veya incelemek için standart bir desenidir.

İpuçları ve En İyi Uygulamalar

Her türden bağımsız olarak tüm alt düğümlere ihtiyaç duyduğunuzda GetChildNodes yerine GetChildNodes(NodeType.Any, true) ile NodeType.Any kullanın.
Manuel özyinelemeli iniş yazmak yerine bir alt ağacın düz, özyinelemeyen taraması için Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) tercih edin.
Aynı işlemin birçok farklı düğüm türünde çalışması gerektiğinde, özensiz ağaç yürütme kodu yerine DocumentVisitor uygulayın.
Bilinmeyen türde bir düğümle çalışırken, CompositeNode‘e dönüştürmeden önce Node.IsComposite‘ı kontrol edin.
Yalnızca kendi kodunuzun doğrudan yaptığı değişikliklere değil, diğer kodların (yerleşik işlemler dahil) yaptığı eklemeler veya kaldırmalar için tepki vermeniz gerektiğinde bir INodeChangingCallback kaydedin.

Yaygın Sorunlar

Sorun	Neden	Düzeltme
Bir `Node`‘ı `CompositeNode`‘e cast etmek geçersiz cast hatası fırlatır	Düğüm, çocuk tutamayan bir yaprak tipidir (örneğin `Run` veya `FieldStart`)	`Node.IsComposite`‘ı önce kontrol edin, ya da cast etmeden önce düğümün bir kapsayıcı tip olup olmadığını doğrulamak için `NodeType`‘ı kullanın
`GetChildNodes` yalnızca doğrudan çocukları döndürür	`isDeep` `false` bırakıldı (veya aşırı yüklemenin varsayılanı sığ olduğunda atlandı)	Tüm alt ağacı aramak için `isDeep: true` geçirin
Bir koleksiyonu üzerinde yineleme yaparken değiştirmek bir hata üretir	Düğümler, `foreach` içinde `NodeCollection` üzerinde veya `GetChildNodes` sonucunda eklendi ya da kaldırıldı	İlk olarak `ToArray()` ile değiştirilmesi gereken düğümleri somutlaştırın, ardından ağacı değiştirirken dizi üzerinde yineleme yapın
Bir `DocumentVisitor` alt sınıfı bazı içerikler için çağrılmıyor	Ziyaretçi, hedef içeriği içermeyen bir düğüm üzerinde `Accept()` aracılığıyla çağrıldı ya da ilgili `Visit*` metodu geçersiz kılınmadı	İçeriği içeren bir ata üzerinde `Accept()` çağırın ve işlenen düğüm tipleriyle ilgili her `VisitStart`/`VisitEnd` çiftini geçersiz kılın

FAQ

`Node` ile `CompositeNode` arasındaki fark nedir?

Node, her belge öğesinin türediği temel sınıftır. CompositeNode, çocukları (örneğin Body, Paragraph ve Table) içerebilen öğeler için Node‘yi genişletir; yaprak öğeler (örneğin Run) doğrudan Node‘den türetilir ve çocuk tutamaz.

Belgede belirli bir türdeki tüm düğümleri nasıl bulabilirim?

Aramanızın kök düğümünde (genellikle Document kendisi) CompositeNode.GetChildNodes(nodeType, isDeep) metodunu çağırın, istediğiniz NodeType ve tüm alt ağacı, sadece doğrudan çocukları değil, aramak için isDeep: true parametresini geçirin.

Döngü sırasında düğümleri güvenli bir şekilde nasıl kaldırabilirim?

Kaldırılacak düğümleri önce bir diziye toplayın — örneğin NodeCollection.ToArray() ile — ardından bu dizi üzerinde döngü yapın ve her düğümde Remove() metodunu çağırın; böylece bir foreach döngüsü sırasında canlı koleksiyonu değiştirmek yerine.

`FieldStart`, `FieldSeparator` ve `FieldEnd` düğümleri nedir?

Bunlar, çalışma akışına gömülü bir Word alanının mekanizmasını işaretleyen NodeType değerleridir: FieldStart ve FieldEnd alanı bağlar, ve FieldSeparator alan kodunu şu anda görüntülenen sonucundan ayırır.

Bir belgede her paragrafı, tabloyu ve run’u nasıl işlerim?

DocumentVisitor sınıfından türeyin, ihtiyacınız olan düğüm tipleri için VisitParagraphStart/VisitParagraphEnd, VisitTableStart/VisitTableEnd ve VisitRun metodlarını geçersiz kılın, ardından Accept(visitor) metodunu Document üzerinde (veya herhangi bir alt ağaç kökü) çağırarak çalıştırın.

API Reference Özeti

Sınıf/Yöntem	Açıklama
`Node`	Bir belge ağacındaki her düğüm için soyut temel sınıf
`CompositeNode`	Çocuklar içerebilen düğümler için temel sınıf
`CompositeNode.GetChildNodes(nodeType, isDeep)`	Belirli bir türe ait tüm çocukları, isteğe bağlı olarak tüm alt ağaçta da al
`CompositeNode.AppendChild(newChild)` / `InsertBefore(newChild, refChild)`	Bir düğümü bir kapsayıcının sonuna ekle, ya da mevcut bir çocuğun önüne/arkasına ekle
`NodeType`	Bir düğümün türünü tanımlayan enum (`Paragraph`, `Table`, `Run`, `FieldStart` ve benzeri)
`NodeCollection`	Somut, değiştirilebilir `Node` nesnelerinin koleksiyonu
`Node.Clone(isCloneChildren)`	Bir düğümü kopyala, isteğe bağlı olarak çocuklarını da dahil et
`Node.NextPreOrder(rootNode)` / `PreviousPreOrder(rootNode)`	Belge sırasına göre bir alt ağacın içinde ilerle
`INodeChangingCallback`	Düğümler eklendiğinde veya kaldırıldığında bildirilen Callback arayüzü
`DocumentVisitor`	Yapılandırılmış, tip yönlendirmeli gezinme için `Node.Accept(visitor)` aracılığıyla temel sınıf

Ayrıca Bakınız

Aspose.Words for .NET — Enterprise Documentation