Cara Memuat Dokumen Word di .NET
Cara Memuat Dokumen Word di .NET
Aspose.Words FOSS untuk .NET membaca dokumen ke memori segera setelah Anda membuat sebuah Document objek — setiap jalur pemuatan dalam perpustakaan mengalir melalui Document’s overload konstruktor dan the LoadOptions kelas. Panduan ini menunjukkan cara memuat dokumen dari file atau aliran, menyediakan kata sandi atau pengaturan khusus format, dan mengendalikan apa yang terjadi ketika pemuatan menemukan sumber eksternal atau dokumen yang mungkin rusak. Aspose.Words FOSS untuk .NET dibangun dari sumber dan direferensikan langsung dalam sebuah proyek alih-alih diinstal dari umpan paket — lihat the Panduan Instalasi untuk langkah-langkah pembangunan sebelum mengerjakan tugas di bawah ini.
Panduan Langkah-demi-Langkah
Langkah 1: Muat Dokumen dari File atau Aliran
Document memiliki lima konstruktor. Document() membuat dokumen baru yang kosong alih-alih memuat satu. Document(fileName) memuat langsung dari jalur di disk, dan Document(stream) memuat dari Stream yang dapat dibaca — berguna ketika sumber bukan file, seperti konten yang sudah ada di memori atau diterima melalui koneksi jaringan. Kedua konstruktor tersebut memiliki overload pendamping yang menerima argumen kedua, Document(fileName, loadOptions) dan Document(stream, loadOptions), yang menjadi titik masuk untuk setiap tugas lain dalam panduan ini.
Langkah 2: Muat Dokumen yang Dilindungi Kata Sandi
Bangun sebuah LoadOptions dengan kata sandi sebelum memanggil Document(fileName, loadOptions) (atau overload stream). new LoadOptions(password) menetapkan LoadOptions.Password secara langsung; alternatifnya, tetapkan Password pada instance LoadOptions() tanpa parameter sebelum mengirimkannya. Berikan kata sandi di awal daripada memuat dulu dan bereaksi terhadap kegagalan — Aspose.Words FOSS untuk .NET membutuhkan kata sandi untuk mengurai file yang dilindungi sama sekali, jadi tidak ada keadaan termuat sebagian yang dapat dipulihkan.
Langkah 3: Terapkan Opsi Khusus Format untuk Sumber Teks dan Markdown
Sumber teks polos dan Markdown menerima pengaturan yang tidak diekspos oleh LoadOptions dasar. TxtLoadOptions menambahkan AutoNumberingDetection dan DetectNumberingWithWhitespaces untuk mengenali daftar bernomor dalam teks polos, DetectHyperlinks untuk mengubah URL mentah menjadi hyperlink, DocumentDirection (LeftToRight, RightToLeft, atau Auto) untuk arah aliran teks, dan LeadingSpacesOptions/TrailingSpacesOptions terpisah (tipe TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) untuk penanganan spasi putih di awal dan akhir setiap baris. MarkdownLoadOptions menambahkan PreserveEmptyLines, ImportUnderlineFormatting, dan SoftLineBreakCharacter untuk mengontrol bagaimana konvensi pemutusan baris Markdown dipetakan ke paragraf dan rangkaian. Kedua subclass diturunkan dari LoadOptions, sehingga kata sandi atau callback pemuatan sumber daya yang diatur pada salah satunya berperilaku sama seperti pada kelas dasar — kirimkan instance khusus format ke Document(fileName, loadOptions) persis seperti Anda akan mengirimkan LoadOptions polos.
Langkah 4: Alihkan atau Intersep Sumber Daya Eksternal Saat Memuat
Tetapkan LoadOptions.ResourceLoadingCallback ke implementasi IResourceLoadingCallback ketika Anda perlu mengontrol bagaimana sumber daya eksternal yang dirujuk oleh dokumen diselesaikan saat memuat. Metode ResourceLoading(args)-nya menerima sebuah ResourceLoadingArgs yang menjelaskan ResourceType sumber daya (Image, Font, CssStyleSheet, atau Document) bersama dengan Uri dan OriginalUri, dan mengembalikan sebuah ResourceLoadingAction — Default untuk memuat sumber daya secara normal, Skip untuk mengabaikannya, atau UserProvided untuk menggantikan data yang disediakan melalui ResourceLoadingArgs.SetData(data).
Langkah 5: Tetapkan Default Bahasa dan Perilaku Pemulihan
Jika metadata bahasa dokumen tidak ada atau tidak dapat diandalkan, tetapkan LoadOptions.LanguagePreferences.DefaultEditingLanguage ke nilai EditingLanguage sebelum memuat, dan gunakan AddEditingLanguage(language) atau AddEditingLanguages(languages) pada LanguagePreferences untuk mendaftarkan bahasa tambahan yang mungkin ada dalam dokumen. Untuk sumber yang mungkin rusak, tetapkan LoadOptions.RecoveryMode ke nilai DocumentRecoveryMode — None untuk memuat tanpa upaya pemulihan apa pun, atau TryRecover agar pemuat mengatasi beberapa masalah struktural alih-alih gagal memuat secara total.
Masalah Umum dan Solusi
Memuat dokumen yang dilindungi kata sandi masih melemparkan pengecualian setelah memberikan kata sandi. Pastikan kata sandi telah diatur pada yang tepat LoadOptions instance yang diteruskan ke Document(fileName, loadOptions) (atau overload stream) — via new LoadOptions(password) atau dengan menyetel Password setelahnya — dan bahwa ini adalah objek yang sebenarnya diteruskan ke constructor. Sebuah LoadOptions yang dibuat tetapi tidak pernah diberikan ke Document tidak berpengaruh pada load.
Pengaturan khusus Text atau Markdown tampaknya tidak berlaku. Periksa bahwa sebuah TxtLoadOptions or MarkdownLoadOptions instance — bukan yang dasar LoadOptions — dilewatkan ke Document constructor. Hanya subclass yang mengekspos properti khusus format; melewatkan kelas dasar tetap dapat dikompilasi tetapi secara diam-diam mengabaikannya.
Sumber daya eksternal tidak diintersep atau diarahkan ulang. ResourceLoadingCallback harus diatur pada yang sama LoadOptions objek yang diberikan ke Document konstruktor, dan harus ditetapkan sebelum pemanggilan load. Menetapkannya setelah pemuatan selesai tidak berpengaruh.
Dokumen yang rusak tetap gagal dimuat setelah pengaturan RecoveryMode. DocumentRecoveryMode.TryRecover memungkinkan loader mengatasi beberapa masalah struktural dalam dokumen, tetapi korupsi yang lebih parah masih dapat mencegah dokumen dimuat dengan sukses.
Sebuah dokumen yang dimuat dari sebuah Stream berperilaku berbeda dibandingkan file yang sama dimuat melalui jalur. Verifikasi posisi aliran berada di awal sebelum meneruskannya ke Document(stream) or Document(stream, loadOptions) — sebuah stream yang ditinggalkan di tengah kontennya hanya memuat byte yang tersisa.
Pertanyaan yang Sering Diajukan
Bagaimana cara memuat dokumen tanpa opsi khusus?
Berikan jalur file atau Stream secara langsung ke Document(fileName) atau Document(stream) — LoadOptions hanya diperlukan ketika password, pengaturan khusus format, atau callback dibutuhkan.
Apa perbedaan antara LoadOptions, TxtLoadOptions, dan MarkdownLoadOptions?
TxtLoadOptions dan MarkdownLoadOptions keduanya diturunkan dari LoadOptions dan menambahkan pengaturan khusus untuk sumber teks biasa dan Markdown masing-masing. Setiap properti umum LoadOptions — password, encoding, callbacks — tetap tersedia pada kedua subclass.
Apakah saya dapat memuat dokumen langsung dari byte array?
Bungkus byte dalam MemoryStream dan berikan stream itu ke Document(stream) atau Document(stream, loadOptions) — tidak ada konstruktor yang menerima byte array secara langsung.
Bagaimana saya mengontrol apa yang terjadi ketika loader tidak dapat menyelesaikan sumber eksternal?
Implementasikan IResourceLoadingCallback dan tetapkan ke LoadOptions.ResourceLoadingCallback. Kembalikan ResourceLoadingAction.Skip dari ResourceLoading(args) untuk mengabaikan sumber daya alih-alih membiarkan pemuatan gagal.
Apakah mengatur RecoveryMode mengubah cara dokumen yang terbentuk dengan baik dimuat?
Tidak. DocumentRecoveryMode hanya mengubah perilaku ketika pemuat benar-benar menghadapi masalah struktural — dokumen yang terstruktur dengan baik dimuat dengan cara yang sama terlepas dari pengaturannya.
