Memuat Dokumen dengan LoadOptions

Panduan ini menunjukkan cara mengontrol pemuatan dokumen di luar jalur file atau aliran sederhana, menggunakan kelas LoadOptions. Document memiliki overload konstruktor yang menerima instance LoadOptions — Document(fileName, loadOptions) dan Document(stream, loadOptions) — sehingga semua pengaturan yang dijelaskan di sini berlaku pada saat pemuatan, sebelum objek dokumen dikembalikan ke kode Anda.

Kelas LoadOptions

LoadOptions membawa pengaturan Aspose.Words yang diperlukan FOSS saat memuat dokumen ke dalam objek Document. Konstruktornya termasuk LoadOptions() tanpa parameter, LoadOptions(password) untuk membuka file yang dilindungi kata sandi secara langsung, dan LoadOptions(loadFormat, password, baseUri) untuk menentukan format secara eksplisit. Selain Password dan BaseUri (digunakan untuk menyelesaikan referensi relatif seperti sumber daya yang ditautkan), LoadOptions mengekspos Encoding untuk format berbasis teks, TempFolder untuk pemrosesan dokumen besar, MswVersion untuk menentukan konvensi format versi Word yang berlaku, serta UpdateDirtyFields, IgnoreOleData, dan UseSystemLcid untuk kontrol yang lebih halus atas perilaku pemuatan. LoadOptions.FontSettings memungkinkan Anda menyediakan FontSettings pada saat pemuatan alih-alih mengonfigurasi font hanya setelah dokumen dimuat.

Opsi Muat Spesifik Format

Beberapa format memiliki subclass LoadOptions mereka sendiri yang menampilkan pengaturan khusus untuk format tersebut. TxtLoadOptions (untuk teks biasa) menambahkan AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection, dan LeadingSpacesOptions/TrailingSpacesOptions terpisah bertipe TxtLeadingSpacesOptions/TxtTrailingSpacesOptions untuk mengontrol bagaimana spasi putih di awal dan akhir setiap baris ditangani. MarkdownLoadOptions menambahkan PreserveEmptyLines, ImportUnderlineFormatting, dan SoftLineBreakCharacter untuk mengontrol bagaimana konvensi jeda baris Markdown dipetakan ke paragraf dan run dokumen. Kedua subclass mewarisi setiap properti umum LoadOptions, sehingga kata sandi atau callback pemuatan sumber daya yang ditetapkan pada instance TxtLoadOptions atau MarkdownLoadOptions berperilaku sama seperti pada kelas dasar.

Callback Pemuatan Sumber Daya

LoadOptions.ResourceLoadingCallback menerima implementasi dari IResourceLoadingCallback, yang diberitahukan saat pemuat menyelesaikan sumber eksternal yang dirujuk oleh dokumen yang sedang dimuat. Callback menerima sebuah ResourceLoadingArgs yang menggambarkan ResourceType dari sumber yang dimuat, dan mengembalikan sebuah ResourceLoadingAction untuk memberi tahu pemuat apakah harus memuat sumber secara normal, melewatinya, atau mengganti dengan data khusus. Ini adalah titik ekstensi untuk mengendalikan atau menyela resolusi sumber selama pemuatan, terlepas dari format apa yang dibaca.

Pengaturan Bahasa, Arah, dan Pemulihan

LoadOptions.LanguagePreferences adalah objek LanguagePreferences yang DefaultEditingLanguage-nya (nilai enum EditingLanguage) menentukan bahasa Aspose.Words yang diasumsikan oleh FOSS ketika sebuah dokumen tidak secara eksplisit menyebutkannya; AddEditingLanguage(language) dan AddEditingLanguages(languages) mendaftarkan bahasa tambahan yang dapat dipakai dokumen. DocumentDirection (juga tersedia langsung pada TxtLoadOptions) adalah sebuah enum dengan nilai LeftToRight, RightToLeft, dan Auto untuk mengendalikan arah aliran teks saat pemuatan. LoadOptions.RecoveryMode menerima nilai DocumentRecoveryMode, yang mengatur bagaimana pemuat merespons ketika menemukan dokumen yang rusak atau sebagian korup.

Callback Progres dan Peringatan

Selain pemuatan sumber daya, LoadOptions.WarningCallback dan LoadOptions.ProgressCallback menerima implementasi callback yang diberitahukan tentang masalah non-fatal yang ditemui saat pemuatan dan tentang progres pemuatan, masing-masing — berguna untuk menampilkan masalah yang dapat dipulihkan ke kode pemanggil atau melaporkan progres pada dokumen besar tanpa polling.

Tips dan Praktik Terbaik

Berikan LoadOptions(password) (atau atur LoadOptions.Password) alih-alih menangkap pengecualian pemuatan dan mencoba lagi — Aspose.Words FOSS memerlukan kata sandi sebelum dapat mem-parsing dokumen sama sekali.
Atur LanguagePreferences.DefaultEditingLanguage saat memuat dokumen yang metadata bahasanya hilang atau tidak dapat diandalkan, sehingga pemrosesan turun-bawah yang bergantung pada bahasa berperilaku secara dapat diprediksi.
Lebih pilih kelas opsi khusus format (TxtLoadOptions, MarkdownLoadOptions) dibandingkan kelas dasar LoadOptions saat memuat format tersebut, karena subclass khusus tersebut menampilkan pengaturan yang relevan dengan format yang tidak ada pada kelas dasar.
Gunakan IResourceLoadingCallback ketika Anda perlu mengarahkan ulang, menyimpan cache, atau memblokir resolusi sumber daya eksternal selama pemuatan, bukan setelah dokumen sudah berada di memori.
Tetapkan LoadOptions.RecoveryMode secara sengaja untuk pipeline yang memproses dokumen dari sumber yang tidak terpercaya atau pihak ketiga, alih-alih mengandalkan perilaku pemulihan default.

Masalah Umum

Masalah	Penyebab	Perbaikan
Memuat dokumen yang dilindungi kata sandi menghasilkan pengecualian	Tidak ada kata sandi yang diberikan, atau kata sandi diberikan setelah proses pemuatan sudah dimulai	Berikan `LoadOptions(password)` (atau atur `Password` pada instance `LoadOptions`) ke overload konstruktor `Document` yang menerima `LoadOptions`
Spasi putih di awal/akhir dalam file teks yang dimuat tidak ditangani seperti yang diharapkan	Perilaku default `TxtLeadingSpacesOptions`/`TxtTrailingSpacesOptions` tidak sesuai dengan konvensi spasi putih pada file sumber	Set `TxtLoadOptions.LeadingSpacesOptions` / `TrailingSpacesOptions` secara eksplisit
Baris jeda Markdown tidak sesuai dengan struktur paragraf yang diharapkan	`MarkdownLoadOptions.PreserveEmptyLines` atau `SoftLineBreakCharacter` tidak sesuai dengan konvensi Markdown sumber	Sesuaikan properti `MarkdownLoadOptions` yang relevan sebelum memuat
Pemuat sumber daya eksternal tidak teramati atau dapat dikendalikan	Tidak ada `IResourceLoadingCallback` yang terdaftar pada `LoadOptions.ResourceLoadingCallback`	Implementasikan `IResourceLoadingCallback` dan tetapkan sebelum memuat

FAQ

Bagaimana cara memuat dokumen yang dilindungi kata sandi?

Bangun LoadOptions dengan kata sandi — new LoadOptions(password) — atau atur LoadOptions.Password, kemudian kirimkan ke new Document(fileName, loadOptions) atau new Document(stream, loadOptions).

Apakah saya memerlukan subclass `LoadOptions` khusus format, ataukah kelas dasar sudah cukup?

Kelas dasar LoadOptions mencakup pengaturan yang umum untuk setiap format (kata sandi, enkoding, callback). Gunakan subclass khusus format seperti TxtLoadOptions atau MarkdownLoadOptions ketika Anda memerlukan pengaturan khusus untuk format tersebut, seperti penanganan spasi putih untuk file teks atau konvensi pemutus baris untuk Markdown.

Bagaimana cara saya mencegat atau mengarahkan ulang sumber daya yang direferensikan dokumen saat dimuat?

Implementasikan IResourceLoadingCallback dan tetapkan ke LoadOptions.ResourceLoadingCallback sebelum memuat. Callback menerima sebuah ResourceLoadingArgs per sumber daya dan mengembalikan sebuah ResourceLoadingAction yang menentukan bagaimana loader melanjutkan.

Bagaimana saya mengontrol bahasa apa yang diasumsikan oleh Aspose.Words FOSS untuk dokumen yang dimuat?

Setel LoadOptions.LanguagePreferences.DefaultEditingLanguage ke nilai EditingLanguage sebelum memuat; gunakan AddEditingLanguage/AddEditingLanguages untuk mendaftarkan bahasa tambahan yang mungkin terdapat dalam dokumen.

Apa yang terjadi jika loader menemukan dokumen yang tidak terformat dengan benar?

Perilaku dikendalikan oleh LoadOptions.RecoveryMode, sebuah nilai DocumentRecoveryMode yang menentukan bagaimana loader merespons masalah struktural dalam dokumen sumber.

API Reference Ringkasan

Kelas/Metode	Deskripsi
`LoadOptions`	Objek opsi dasar yang mengontrol bagaimana dokumen dimuat
`Document(fileName, loadOptions)` / `Document(stream, loadOptions)`	Overload konstruktor yang menerapkan `LoadOptions` saat memuat
`TxtLoadOptions`	Muat opsi khusus untuk dokumen teks polos
`MarkdownLoadOptions`	Muat opsi khusus untuk dokumen Markdown
`IResourceLoadingCallback`	Antarmuka callback untuk mencegat resolusi sumber daya eksternal selama pemuatan
`ResourceLoadingArgs` / `ResourceLoadingAction`	Data per-sumber daya acara dan aksi yang dikembalikan ke pemuat
`LanguagePreferences`	Mengonfigurasi bahasa penyuntingan default dan tambahan yang diasumsikan saat dimuat
`DocumentDirection`	Enum yang mengontrol arah aliran teks (`LeftToRight`, `RightToLeft`, `Auto`)
`DocumentRecoveryMode`	Mengontrol perilaku pemuat ketika dokumen rusak

Lihat Juga

Aspose.Words for .NET — Enterprise Documentation

Memuat Dokumen dengan LoadOptions