Bekerja dengan Dokumen

Aspose.Words FOSS untuk .NET merepresentasikan setiap file Word sebagai model objek dalam memori yang berakar pada kelas Document, dengan DocumentBuilder menyediakan API tingkat tinggi berbasis kursor untuk menulis konten. Panduan ini mencakup pembuatan dan pemuatan dokumen, penulisan dengan DocumentBuilder, struktur bagian/tubuh, penelusuran pohon node, penggabungan dokumen, dan perlindungannya.

Membuat dan Memuat Dokumen

Buat dokumen kosong dengan new Document(), atau buka file yang sudah ada dengan memberikan jalur atau Stream ke konstruktor Document(fileName) atau Document(stream). Overload yang menerima argumen LoadOptions memungkinkan Anda mengontrol perilaku pemuatan, seperti memberikan kata sandi untuk file terenkripsi.

Sebelum memuat file dari sumber yang tidak diketahui atau tidak tepercaya, FileFormatUtil.DetectFileFormat(fileName) (atau overload Stream) mengembalikan FileFormatInfo yang menjelaskan LoadFormat yang terdeteksi, serta apakah file IsEncrypted, HasDigitalSignature, atau HasMacros.

Menulis dengan DocumentBuilder

DocumentBuilder membungkus Document dan mengekspos kursor yang Anda gerakkan melalui dokumen saat menyisipkan konten. Write(text) dan Writeln(text) menyisipkan teks pada kursor; InsertParagraph() memulai paragraf baru. Properti pemformatan pada builder — Font, ParagraphFormat, ListFormat, PageSetup — diterapkan pada apa pun yang ditulis berikutnya.

Pindahkan kursor dengan MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), atau MoveToParagraph(paragraphIndex, characterIndex). Properti CurrentNode, CurrentParagraph, dan CurrentSection builder melaporkan posisi saat ini dalam pohon.

Struktur Dokumen: Bagian dan Isi

Sebuah Document menampung SectionCollection (Document.Sections, plus FirstSection / LastSection); setiap Section memiliki satu Body, koleksi header/footer opsional, dan PageSetup miliknya sendiri. Section.AppendContent(sourceSection) dan PrependContent(sourceSection) menyalin konten antar bagian, dan ClearContent() mengatur ulang sebuah bagian tanpa menghapusnya dari dokumen.

Di dalam Body, konten diekspos melalui Body.Paragraphs (sebuah ParagraphCollection) dan Body.Tables. Sebuah Range — tersedia dari Document, Section, Paragraph, dan node lainnya — mewakili area berkelanjutan pada pohon; Range.Text membaca teks polosnya dan Range.Replace(pattern, replacement) melakukan temukan-dan-ganti hanya pada area tersebut.

Menelusuri Pohon Node dengan DocumentVisitor

Setiap bagian dari dokumen — bagian, paragraf, run, tabel, bidang, bentuk, komentar, catatan kaki — adalah Node dalam pohon komposit yang berakar di Document. Untuk memproses setiap node dari tipe tertentu tanpa harus melakukan rekursi manual, buat subclass dari DocumentVisitor abstrak dan timpa callback Visit*Start / Visit*End yang Anda butuhkan, seperti VisitParagraphStart(paragraph) atau VisitRun(run), lalu panggil document.Accept(visitor). Setiap callback dapat mengembalikan VisitorAction (Continue, SkipThisNode, atau Stop) untuk mengendalikan cara traversal berlangsung.

Menggandakan, Mengimpor, dan Menambahkan Konten

Document.Clone() menghasilkan salinan mendalam dari seluruh dokumen. Untuk memindahkan konten antara dua instance Document yang berbeda, panggil ImportNode(srcNode, isImportChildren) pada dokumen tujuan untuk memasukkan node dari pohon asing, atau panggil Document.AppendDocument(srcDoc, importFormatMode) untuk menambahkan bagian-bagian satu dokumen ke dokumen lain menggunakan ImportFormatMode yang dipilih — KeepSourceFormatting, UseDestinationStyles, atau KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) menyisipkan konten dokumen sumber pada kursor builder alih-alih di akhir tujuan.

Melindungi Dokumen

Document.Protect(type, password) membatasi penyuntingan berdasarkan nilai ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields, atau NoProtection untuk menghapus perlindungan. Unprotect() (dengan atau tanpa kata sandi) membaliknya. Ini adalah pembatasan penyuntingan yang diterapkan oleh Word, terpisah dari enkripsi kata sandi OOXML yang OoxmlSaveOptions.Password terapkan saat menyimpan file.

Tips dan Praktik Terbaik

Lebih pilih DocumentBuilder untuk membuat konten baru; turun ke manipulasi node langsung (AppendChild, InsertAfter, Clone) ketika Anda memerlukan kontrol detail atas pohon yang ada.
Panggil FileFormatUtil.DetectFileFormat sebelum memuat file dari sumber yang tidak tepercaya atau yang diberikan pengguna sehingga Anda dapat memeriksa LoadFormat dan menolak masukan yang tidak didukung atau terenkripsi lebih awal.
Saat menggabungkan dokumen dengan AppendDocument atau InsertDocument, pilih ImportFormatMode dengan sengaja — KeepSourceFormatting mempertahankan tampilan sumber, UseDestinationStyles menyesuaikan set gaya dokumen target.
Gunakan subclass DocumentVisitor alih-alih penelusuran pohon rekursif manual ketika Anda perlu memproses setiap instance tipe node secara konsisten.
Document.Protect adalah pembatasan penyuntingan, bukan enkripsi — padukan dengan OoxmlSaveOptions.Password jika file yang disimpan harus memerlukan kata sandi untuk dibuka.

Masalah Umum

Masalah	Penyebab	Perbaikan
`Document(fileName)` menghasilkan kesalahan untuk file yang dapat dibuka dengan baik di Word	Format file tidak termasuk yang didukung oleh edisi ini untuk dimuat	Panggil `FileFormatUtil.DetectFileFormat` terlebih dahulu dan periksa `LoadFormat` yang dikembalikan sebelum memuat
Konten yang ditambahkan mengambil font atau gaya yang salah	Ketidaksesuaian `ImportFormatMode` antara set gaya sumber dan tujuan	Berikan `KeepSourceFormatting` atau `UseDestinationStyles` secara eksplisit alih-alih mengandalkan nilai default
Penelusuran `DocumentVisitor` berhenti lebih awal atau melewatkan konten	Sebuah override `VisitStart` / `VisitEnd` mengembalikan `SkipThisNode` atau `Stop` secara tidak sengaja	Kembalikan `VisitorAction.Continue` dari setiap override kecuali Anda secara khusus berniat untuk melewatkan atau menghentikan
`Unprotect()` tidak berpengaruh	Dokumen tidak dilindungi dengan kata sandi, atau kata sandi yang diberikan salah	Panggil `Unprotect()` tanpa argumen jika `Protect` dipanggil tanpa kata sandi, jika tidak kirimkan kata sandi yang cocok

FAQ

Apa perbedaan antara `Document.Clone()` dan `ImportNode`?

Clone() menyalin seluruh dokumen ke dalam sebuah instance Document yang baru. ImportNode(srcNode, isImportChildren) memindahkan satu node (dan opsional anak-anaknya) dari pohon satu dokumen ke dokumen lain, yang merupakan cara yang Anda gunakan ketika menggabungkan konten spesifik daripada seluruh dokumen.

Format file apa yang dapat `Document(fileName)` muat?

Document(fileName) memuat DOCX, DOCM, DOTX, DOTM, Flat OPC (beserta varian macro-enabled dan templatenya), Markdown, dan teks biasa. Format pengolah kata dan web yang lebih lama dikecualikan dari pemuat edisi ini.

Bagaimana cara menemukan di mana `DocumentBuilder` saat ini berada?

Baca CurrentNode, CurrentParagraph, atau CurrentSection pada instance builder.

Apakah `Document.Protect` mengenkripsi file yang disimpan?

Tidak — itu adalah pembatasan penyuntingan yang diterapkan oleh Word saat file dibuka. Untuk meminta kata sandi hanya saat membuka file, atur OoxmlSaveOptions.Password saat menyimpan.

Bagaimana cara membaca hanya paragraf dalam isi dokumen?

Gunakan koleksi Body.Paragraphs, atau Body.GetChildNodes(nodeType, isDeep) untuk tipe node lainnya.

API Reference Ringkasan

Kelas/Metode	Deskripsi
`Document`	Akar dari model objek dokumen; konstruktor memuat dari file atau stream, atau membuat dokumen kosong.
`Document.Save`	Menulis dokumen ke file, stream, atau respons HTTP dalam format yang dipilih.
`Document.Clone()`	Menghasilkan salinan mendalam dari seluruh dokumen.
`Document.Protect(type, password)` / `Unprotect()`	Menerapkan atau menghapus pembatasan penyuntingan.
`Document.AppendDocument(srcDoc, importFormatMode)`	Menambahkan bagian-bagian dokumen lain ke dokumen ini.
`DocumentBuilder`	API berbasis kursor untuk menulis teks dan menyisipkan konten ke dalam dokumen.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Menyisipkan konten dokumen sumber pada kursor.
`Section` / `SectionCollection`	Sebuah bagian tunggal dari dokumen, serta kumpulan semua bagian.
`Body`	Kontainer untuk teks utama (paragraf dan tabel) dari sebuah bagian.
`Range`	Area berurutan dari pohon dokumen; mendukung `Text` dan `Replace`.
`DocumentVisitor`	Kelas dasar abstrak untuk menjelajahi setiap node dalam pohon dokumen.
`ProtectionType`	Enum dari pembatasan penyuntingan tingkat dokumen.
`FileFormatUtil.DetectFileFormat`	Mendeteksi format file atau aliran sebelum memuatnya.

Lihat Juga

Aspose.Words for .NET — Enterprise Documentation

Bekerja dengan Dokumen