Giriş
Bu kılavuz, Aspose.Words FOSS for .NET nasıl bir Word belgesini bellekte temsil ettiğine ve bu temsili oluşturmak, gezinmek ve değiştirmek için kullanılan API’lere bakar: sıralı yazım için DocumentBuilder, doğrudan yapısal erişim için düğüm ağacı (Node, CompositeNode, NodeCollection), tüm düğüm türlerini tek geçişte işlemek için DocumentVisitor, Range ve FindReplaceOptions aracılığıyla bul ve değiştir, ve belgeleri birleştirme ve klonlama yöntemleri. Where duyuru gönderisi kütüphaneyi bütün olarak tanıtır, bu ise belge nesne modeline (DOM) odaklanır — API yüzeyinin tek en büyük alanı — ve parçalarının nasıl bir araya geldiği.
Aspose.Words FOSS for .NET, yerel bağımlılıklar olmadan MIT lisansı altında yayınlanmıştır; .NET Standard 2.0’ı hedefler, bu yüzden burada açıklanan DOM, .NET Framework 4.6.2+ ve .NET 6, 8 ve 10 üzerinde, Windows, Linux ve macOS’ta kullanılabilir. NuGet aracılığıyla kurun veya kaynak koddan derleyin — aşağıdaki Hızlı Başlangıç bölümüne bakın.
Aşağıda açıklanan her görev — sıfırdan bir rapor yazmak, mevcut bir .docx dosyasını yeniden yapılandırmak, analiz için içeriğini dolaşmak veya birden fazla belgeyi birleştirmek — aynı bir avuç temel türden başlar: Document, DocumentBuilder ve bunların altındaki Node hiyerarşisi.
Bu Document Object Model
DocumentBuilder ile Belgeler Oluşturma
DocumentBuilder, bir Document üzerine oturan ve içeriği sırayla ekleyen imleç tabanlı bir yazıcıdır. Write(text) ve Writeln(text) mevcut konuma metin ekler; InsertParagraph() ve InsertBreak(breakType) paragraf ve sayfa/sütun/bölüm sonları ekler. Biçimlendirme durumludur: oluşturucunun Font, ParagraphFormat, ListFormat ve PageSetup özellikleri sonrasında yazılan her şeye uygulanır ve PushFont() / PopFont() mevcut yazı tipi durumunu kaydeder ve geri yükler, böylece geçici bir stil değişikliğinin elle geri alınması gerekmez. Gezinme yöntemleri imleci mevcut bir belgenin herhangi bir yerine yeniden konumlandırır — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex) ve genel amaçlı MoveTo(node) — ve DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph ve DocumentBuilder.CurrentSection oluşturucunun şu anda nerede bulunduğunu rapor eder. Tam bir DOM gerektirmeyen yalnızca okuma amaçlı metin çıkarımı için PlainTextDocument daha hafif bir yol sunar: new PlainTextDocument(fileName) sadece PlainTextDocument.Text özelliğini ve belgenin yerleşik ve özel özelliklerini ortaya çıkarır.
Düğüm Ağacı: Bölümler, Paragraflar, Run’lar ve Tablolar
Document bir ağaçtır ve Node nesnelerinden oluşur, kökü belge kendisidir: gövde metni için Section → Body → Paragraph → Run, tablo çıktığı yerde ise Table → Row → Cell dallanır. CompositeNode, her konteyner düğümün temel sınıfı, doğrudan gezinme için CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling ve Node.PreviousSibling üyelerini sunar, belirli bir NodeType (Paragraph, Run, Table vb.) için tüm düğümleri herhangi bir derinlikte toplamak üzere GetChildNodes(nodeType, isDeep) ve indeksli aramalar için GetChild(nodeType, index, isDeep) sağlar. AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) ve RemoveChild(oldChild) ağaç üzerinde doğrudan değişiklik yapar. CompositeNode.SelectNodes(xpath) ve SelectSingleNode(xpath) düğümleri elle dolaşmak yerine XPath benzeri bir ifadeyle seçer ve çok büyük belgeler için Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) her bir düğümü tek tek, özyineleme olmadan adım adım dolaşır.
DocumentVisitor: Tek Geçişte Her Düğüm Türünün İşlenmesi
DocumentVisitor sınıfını alt sınıfa almak, bir belgenin yapısını sabit kodlamadan işlemek için kullanılan yöntemdir. Her birleşik düğüm türü için eşleşen Visit-Start / Visit-End metodlarını tanımlar; örneğin DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart ve DocumentVisitor.VisitBookmarkStart — her biri karşılık gelen End geri çağrısına sahiptir — ayrıca tek tek metin çalışları için DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd ve DocumentVisitor.VisitRun bulunur. Bir Document, Section veya başka herhangi bir düğüm üzerinde Accept(visitor) çağırarak ziyaretçiyi o düğüm ve altındaki tüm öğeler üzerinde çalıştırabilirsiniz; AcceptStart(visitor) ve AcceptEnd(visitor) yalnızca tek bir birleşik düğüm için giriş ve çıkış geri çağrılarını tetikler. Her Visit metodu, gezinmenin nasıl devam edeceğini kontrol eden bir VisitorAction değeri döndürür — alt ağaca devam etmek için Continue, atlamak için SkipThisNode veya tamamen durdurmak için Stop.
Metin Bulma ve Değiştirme
Range.Replace(pattern, replacement) sahip olduğu Range üzerinde — bütün bir Document, bir Section ya da herhangi bir düğümün kendi Range özelliği — bul ve değiştir işlemini yürütür; arama deseni ya literal bir metin dizgesi ya da bir düzenli ifade olarak kabul edilir. Range.Replace(pattern, replacement, options) aşırı yüklemesi, FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, arama yönünü belirleyen FindReplaceOptions.Direction (İleri veya Geri yönlü bir FindReplaceDirection değeri), değiştirilen metne uygulanacak biçimlendirme (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat) ve hangi çevresel içeriğin değişmeden bırakılacağını (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes ve ilgili Ignore* bayrakları) kontrol eden bir FindReplaceOptions örneği alır. Basit bir yerine koymanın ötesinde, eşleşme başına mantık eklemek için IReplacingCallback arayüzünün Replacing(args) metodunu uygulayın ve bu uygulamayı FindReplaceOptions.ReplacingCallback‘e atayın; her eşleşme, eşleşmeyi tanımlayan bir ReplacingArgs ile geri çağırılır ve geri dönüş değeri — ReplaceAction değerlerinden Replace, Skip veya Stop — o eşleşmenin ne yapılacağını belirler.
Belgeleri Birleştirme ve Kopyalama
Document.AppendDocument(srcDoc, importFormatMode) bir Document‘in tüm içeriğini diğerinin sonuna ekler. Its importFormatMode argümanı — UseDestinationStyles, KeepSourceFormatting, veya KeepDifferentStyles değerlerinden bir ImportFormatMode — kaynak ve hedef arasındaki stil çakışmalarının nasıl çözüleceğini belirler ve Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) aşırı yüklemesi ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists ve benzeri bayraklar) aracılığıyla daha ince kontrol ekler. Başka bir belgenin içeriğini son yerine belirli bir konuma eklemek için DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) builder’ın mevcut imleç konumundan eşdeğerini yapar ve DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) aynı içeriği ekleme noktasında paragraf veya bölüm sonu eklemeden ekler. Document.ImportNode(srcNode, isImportChildren) farklı bir belgeden bir düğümü — isteğe bağlı olarak çocuklarıyla birlikte — kopyalar, böylece mevcut belgeye eklenebilir ve herhangi bir düğümde bulunan Node.Clone(isCloneChildren) yöntemi aynı belge içinde yapıyı çoğaltır; örneğin bir Section‘ı tekrar eden içerik için şablon olarak yeniden kullanmak gibi.
Yer İşaretleri ve Belge Değişkenleri
Range.Bookmarks özelliği, bu aralık içinde adlandırılmış bağlantı noktalarından oluşan bir BookmarkCollection sunar. DocumentBuilder.StartBookmark(bookmarkName) ve EndBookmark(bookmarkName) bir yer işaretinin kapsamını oluşturma sırasında işaretler; BookmarkCollection dizinleyicisi, bookmarks[name], daha sonra DocumentBuilder.MoveToBookmark(bookmarkName) navigasyonu için veya Bookmark.Text okumak için birini geri getirir. Ayrı olarak, Document.Variables — bir VariableCollection — belgeye doğrudan key/value string çiftlerini depolar; bu, görünür içerik eklemeden belge-oluşturma işlem hattı boyunca küçük durum parçacıklarını taşımak için kullanışlıdır.
Hızlı Başlangıç
Aspose.Words FOSS, .NET için NuGet aracılığıyla kullanılabilir:
dotnet add package Aspose.Words.FOSSBunun yerine kaynaktan derlemek için:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Bir proje referansı Aspose.Words.csproj mevcut olduğunda, bir belgeye en kısa yol bu gönderide kullanılan aynı desen izler: bir Document oluşturun, onu bir DocumentBuilder içine sarın, metin eklemek için Write() veya Writeln() çağırın — builder’ın Font ve ParagraphFormat özelliklerine ayarlanan biçimlendirme sonraki tüm yazmalara taşınır — ve belgeyi .docx, .docm, .dotx, .dotm, Flat OPC, Markdown veya düz metin olarak kaydetmek için Document.Save(fileName) çağırın. Sıfırdan başlamak yerine mevcut bir dosyayı düzenlemek için, new Document(fileName) ile doğrudan yükleyin, builder’ı belirli bir konuma MoveToBookmark(), MoveToParagraph() veya MoveTo(node) ile taşıyın ve oradan yazmaya devam edin.
Desteklenen Biçimler
| Biçim | Uzantı | Oku | Yaz |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Düz OPC (tüm varyantlar) | (çeşitli) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Yukarıda açıklanan düğüm ağacı, bir belgenin bu formatlardan hangisiyle yüklendiğine veya hangi formata kaydedileceğine bakılmaksızın aynı şekilde kullanılabilir — DOM içsel olarak formattan bağımsızdır. Bu sürümde sayfa düzenine bağlı olan hiçbir şey bulunmaz: PDF, XPS veya görüntü dışa aktarma yoktur ve yazdırma yoktur, bu nedenle sayfa numaraları gibi düzen bağımlı alan değerleri hesaplanmak yerine yer tutucular olarak değerlendirilir. Ek format dönüştürücüleri (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 ve WordML) okunmaz veya yazılmaz, ayrıca posta birleştirme yürütmesi, LINQ Raporlama ve belge karşılaştırması dahil değildir. Bu yeteneklere ihtiyaç duyan geliştiriciler ticari sürüme geçebilirler Aspose.Words for .NET burada gösterilen DOM kodunu yeniden yazmadan, çünkü her iki sürüm de aynı temel API’ı paylaşır.
Açık Kaynak & Lisanslama
Aspose.Words FOSS for .NET, MIT lisansı altında yayımlanmıştır, ticari ve kişisel kullanım için ücretsizdir, telif hakkı veya yeniden dağıtım kısıtlaması yoktur. Kaynak, dahil olan Document, DocumentBuilder, ve yukarıda açıklanan düğüm-ağacı uygulaması, şurada mevcuttur Aspose.Words FOSS for .NET deposu GitHub üzerinde.
