Belgelerle Çalışma

Aspose.Words FOSS for .NET, her Word dosyasını Document sınıfında köklenen bir bellek içi nesne modeli olarak temsil eder, DocumentBuilder ise içerik oluşturmak için yüksek seviyeli, imleç tabanlı bir API sağlar. Bu kılavuz, belgeleri oluşturma ve yükleme, DocumentBuilder ile yazma, bölüm/gövde yapısı, düğüm ağacında gezinme, belgeleri birleştirme ve koruma konularını kapsar.

Belgeleri Oluşturma ve Yükleme

new Document() ile boş bir belge oluşturun veya bir yolu veya Stream parametresini Document(fileName) ya da Document(stream) yapıcıya geçirerek mevcut bir dosyayı açın. LoadOptions argümanını kabul eden aşırı yüklemeler, şifreli bir dosya için parola sağlama gibi yükleme davranışını kontrol etmenizi sağlar.

Bilinmeyen veya güvenilmeyen bir kaynaktan dosya yüklemeden önce, FileFormatUtil.DetectFileFormat(fileName) (veya Stream aşırı yüklemesi), tespit edilen LoadFormat‘ü açıklayan bir FileFormatInfo döndürür ve dosyanın IsEncrypted, HasDigitalSignature veya HasMacros olup olmadığını belirtir.

DocumentBuilder ile Yazma

DocumentBuilder, bir Document paketler ve içeriği eklerken belge içinde hareket ettireceğiniz bir imleç sunar. Write(text) ve Writeln(text), imleçte metin ekler; InsertParagraph() yeni bir paragraf başlatır. Oluşturucudaki biçimlendirme özellikleri — Font, ParagraphFormat, ListFormat, PageSetup — bir sonraki yazılan her şeye uygulanır.

İmleci MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) veya MoveToParagraph(paragraphIndex, characterIndex) ile hareket ettirin. Oluşturucunun CurrentNode, CurrentParagraph ve CurrentSection özellikleri, ağacın içindeki mevcut konumunu rapor eder.

Belge Yapısı: Bölümler ve Gövde

Bir Document, bir SectionCollection (Document.Sections, ayrıca FirstSection / LastSection) tutar; her Section bir Body, isteğe bağlı üstbilgi/altbilgi koleksiyonu ve kendi PageSetup öğesine sahiptir. Section.AppendContent(sourceSection) ve PrependContent(sourceSection) bölümler arasında içeriği kopyalar, ve ClearContent() bir bölümü belgeden kaldırmadan sıfırlar.

Bir Body içinde, içerik Body.Paragraphs (bir ParagraphCollection) ve Body.Tables aracılığıyla ortaya çıkar. Document, Section, Paragraph ve diğer düğümlerden erişilebilen bir Range, ağacın kesintisiz bir alanını temsil eder; Range.Text düz metnini okur ve Range.Replace(pattern, replacement) sadece o alanda bir bul-ve-değiştir işlemi gerçekleştirir.

DocumentVisitor ile Düğüm Ağacını Gezinmek

Bir belgenin her bölümü — bölümler, paragraflar, koşular, tablolar, alanlar, şekiller, yorumlar, dipnotlar — Document kök düğümüne sahip bir birleşik ağaçta Nodedır. Belirli bir türdeki tüm düğümleri manuel olarak yinelemeye gerek kalmadan işlemek için, soyut DocumentVisitor sınıfından türeyin ve ihtiyaç duyduğunuz Visit*Start / Visit*End geri çağırma işlevlerini, örneğin VisitParagraphStart(paragraph) veya VisitRun(run), geçersiz kılın, ardından document.Accept(visitor) çağırın. Her geri çağırma, dolaşımın nasıl ilerleyeceğini kontrol etmek için bir VisitorAction (Continue, SkipThisNode veya Stop) döndürebilir.

İçeriği Kopyalama, İçe Aktarma ve Eklemleme

Document.Clone(), tüm bir belgenin derin bir kopyasını üretir. İki farklı Document örneği arasında içeriği taşımak için, hedef belge üzerinde ImportNode(srcNode, isImportChildren) çağırarak yabancı bir ağaçtan bir düğüm getirilebilir veya seçilen bir ImportFormatMode — KeepSourceFormatting, UseDestinationStyles veya KeepDifferentStyles — kullanarak bir belgenin bölümlerini diğerine eklemek için Document.AppendDocument(srcDoc, importFormatMode) çağırın. DocumentBuilder.InsertDocument(srcDoc, importFormatMode), hedef belgenin sonuna değil, oluşturucunun imlecine kaynak belgenin içeriğini ekler.

Belgeleri Koruma

Document.Protect(type, password), bir ProtectionType değerine göre düzenlemeyi kısıtlar — korumayı kaldırmak için ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields veya NoProtection. Unprotect() (parola ile ya da parolasız) bunu tersine çevirir. Bu, Word tarafından uygulanan bir düzenleme kısıtlamasıdır ve OoxmlSaveOptions.Password dosya kaydederken uyguladığı OOXML parola şifrelemesinden ayrı bir şeydir.

İpuçları ve En İyi Uygulamalar

Yeni içerik oluştururken DocumentBuilder kullanmayı tercih edin; mevcut bir ağaç üzerinde ince kontrol gerektiğinde doğrudan düğüm manipülasyonuna (AppendChild, InsertAfter, Clone) geçin.
Güvenilmeyen ya da kullanıcı tarafından sağlanan bir kaynaktan dosya yüklemeden önce FileFormatUtil.DetectFileFormat çağırın, böylece LoadFormat kontrol edebilir ve desteklenmeyen ya da şifreli girdileri erken reddedebilirsiniz.
AppendDocument veya InsertDocument ile belgeleri birleştirirken, ImportFormatMode öğesini kasıtlı olarak seçin — KeepSourceFormatting kaynağın görünümünü korur, UseDestinationStyles hedef belgenin stil kümesiyle eşleşir.
Her düğüm tipinin tüm örneklerini tutarlı bir şekilde işlemek gerektiğinde, manuel yinelemeli ağaç yürütme yerine bir DocumentVisitor alt sınıfı kullanın.
Document.Protect, bir düzenleme kısıtlamasıdır, şifreleme değildir — kaydedilen dosyanın açılması için bir parola gerektirmesi gerekiyorsa, bunu OoxmlSaveOptions.Password ile birlikte kullanın.

Yaygın Sorunlar

Sorun	Neden	Çözüm
`Document(fileName)`, Word’de sorunsuz açılan bir dosya için hata veriyor	Dosyanın formatı, bu sürümün yükleme için desteklediği formatlardan biri değil	Yüklemeden önce önce `FileFormatUtil.DetectFileFormat` çağırın ve döndürülen `LoadFormat`‘i kontrol edin
Eklenen içerik yanlış yazı tiplerini veya stilleri alıyor	`ImportFormatMode`, kaynak ve hedef stil setleri arasında uyumsuzluk	Varsayıcaya güvenmek yerine `KeepSourceFormatting` veya `UseDestinationStyles` değerini açıkça geçin
`DocumentVisitor` dolaşımı erken durur veya içeriği atlar	Bir `VisitStart` / `VisitEnd` geçersiz kılma, istemeden `SkipThisNode` veya `Stop` döndürür	Atlamayı veya durdurmayı özellikle amaçlamadığınız sürece, her geçersiz kılmadan `VisitorAction.Continue` döndürün
`Unprotect()` hiçbir etkisi yok	Belge bir şifre ile korunmamıştı veya yanlış şifre girildi	`Protect` şifresiz çağrıldıysa `Unprotect()` işlevini argümansız çağırın, aksi takdirde eşleşen şifreyi geçin

FAQ

`Document.Clone()` ile `ImportNode` arasındaki fark nedir?

Clone(), tüm bir belgeyi yeni bir Document örneğine kopyalar. ImportNode(srcNode, isImportChildren), bir belgenin ağacından tek bir düğümü (ve isteğe bağlı olarak alt düğümlerini) başka bir belgeye getirir; bu, tüm belgeler yerine belirli içeriği birleştirirken kullandığınız şeydir.

Hangi dosya formatlarını `Document(fileName)` yükleyebilir?

Document(fileName), DOCX, DOCM, DOTX, DOTM, Flat OPC (makro etkin ve şablon varyantları dahil), Markdown ve düz metni yükler. Daha eski kelime işlemci ve web formatları bu sürümün yükleyicilerinden hariç tutulmuştur.

Bir `DocumentBuilder` şu anda nerede konumlandırılmış olduğunu nasıl bulabilirim?

Builder örneğinde CurrentNode, CurrentParagraph veya CurrentSection‘yi okuyun.

Kaydedilen dosyayı `Document.Protect` şifreliyor mu?

Hayır — bu, dosya açıldığında Word tarafından uygulanan bir düzenleme kısıtlamasıdır. Dosyayı sadece açmak için bir parola gerektirmek istiyorsanız, kaydederken OoxmlSaveOptions.Password ayarlayın.

Bir belgenin gövdesindeki sadece paragrafları nasıl okuyabilirim?

Body.Paragraphs koleksiyonunu kullanın, ya da diğer düğüm türleri için Body.GetChildNodes(nodeType, isDeep) kullanın.

API Reference Özeti

Sınıf/Yöntem	Açıklama
`Document`	Belge nesne modelinin kökü; yapıcılar bir dosyadan veya akıştan yükler ya da boş bir belge oluşturur.
`Document.Save`	Belgeyi seçilen formatta bir dosyaya, akışa veya HTTP yanıtına yazar.
`Document.Clone()`	Tüm belgenin derin bir kopyasını üretir.
`Document.Protect(type, password)` / `Unprotect()`	Bir düzenleme kısıtlamasını uygular veya kaldırır.
`Document.AppendDocument(srcDoc, importFormatMode)`	Bu belgeye başka bir belgenin bölümlerini ekler.
`DocumentBuilder`	Metin yazmak ve bir belgeye içerik eklemek için imleç tabanlı API.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	İmleçte bir kaynak belgenin içeriğini ekler.
`Section` / `SectionCollection`	Bir belgenin tek bir bölümü ve tüm bölümlerin koleksiyonu.
`Body`	Bir bölümün ana metni (paragraflar ve tablolar) için kapsayıcı.
`Range`	Belge ağacının kesintisiz bir bölgesi; `Text` ve `Replace` destekler.
`DocumentVisitor`	Belge ağacındaki her düğümü dolaşmak için soyut temel sınıf.
`ProtectionType`	Belge seviyesindeki düzenleme kısıtlamalarının enum’ı.
`FileFormatUtil.DetectFileFormat`	Bir dosyanın veya akışın formatını yüklemeden önce algılar.

Ayrıca Bakınız

Aspose.Words for .NET — Enterprise Documentation

Belgelerle Çalışma