Plugin Chuyển Đổi

Plugin Converter biến Doconut thành một dịch vụ chuyển đổi tài liệu. Nó cung cấp động cơ phía sau façade công cộng DocumentConverter, và — khi bật — một widget tích hợp có hợp đồng HTTP riêng, cho phép bạn chuyển đổi tài liệu từ C#, từ widget, hoặc từ giao diện người dùng bạn tự viết.

Cài đặt gói

Cài đặt plugin Converter ổn định mới nhất:

dotnet add package Doconut.NET6.Converter

Để cố định plugin ở phiên bản 26.7.0 hiện tại, truyền phiên bản riêng biệt:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Giữ phiên bản gói Converter đồng nhất với Doconut.NET6. ID gói là Doconut.NET6.Converter; .26.7.0 chỉ xuất hiện trong tên tệp .nupkg đã tải về.

Đăng ký plugin

Không có phương thức AddConverter() — mô hình plugin của Doconut là thống nhất. Mọi plugin, bao gồm Converter, đều được đăng ký cùng một cách: gọi AddPlugin<TPlugin>() bên trong AddDoconut(). ConverterPlugin được cung cấp trong gói NuGet riêng, Doconut.NET6.Converter, được cài đặt cùng với gói viewer cơ bản.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Lệnh này sẽ ném lỗi khi khởi động nếu thiếu giấy phép, tệp TRIAL cũ, hoặc giấy phép không tạm thời không cấp quyền Converter — một InvalidOperationException được ném từ bên trong AddDoconut(), trước khi ứng dụng phục vụ các yêu cầu. Các đăng ký Demo/NFR tạm thời được chấp nhận; sau khi hết hạn, việc chuyển đổi vẫn khả dụng nhưng kết quả có dấu watermark. Không có cấp miễn phí âm thầm. Xem Cài đặt giấy phép để biết cách tải giấy phép.

Chuyển đổi từ C#

Mỗi lần chuyển đổi trả về một MemoryStream có thể tìm kiếm, vị trí đặt tại 0, sẵn sàng đọc hoặc sao chép ngay lập tức. Lấy DocumentConverter từ DI ở bất kỳ nơi nào bạn cần — nó không giữ trạng thái, vì vậy một thể hiện duy nhất có thể tái sử dụng an toàn giữa các yêu cầu.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Hai chi tiết dễ bị nhầm lẫn: sourceExtension trong overload cho stream phải bao gồm dấu chấm đầu (".xlsx", không phải "xlsx" ) — bộ chuyển đổi sẽ so sánh nó với danh mục định dạng và một phần mở rộng không có dấu chấm sẽ không được giải quyết. Và mặc dù tên gọi, WordToHtmlAsync trả về Task<Stream>, không phải Task<string> — bạn nhận được tài liệu HTML (hình ảnh được nhúng dưới dạng Base64) dưới dạng stream, giống như mọi kết quả chuyển đổi khác.

Định dạng mục tiêu

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Không phải mọi nguồn đều có thể chuyển sang mọi đích — plugin ánh xạ mỗi họ định dạng nguồn (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) sang một tập hợp cố định các đích được phép. Đừng hardcode enum này làm danh sách đích UI của bạn: ?convert=open trả về allowedTargets thực tế cho tệp vừa được tải lên, và đó là dữ liệu nên dùng để hiển thị bộ chọn.

Widget tích hợp

Các endpoint ?convert=open|run|download của widget là tùy chọn và mặc định bị tắt — bảo mật theo mặc định. Kích hoạt chúng phía máy chủ, cùng với việc đăng ký plugin:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Nếu không gọi AddConverterWidget(), ba endpoint ?convert= sẽ trả về 404 — nhưng tệp JS vẫn được phục vụ (đó là tài nguyên tĩnh nhúng; chỉ các endpoint mà nó giao tiếp mới bị chặn). AddConverterWidget() vẫn yêu cầu plugin Converter đã được đăng ký và một giấy phép cấp quyền Converter — nó không tự động cấp quyền chuyển đổi.

Tùy chỉnh widget

Các tùy chọn khởi tạo được truyền vào Doconut.convert(selector, options):

Callbacks:

Doconut.convert() trả về chính thể hiện widget — giữ lại để điều khiển widget một cách lập trình:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // quay lại màn hình chờ/thả; không kích hoạt lại onReady
conv.loadFile(file);  // bắt đầu luồng với một đối tượng File; không làm gì nếu không ở trạng thái chờ
conv.destroy();       // xóa các listener, dọn dẹp mount; thể hiện không còn sử dụng được sau khi này

Xây dựng giao diện người dùng của riêng bạn

Widget chỉ là một client cho hợp đồng HTTP này — bạn có thể xây dựng giao diện người dùng riêng trực tiếp dựa trên nó để có trải nghiệm UX khác. Cả ba route đều nằm dưới nhánh ASP.NET nơi UseDoconut() được gắn (thông thường là /doconut):

Các byte nguồn được lưu tạm phía máy chủ với TTL 30 phút; khi thời gian này hết, run trả về 404 và tệp phải được mở lại. Kết quả chuyển đổi cũng được lưu trong cùng kho — downloadToken có cửa sổ 30 phút mới khi chuyển đổi hoàn tất — trong khi resultToken là token phiên viewer thông thường, thời gian sống phụ thuộc vào bộ nhớ cache của viewer, độc lập với kho tạm.

sourceExt trong phản hồi open không có dấu chấm đầu (ví dụ "docx") — ngược lại với tham số sourceExtension của DocumentConverter.ConvertAsync, yêu cầu có dấu chấm.

Các chế độ lỗi, phân nhóm theo route

Quyền sở hữu tài nguyên

Bộ chuyển đổi trả về một MemoryStream có thể tìm kiếm, vị trí đặt tại zero. Người gọi sở hữu stream này và nên giải phóng nó sau khi sao chép hoặc trả về nội dung. Dịch vụ DocumentConverter tự nó không giữ trạng thái và được lấy từ dependency injection; không tự tạo hay giải phóng dịch vụ này một cách thủ công.

Đối với widget web, các kho tạm tải lên và tải xuống có TTL độc lập 30 phút. Một resultToken của viewer tuân theo thời gian sống của phiên viewer. Đóng kết quả viewer không xóa kho tạm tải xuống còn hiệu lực, và việc reset widget trong trình duyệt cũng không kéo dài bất kỳ TTL nào.

Khắc phục sự cố

Đánh dấu nước

Khi ConverterPlugin được đăng ký, giấy phép của host sẽ ở một trong ba trạng thái:

Cả hai đường gọi đều tính cờ này dựa trên cùng một quy tắc: facade C# DocumentConverter suy ra nội bộ từ trạng thái IsViewerLicensed và IsTemporary của giấy phép, và handler ?convert=run của widget thực hiện kiểm tra tương đương (IsViewerLicensed && !IsTrial && !IsTemporary) để điền trường watermarked trong phản hồi. Một tích hợp có thể được xây dựng và thử nghiệm end‑to‑end trên giấy phép đánh giá trước khi mua — chỉ có byte đầu ra thay đổi.