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ện | Khi 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:
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:
dotnet add package Doconut.NET8.Converter --version 26.10.0Giữ 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:
apt-get update && apt-get install -y libfontconfig1Trê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.
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:
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ép | Khở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ản | Bắt đầu | Sạch — watermarked: false |
| Giấy phép tạm thời (Demo/NFR) đang hoạt động | Bắt đầu | Chuyển đổi, với watermark đánh giá — watermarked: true |
| Giấy phép tạm thời (Demo/NFR) đã hết hạn | Bắt đầu | Chuyể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ản | AddDoconut() 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.
// 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);// 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);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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:
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, IcoKhô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:
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ệ:
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ó
<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ọn | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
basePath | string | /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) |
resPath | string | /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ó |
maxUploadMb | number | 25 | Chỉ 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á |
licenseUrl | string | null | null | Khi đượ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 |
labels | object | {} | 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
| Callback | Khi nào được kích hoạt | Dữ liệu |
|---|---|---|
onReady() | Widget đã hiển thị màn hình chờ/đổ | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open succeeds | token 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 succeeds | cá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ại | phase 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:
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àyNhã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óa | Mặc định tiếng Anh |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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ó:
#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ến | Mục đích | Phả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ước | 200 — { token, pages, sourceExt, allowedTargets } |
POST ?token=<token>&convert=run&target=<ext> | Chuyển đổi nguồn đã lưu thành target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | Phát luồng tệp đã chuyển đổi | 200 — 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ến | Trạng thái | Khi | Nội dung |
|---|---|---|---|
| bất kỳ | 404 | Tiệ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ỳ | 405 | Phương thức HTTP sai (open/run yêu cầu POST; download yêu cầu GET) | chỉ trạng thái |
open | 400 | Không phải tải lên multipart | Expected a multipart file upload. |
open | 400 | Không có tệp, hoặc tệp rỗng | No file uploaded. |
open | 400 | Phần mở rộng nguồn không thể chuyển đổi | This file type cannot be converted. |
open | 403 | Loạ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. |
open | 413 | Tệ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 đọc | File is too large. |
run | 400 | Token không hợp lệ (không phải GUID) | Invalid token. |
run | 400 | Một target không phân tích được thành một ConversionTarget | Unknown target format. |
run | 400 | target không có trong allowedTargets của nguồn | That target format is not available for this file. |
run | 404 | Tả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, run | 500 | Xử 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ộ |
download | 400 | Token không hợp lệ (không phải GUID) | chỉ trạng thái |
download | 404 | Token tải xuống không xác định hoặc đã hết hạn | chỉ trạng thái |
Một vòng tròn hoàn chỉnh với fetch:
// 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
- Cài đặt plugin bên cạnh gói lõi, ở cùng phiên bản:
dotnet add package Doconut.NET8.Converter. - Thêm tệp giấy phép. Đặt
Doconut.Viewer.Converter.lictrong cùng thư mục vớiDoconut.Viewer.lic. - Đặt giới hạn máy chủ.
MaxUploadMbtrongAddConverterWidgetlà giới hạn mà máy chủ áp dụng;maxUploadMbcủa widget chỉ là kiểm tra phía máy khách. Giữ hai giá trị này bằng nhau. - 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).
- Giải phóng kết quả chuyển đổi. Luồng
ConvertAsynctrả 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():
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
Ttlsau khi được ghi; việc đọc không kéo dài thời gian này. FarmKeyphả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ộtArgumentExceptionkhiRootPathbị thiếu hoặcFarmKeyngắn hơn 32 byte.- Đặt
RootPathtớ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
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
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ứng | Nguyên nhân | Cá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 đầu | Truyề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 Dicom | Sử dụng một giấy phép cho phép Dicom |
| Kết quả có dấu watermark | Giấ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ề 404 | AddConverterWidget() chưa được gọi, hoặc basePath không khớp với nhánh mà UseDoconut() được gắn | Gọ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 Dicom | Sử 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á MaxUploadMb | Khai 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ồn | Chỉ 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ên | Mở lại tệp; trong một farm, đăng ký AddDoconutDistributedWidgets |
| Widget thất bại khi UI ở nguồn khác | Các endpoint không hỗ trợ CORS | Phục vụ UI từ cùng nguồn, hoặc reverse-proxy các đường dẫn Doconut |
| Theme không áp dụng | Cá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 mount | Nhắm tới chính mount: #doconut-convert.dcw hoặc #doconut-convert |
Trang này có hữu ích không?