Plugin Chuyển Đổi

Chuyển đổi tài liệu sang 45 định dạng mục tiêu

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à — tùy chọn — một widget nhúng 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.

Giao diệnKhi nào sử dụng
DocumentConverter (C#)Bạn chuyển đổi trên máy chủ, không có trình duyệt tham gia
Widget nhúng (doconutConverter.js)Bạn muốn một màn hình tải lên, chuyển đổi và tải xuống đã sẵn sàng trong trang của mình
Các endpoint HTTP (?convert=open|run|download)Bạn xây dựng UI chuyển đổi của riêng mình dựa trên hợp đồng máy chủ đã được tài liệu hoá

Cài đặt gói

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

bash
dotnet add package Doconut.NET8.Converter

Để cố định plugin vào phiên bản mà tài liệu này mô tả, truyền phiên bản riêng biệt:

bash
dotnet add package Doconut.NET8.Converter --version 26.10.0

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

Tệp giấy phép của plugin, Doconut.Viewer.Converter.lic, nằm trong cùng thư mục với Doconut.Viewer.lic; nó được đọc cùng với giấy phép của trình xem.

Nền tảng. Plugin chạy ở bất kỳ nơi nào Doconut.NET8 chạy: Windows và Linux dựa trên glibc trên kiến trúc x64 (không phải Alpine hay các bản phân phối dựa trên musl). Trên Linux, cài đặt thư viện cấu hình phông chữ trước khi mở tài liệu đầu tiên:

bash
apt-get update && apt-get install -y libfontconfig1

Trên RHEL, Fedora và các bản phân phối tương tự, gói là fontconfig. Nếu không có, việc mở tài liệu sẽ thất bại với The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Đăng ký plugin

Không có phương thức AddConverter() — mô hình plugin của Doconut là đồ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 của nó, Doconut.NET8.Converter, được cài đặt cùng với gói trình xem cơ bản.

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

Đó là tất cả những gì giao diện C# cần. Widget và các endpoint HTTP của nó là một tùy chọn riêng, AddConverterWidget() (xem Widget nhúng).

Plugin cần một giấy phép cung cấp khả năng Converter. Nếu không có, AddDoconut() sẽ ném một InvalidOperationException khi khởi động, trước khi ứng dụng phục vụ yêu cầu:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Nó sẽ ném lỗi khi không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Converter, và giấy phép trả phí được sử dụng ngoài khoảng thời gian phiên bản. Các giấy phép Demo/NFR tạm thời được chấp nhận. Không có cấp miễn phí ẩn. Xem Cài đặt giấy phép để biết cách tải giấy phép.

Cấp phép & watermark

Trạng thái giấy phépKhởi độngĐầu ra chuyển đổi
Giấy phép xem trả phí cung cấp Converter, trong khoảng thời gian phiên bảnBắt đầuSạch — watermarked: false
Giấy phép tạm thời (Demo/NFR) đang hoạt độngBắt đầuChuyển đổi, với watermark đánh giá — watermarked: true
Giấy phép tạm thời (Demo/NFR) đã hết hạnBắt đầuChuyển đổi, với watermark đánh giá — watermarked: true
Không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Converter, hoặc giấy phép trả phí ngoài khoảng thời gian phiên bảnAddDoconut() ném lỗi—

Cả hai đường gọi đều tính cờ dựa trên 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ử đầu‑cuối trên giấy phép đánh giá trước khi mua — chỉ có các byte đầu ra thay đổi.

Một nguồn DICOM (.dcm, .ima) cũng cần khả năng Dicom. Nếu không có, ConvertAsync ném một LicenseException (Converting '.dcm' requires the Dicom capability license.) và câu trả lời của open trong widget là 403.

Sử dụng từ C#

Mỗi lần chuyển đổi trả về một MemoryStream có thể tìm kiếm, được đặt ở vị trí 0, sẵn sàng để đọc hoặc sao chép ngay lập tức. Hãy giải quyết 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ể được tái sử dụng an toàn trong các yêu cầu.

csharp
// Tiêm DocumentConverter; hàm khởi tạo 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);
csharp
// sourceExtension bao gồm dấu chấm đầu tiên. password là null trừ khi tài liệu được bảo vệ.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: một Stream chứa HTML để chuyển lại thành tài liệu Word, chẳng hạn như kết quả của WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Hai chi tiết dễ bị nhầm lẫn: sourceExtension trên phiên bản overload của stream phải bao gồm dấu chấm đầu tiên (".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 thuần 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.

Người gọi sở hữu stream đã trả về 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ó được giải quyết từ dependency injection; không tự tạo hoặc giải phóng nó một cách thủ công.

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

ConversionTarget (namespace Doconut.Configs.Conversion) có 45 thành viên:

text
Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Không phải mọi nguồn đều chuyển đổi sang mọi mục tiêu — 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, DICOM) tới một tập hợp cố định các mục tiêu được phép. Chuyển đổi một nguồn DICOM (.dcm, .ima) cũng cần một giấy phép cho phép khả năng Dicom; các mục tiêu của nó là Pdf, Png, Jpeg, Bmp, Tiff và Gif. Đừng mã cứng enum này làm danh sách mục tiêu 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à thứ nên điều khiển bộ chọn.

Widget dạng plug‑in

Kích hoạt các endpoint

Các endpoint ?convert=open|run|download của widget là tùy chọn và mặc định bị vô hiệu hoá — 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:

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

AddConverterWidget() không có đối số sẽ kích hoạt widget với các giá trị mặc định (MaxUploadMb = 25). Nó không tự mình cấp quyền chuyển đổi: nó cần AddPlugin<ConverterPlugin>(), hoặc AddDoconut() sẽ gây ra ngoại lệ:

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

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ị hạn chế).

Nhúng nó

html
<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>

Doconut.convert(selectorOrElement, options) nhận một bộ chọn CSS hoặc một phần tử, ném lỗi nếu không tìm thấy mount, và trả về một đầu mối. Widget tải lên một tệp, hiển thị bản xem trước của trang 1, cho phép người dùng chọn một trong các allowedTargets, chuyển đổi, xem trước kết quả khi có thể, và cung cấp tùy chọn tải xuống.

Tùy chọn

Tùy chọnKiểuMặc địnhGhi chú
basePathstring/doconutĐường dẫn cơ sở cho các endpoint ?convert=; nó phải khớp với nhánh ASP.NET nơi UseDoconut() thực sự được gắn (thông thường được phối hợp qua MiddlewarePath)
resPathstring/doconut-resĐược chấp nhận để duy trì tính nhất quán cấu hình với các widget Doconut khác; widget chuyển đổi hiện không tạo bất kỳ URL nào từ nó
maxUploadMbnumber25Chỉ kiểm tra trước phía máy khách — từ chối tệp quá lớn trước khi tải lên. Máy chủ áp dụng giới hạn riêng của mình một cách độc lập và trả về 413 nếu vượt quá
licenseUrlstring | nullnullKhi được đặt, chuyển thông báo watermark trên màn hình kết quả thành một liên kết tới URL này
labelsobject{}Ghi đè bất kỳ tập con nào của các chuỗi mặc định tiếng Anh của widget (văn bản thả, nút, thông báo aria‑live, thông báo lỗi)

Các callback

CallbackKhi nào được kích hoạtDữ liệu
onReady()Widget đã hiển thị màn hình chờ/đổ—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open succeedstoken phiên nguồn, số trang, phần mở rộng nguồn (không có dấu chấm đầu), danh sách đích cho phép
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run succeedscác trường giống như phản hồi chạy, cộng thêm target được yêu cầu
onDownload({ downloadName, downloadToken })Người dùng nhấp vào liên kết Tải xuốngđược kích hoạt cùng với tải xuống gốc của trình duyệt — không chặn hay thay thế nó
onError({ phase, message })Một yêu cầu mở hoặc chạy thất bạiphase là 'open' hoặc 'run'; message là lỗi máy chủ đã được làm sạch (hoặc thông báo phía máy khách cho kiểm tra kích thước tải lên)

Một callback ném lỗi sẽ được bắt và ghi log; nó không bao giờ làm gián đoạn luồng của widget.

Xử lý bắt buộc

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

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // một File từ của bạn <input type="file" id="picker">
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; không thực hiện gì trừ khi hiện đang idle
conv.destroy();       // gỡ bỏ các listener, làm trống mount; đối tượng này không thể sử dụng được sau khi này

Nhãn

Mỗi chuỗi đều có mặc định tiếng Anh; labels ghi đè bất kỳ tập con nào và phần còn lại vẫn là tiếng Anh. Các đoạn thay đổi tại thời gian chạy sử dụng {placeholders}, chẳng hạn như uploading: 'Uploading {name}…' và pages: '{n} pages'.

KhóaMặc định tiếng Anh
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

Các khóa bổ sung bao gồm aria-label của vùng thả (dropAriaLabel), các văn bản xem trước alt (previewAlt, resultAlt), dạng liên kết của thông báo watermark được sử dụng với licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), một phản hồi không đọc được (badResponse) và các thông báo aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

Lỗi JSON từ máy chủ được hiển thị như máy chủ đã ghi; serverError chỉ được sử dụng khi phản hồi lỗi không chứa lỗi JSON, chẳng hạn như 404 của một widget bị vô hiệu hoá.

Tùy chỉnh giao diện

Tiện ích này thêm lớp dcw vào phần tử gắn kết của nó và đọc các màu, bán kính và phông chữ từ các thuộc tính tùy chỉnh CSS, vì vậy bạn có thể tùy chỉnh giao diện mà không cần can thiệp vào nội bộ của nó:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

Mặc định: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, và một phông chữ UI hệ thống cho --dcw-font.

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 — hã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 khác. Ba tuyến đường đều nằm dưới nhánh ASP.NET nơi UseDoconut() được gắn (thông thường là /doconut), và chúng trả lời 404 cho đến khi AddConverterWidget() được gọi. Lỗi mang theo một thân JSON, { "error": "..." }, ngoại trừ các trường hợp bảng ghi là "status only". Một giá trị ?convert= không biết sẽ trả lời 400.

TuyếnMục đíchPhản hồi thành công
POST ?convert=open (multipart, one file)Tải lên và mở tài liệu nguồn để xem trước200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>Chuyển đổi nguồn đã lưu thành target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>Phát luồng tệp đã chuyển đổi200 — file bytes, Content-Disposition: attachment, Cache-Control: no-store

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. allowedTargets liệt kê các tên mục tiêu viết thường ("pdf", "html", …); truyền một trong số chúng dưới dạng target, được so khớp không phân biệt chữ hoa chữ thường. open sử dụng tệp đầu tiên trong phần multipart.

resultToken là null, và resultPages là 0, khi kết quả không thể xem trước. downloadName là tên tệp nguồn với phần mở rộng của mục tiêu.

Các hình ảnh xem trước sử dụng tuyến đường hình ảnh trình xem tiêu chuẩn, {basePath}?token={token}&page=1&thumb=1&width={px}, với token từ open hoặc resultToken từ run. Tiện ích yêu cầu width=240.

Các byte nguồn đã tải lên được lưu trữ phía máy chủ và giữ trong 30 phút sau lần đọc cuối cùng; 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 một 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 trình xem thông thường để xem trước kết quả. Khi kết quả có thể xem trước, downloadToken và resultToken có cùng giá trị. Đóng kết quả trình xem không xóa kho tải xuống vẫn còn hiệu lực, và việc đặt lại tiện ích trình duyệt không kéo dài bất kỳ cửa sổ nào.

Các chế độ lỗi, được nhóm theo tuyến:

TuyếnTrạng tháiKhiNội dung
bất kỳ404Tiện ích không được bật (AddConverterWidget() chưa bao giờ được gọi) — được kiểm tra trước khi bất kỳ ba tuyến nào được xử lýchỉ trạng thái
bất kỳ405Phương thức HTTP sai (open/run yêu cầu POST; download yêu cầu GET)chỉ trạng thái
open400Không phải tải lên multipartExpected a multipart file upload.
open400Không có tệp, hoặc tệp rỗngNo file uploaded.
open400Phần mở rộng nguồn không thể chuyển đổiThis file type cannot be converted.
open403Loại tệp yêu cầu một khả năng mà giấy phép không cấp (tệp DICOM không có Dicom)Converting this file type requires the Dicom capability license.
open413Tệp đã tải lên vượt quá MaxUploadMb, được kiểm tra so với Content-Length và trong khi quá trình tải lên đang được đọcFile is too large.
run400Token không hợp lệ (không phải GUID)Invalid token.
run400Một target không phân tích được thành một ConversionTargetUnknown target format.
run400target không có trong allowedTargets của nguồnThat target format is not available for this file.
run404Tải lên đã lưu đã hết hạn hoặc token chưa bao giờ được mởUpload expired — please re-open the file.
open, run500Xử lý thất bại nội bộMột thông báo đã được làm sạch — được làm sạch theo cùng cách như mọi đường lỗi Doconut khác; không bao giờ tiết lộ chi tiết nội bộ
download400Token không hợp lệ (không phải GUID)chỉ trạng thái
download404Token tải xuống không xác định hoặc đã hết hạnchỉ trạng thái

Một vòng tròn hoàn chỉnh với fetch:

javascript
// file: Tệp để chuyển đổi, ví dụ từ một <input type="file">.
async function convertFile(file) {
  const base = '/doconut';

  // 1. open: tải lên tệp
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: chuyển đổi sang PDF khi được phép, nếu không thì sang mục tiêu đầu tiên được phép
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: một GET đơn giản mà trình duyệt có thể theo dõi
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Các điểm cuối là same-origin: phiên bản này không hỗ trợ CORS. Phục vụ UI và script tiện ích của bạn từ cùng một nguồn với Doconut, hoặc reverse-proxy cả hai đường dẫn /doconut (đường dẫn middleware và đường dẫn tài nguyên) dưới nguồn gốc UI của bạn.

Trong môi trường sản xuất

  1. Cài đặt plugin bên cạnh gói lõi, ở cùng phiên bản: dotnet add package Doconut.NET8.Converter.
  2. Thêm tệp giấy phép. Đặt Doconut.Viewer.Converter.lic trong cùng thư mục với Doconut.Viewer.lic.
  3. Đặt giới hạn máy chủ. MaxUploadMb trong AddConverterWidget là giới hạn mà máy chủ áp dụng; maxUploadMb của widget chỉ là kiểm tra phía máy khách. Giữ hai giá trị này bằng nhau.
  4. Phục vụ UI từ cùng nguồn như các endpoint Doconut, hoặc reverse-proxy chúng (xem Xây dựng giao diện của bạn).
  5. Giải phóng kết quả chuyển đổi. Luồng ConvertAsync trả về được gộp lại; giải phóng nó sẽ trả các bộ đệm về pool.

Cụm máy chủ web

Widget giữ mỗi tải lên và kết quả của nó trong bộ nhớ trên node đã phục vụ open. Đằng sau một load balancer không có sticky sessions, một yêu cầu run, download hoặc xem trước sau này có thể tới một node khác và không tìm thấy tải lên. Đăng ký kho widget được chia sẻ, được mã hoá một lần, sau AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // một thư mục mà mỗi nút có thể đọc và ghi
    store.FarmKey = farmKey;                   // ít nhất 32 byte, giống nhau trên mỗi nút
    // store.Ttl = TimeSpan.FromMinutes(30);   // thời gian một tệp tải lên được giữ (mặc định)
});
  • Một máy chủ đơn lẻ không cần gì: nếu không có lời gọi này, kho trong bộ nhớ sẽ được sử dụng.
  • Các tải lên và kết quả được mã hoá khi lưu trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được ràng buộc với token của nó, vì vậy một token không bao giờ có thể đọc tệp của token khác.
  • Trên chia sẻ, một tải lên hoặc một kết quả được giữ lại trong Ttl sau khi được ghi; việc đọc không kéo dài thời gian này.
  • FarmKey phải có ít nhất 32 byte và giống nhau trên mọi node. Tải nó từ kho bí mật; không bao giờ hard-code. Đăng ký sẽ ném một ArgumentException khi RootPath bị thiếu hoặc FarmKey ngắn hơn 32 byte.
  • Đặt RootPath tới cùng vị trí chia sẻ mà trình xem phân tán sử dụng.

Tham chiếu API

Facade và các tùy chọn widget nằm trong không gian tên Doconut; ConversionTarget nằm trong Doconut.Configs.Conversion. ConverterPlugin nằm trong Doconut.Plugins.Converter.

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

Được giải quyết từ dependency injection; constructor là internal. sourceExtension bao gồm dấu chấm đầu. HtmlToWordAsync ghi một tệp .doc khi outputFormat là ConversionTarget.Doc, và một tệp .docx cho bất kỳ giá trị nào khác.

ConversionTarget

45 định dạng đầu ra được liệt kê trong Định dạng mục tiêu.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

Đặt thông qua DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), trả về DoconutOptions để các lời gọi có thể được nối chuỗi.

Khắc phục sự cố

Triệu chứngNguyên nhânCách khắc phục
AddDoconut() ném The Converter plugin is registered via AddPlugin but no active license grants Converter.Không có giấy phép, một tệp TRIAL, một giấy phép không có Converter, hoặc một giấy phép trả phí ngoài khoảng thời gian phiên bản của nóCài đặt một giấy phép cho phép Converter, hoặc loại bỏ AddPlugin<ConverterPlugin>()
AddDoconut() ném AddConverterWidget() was called but the Converter plugin is not registered.Widget được bật mà không có plugin của nóThêm options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Giải quyết DocumentConverter ném No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin chưa được đăng kýThêm AddPlugin<ConverterPlugin>() bên trong AddDoconut()
Chuyển đổi luồng cho biết định dạng không được hỗ trợsourceExtension không có dấu chấm đầuTruyền ".xlsx", không phải "xlsx"
ConvertAsync ném Converting '.dcm' requires the Dicom capability license.Nguồn DICOM, và giấy phép không cho phép DicomSử dụng một giấy phép cho phép Dicom
Kết quả có dấu watermarkGiấy phép tạm thời (Demo/NFR)Sử dụng giấy phép trả phí cho phép Converter
Widget tải nhưng các yêu cầu trả về 404AddConverterWidget() chưa được gọi, hoặc basePath không khớp với nhánh mà UseDoconut() được gắnGọi AddConverterWidget(); sửa basePath
open trả lời 403 Converting this file type requires the Dicom capability license.Một tải lên DICOM, và giấy phép không cho phép DicomSử dụng giấy phép cho phép Dicom
open trả lời 413 File is too large.Tải lên vượt quá MaxUploadMbKhai báo MaxUploadMb trong AddConverterWidget; maxUploadMb của widget chỉ là kiểm tra phía máy khách
run trả lời 400 That target format is not available for this file.Mục tiêu không phải là một trong các allowedTargets của nguồnChỉ cung cấp allowedTargets từ open
run hoặc download trả lời 404 (Upload expired — please re-open the file. từ run)Cửa sổ 30 phút đã hết, hoặc một node trong web-farm không có tải lênMở lại tệp; trong một farm, đăng ký AddDoconutDistributedWidgets
Widget thất bại khi UI ở nguồn khácCác endpoint không hỗ trợ CORSPhục vụ UI từ cùng nguồn, hoặc reverse-proxy các đường dẫn Doconut
Theme không áp dụngCác biến được đặt trên một phần tử cha hoặc trên một phần tử bên trong mount; quy tắc .dcw riêng của widget đặt chúng trên mountNhắm tới chính mount: #doconut-convert.dcw hoặc #doconut-convert

Trang này có hữu ích không?