Tải Tài Liệu bằng LoadOptions

Tải tài liệu với LoadOptions

Hướng dẫn này cho thấy cách kiểm soát việc tải tài liệu vượt ra ngoài một đường dẫn tệp hoặc luồng thuần túy, bằng cách sử dụng lớp LoadOptions. Document có các overload của constructor chấp nhận một thể hiện LoadOptions — Document(fileName, loadOptions) và Document(stream, loadOptions) — vì vậy bất kỳ cài đặt nào được mô tả ở đây sẽ áp dụng tại thời điểm tải, trước khi đối tượng tài liệu được trả lại cho mã của bạn.

Lớp LoadOptions

LoadOptions mang các cài đặt Aspose.Words FOSS cần khi tải một tài liệu vào đối tượng Document. Các constructor của nó bao gồm một LoadOptions() không có tham số, LoadOptions(password) để mở trực tiếp tệp được bảo vệ bằng mật khẩu, và LoadOptions(loadFormat, password, baseUri) để chỉ định định dạng một cách rõ ràng. Ngoài Password và BaseUri (được dùng để giải quyết các tham chiếu tương đối như tài nguyên liên kết), LoadOptions cung cấp Encoding cho các định dạng dựa trên văn bản, TempFolder cho việc xử lý tài liệu lớn, MswVersion để chỉ định quy ước định dạng của phiên bản Word nào áp dụng, và UpdateDirtyFields, IgnoreOleData, và UseSystemLcid để kiểm soát chi tiết hơn hành vi tải. LoadOptions.FontSettings cho phép bạn cung cấp FontSettings tại thời điểm tải thay vì chỉ cấu hình phông chữ sau khi tài liệu đã được tải.

Các tùy chọn tải theo định dạng

Một số định dạng có lớp con LoadOptions riêng của chúng, tiết lộ các cài đặt đặc thù cho định dạng đó. TxtLoadOptions (cho văn bản thuần) bổ sung AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection, và các LeadingSpacesOptions/TrailingSpacesOptions riêng biệt kiểu TxtLeadingSpacesOptions/TxtTrailingSpacesOptions để kiểm soát cách xử lý khoảng trắng đầu và cuối mỗi dòng. MarkdownLoadOptions thêm PreserveEmptyLines, ImportUnderlineFormatting, và SoftLineBreakCharacter để kiểm soát cách các quy ước ngắt dòng của Markdown được ánh xạ vào các đoạn và run trong tài liệu. Cả hai lớp con đều kế thừa mọi thuộc tính LoadOptions chung, vì vậy một mật khẩu hoặc callback tải tài nguyên được đặt trên một thể hiện TxtLoadOptions hoặc MarkdownLoadOptions sẽ hoạt động giống như trên lớp cơ sở.

Các callback tải tài nguyên

LoadOptions.ResourceLoadingCallback chấp nhận một triển khai của IResourceLoadingCallback, được thông báo khi bộ tải giải quyết các tài nguyên bên ngoài được tham chiếu bởi tài liệu đang được tải. Callback nhận một ResourceLoadingArgs mô tả ResourceType của tài nguyên đang được tải, và trả về một ResourceLoadingAction để cho bộ tải biết nên tải tài nguyên bình thường, bỏ qua, hay thay thế bằng dữ liệu tùy chỉnh. Đây là điểm mở rộng để kiểm soát hoặc can thiệp vào việc giải quyết tài nguyên trong quá trình tải, không phụ thuộc vào định dạng nào đang được đọc.

Cài đặt Ngôn ngữ, Hướng và Khôi phục

LoadOptions.LanguagePreferences là một đối tượng LanguagePreferences có DefaultEditingLanguage (một giá trị enum EditingLanguage) thiết lập ngôn ngữ Aspose.Words FOSS giả định khi tài liệu không chỉ định rõ ràng; AddEditingLanguage(language) và AddEditingLanguages(languages) đăng ký các ngôn ngữ bổ sung mà tài liệu có thể sử dụng. DocumentDirection (cũng được phơi bày trực tiếp trên TxtLoadOptions) là một enum với các giá trị LeftToRight, RightToLeft, và Auto để kiểm soát hướng luồng văn bản khi tải. LoadOptions.RecoveryMode nhận một giá trị DocumentRecoveryMode, điều này kiểm soát cách bộ tải phản hồi khi gặp tài liệu bị lỗi cấu trúc hoặc một phần hỏng.

Callbacks Tiến độ và Cảnh báo

Ngoài việc tải tài nguyên, LoadOptions.WarningCallback và LoadOptions.ProgressCallback chấp nhận các triển khai callback được thông báo về các vấn đề không nghiêm trọng gặp phải trong quá trình tải và về tiến độ tải, tương ứng — hữu ích để đưa ra các vấn đề có thể phục hồi cho mã gọi hoặc báo cáo tiến độ trên tài liệu lớn mà không cần polling.

Mẹo và Thực hành Tốt nhất

• Truyền LoadOptions(password) (hoặc đặt LoadOptions.Password) thay vì bắt ngoại lệ tải và thử lại — Aspose.Words FOSS cần mật khẩu trước khi có thể phân tích tài liệu.
• Đặt LanguagePreferences.DefaultEditingLanguage khi tải các tài liệu mà siêu dữ liệu ngôn ngữ bị thiếu hoặc không đáng tin, để các xử lý phụ thuộc vào ngôn ngữ phía sau hoạt động một cách dự đoán được.
• Ưu tiên lớp tùy chọn riêng cho định dạng (TxtLoadOptions, MarkdownLoadOptions) hơn lớp cơ sở LoadOptions khi tải các định dạng đó, vì lớp con cụ thể cung cấp các cài đặt liên quan đến định dạng mà lớp cơ sở không có.
• Triển khai IResourceLoadingCallback khi bạn cần chuyển hướng, lưu vào bộ nhớ đệm hoặc chặn việc phân giải tài nguyên bên ngoài trong quá trình tải thay vì sau khi tài liệu đã có trong bộ nhớ.
• Đặt LoadOptions.RecoveryMode một cách có chủ ý cho các pipeline xử lý tài liệu từ nguồn không tin cậy hoặc bên thứ ba, thay vì dựa vào hành vi khôi phục mặc định.

Các vấn đề thường gặp

FAQ

Làm thế nào để tải tài liệu có bảo vệ bằng mật khẩu?

Tạo LoadOptions với mật khẩu — new LoadOptions(password) — hoặc đặt LoadOptions.Password, sau đó truyền nó cho new Document(fileName, loadOptions) hoặc new Document(stream, loadOptions).

Tôi có cần một lớp con LoadOptions riêng cho định dạng không, hay lớp cơ sở đã đủ?

Lớp LoadOptions cơ bản bao phủ các thiết lập chung cho mọi định dạng (mật khẩu, mã hoá, callbacks). Sử dụng một lớp con đặc thù cho định dạng như TxtLoadOptions hoặc MarkdownLoadOptions khi bạn cần các thiết lập riêng cho định dạng đó, chẳng hạn xử lý khoảng trắng cho tệp văn bản hoặc quy tắc ngắt dòng cho Markdown.

Làm thế nào để tôi chặn hoặc chuyển hướng các tài nguyên mà tài liệu tham chiếu khi đang tải?

Triển khai IResourceLoadingCallback và gán nó cho LoadOptions.ResourceLoadingCallback trước khi tải. Callback nhận một ResourceLoadingArgs cho mỗi tài nguyên và trả về một ResourceLoadingAction quyết định cách bộ tải tiếp tục.

Làm sao tôi có thể kiểm soát ngôn ngữ mà Aspose.Words FOSS cho rằng cho một tài liệu đã tải?

Đặt LoadOptions.LanguagePreferences.DefaultEditingLanguage thành một giá trị EditingLanguage trước khi tải; sử dụng AddEditingLanguage/AddEditingLanguages để đăng ký các ngôn ngữ bổ sung mà tài liệu có thể chứa.

Điều gì sẽ xảy ra nếu bộ tải gặp phải một tài liệu bị hỏng?

Hành vi được kiểm soát bởi LoadOptions.RecoveryMode, một giá trị DocumentRecoveryMode xác định cách bộ tải phản hồi với các vấn đề cấu trúc trong tài liệu nguồn.

API Reference Tóm tắt

Xem thêm

• Aspose.Words for .NET — Enterprise Documentation