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 giao diện công cộng DocumentConverter, và — nếu chọn — một widget có thể chèn vào với 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 mà bạn tự viết.

Cài đặt gói

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

dotnet add package Doconut.NET8.Converter

Để cố định plugin vào 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.NET8.Converter --version 26.7.0

Giữ gói Converter ở cùng phiên bản với Doconut.NET8. ID gói là Doconut.NET8.Converter; .26.7.0 chỉ xuất hiện trong tên tệp .nupkg đã tải xuống.

Đă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 đăng ký theo 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.NET8.Converter, được cài đặt cùng với gói trình xem 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 legacy TRIAL, hoặc giấy phép không tạm thời không cung cấp khả năng Converter — một InvalidOperationException được phát sinh từ bên trong AddDoconut(), trước khi ứng dụng phục vụ yêu cầu. Đăng ký Demo/NFR tạm thời được chấp nhận; sau khi hết hạn theo lịch, việc chuyển đổi vẫn khả dụng với đầu ra có watermark. Không có mức miễn phí im lặng. 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, đặt vị trí 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 có trạng thái theo thiết kế, vì vậy một thể hiện duy nhất có thể tái sử dụng an toàn trong các yêu cầu.

// Tiêm DocumentConverter; constructor của nó là internal, vì vậy không bao giờ `new` nó.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension bao gồm dấu chấm đầu. password là null trừ khi tài liệu được bảo vệ.
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 trên overload stream phải bao gồm dấu chấm đầu tiên (".xlsx", không phải "xlsx") — trình 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 chuyển đổi 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, tài liệu web) tới bộ danh sách đích cố định của nó. Đừng mã cứng enum này làm danh sách đích cho UI của bạn: ?convert=open trả về allowedTargets thực tế cho bất kỳ tệp nào vừa được tải lên, và đó là gì nên điều khiển bộ chọn.

Tiện ích nhúng sẵn

Các endpoint ?convert=open|run|download của tiện ích được bật tùy chọn và bị vô hiệu hoá mặc định — an toàn 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 có AddConverterWidget(), ba endpoint ?convert= sẽ trả lời 404 — nhưng tệp JS vẫn được phục vụ bất kể (đó là một tài nguyên tĩnh nhúng thuần; chỉ các endpoint mà nó giao tiếp mới bị giới hạn). AddConverterWidget() vẫn yêu cầu plugin Converter được đăng ký và một giấy phép cho phép Converter — nó không tự động cấp quyền chuyển đổi.

Tùy chỉnh tiện ích

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

Các callback:

Doconut.convert() trả về chính thể hiện của tiện ích — giữ lại nó để điều khiển tiện ích bằng chương trình:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // quay lại màn hình idle/drop; 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; no-op trừ khi hiện đang idle
conv.destroy();       // gỡ bỏ các listeners, làm trống mount; instance không thể sử dụng được sau khi thực hiện

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

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

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

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

Các chế độ lỗi, 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 được đặt ở vị trí zero. Người gọi sở hữu luồng đó và nên giải phóng nó sau khi sao chép hoặc trả lại nội dung. Dịch vụ DocumentConverter tự nó không có trạng thái và được lấy từ dependency injection; không tự tạo hoặc giải phóng dịch vụ này một cách thủ công.

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

Khắc phục sự cố

Đánh dấu nước

Khi đã đăng ký ConverterPlugin, giấy phép của máy chủ nằm trong một trong ba trạng thái:

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