ปลั๊กอินแปลงไฟล์
แปลงเอกสารเป็น 45 รูปแบบเป้าหมาย
ปลั๊กอิน Converter ทำให้ Doconut กลายเป็นบริการแปลงเอกสาร มันเป็นส่วนที่ทำงานเป็นเอนจินเบื้องหลัง façade สาธารณะ DocumentConverter และ — หากเลือกใช้ — วิดเจ็ตดรอปอินที่มีสัญญา HTTP ของตนเอง เพื่อให้คุณสามารถแปลงเอกสารจาก C#, จากวิดเจ็ต, หรือจากส่วนหน้า (frontend) ที่คุณเขียนเองได้.
| ส่วน | ใช้เมื่อใด |
|---|---|
DocumentConverter (C#) | คุณทำการแปลงบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
Drop-in widget (doconutConverter.js) | คุณต้องการหน้าจออัปโหลด, แปลงและดาวน์โหลดที่พร้อมใช้งานในหน้าของคุณ |
HTTP endpoints (?convert=open|run|download) | คุณสร้าง UI การแปลงของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย |
ติดตั้งแพคเกจ
ติดตั้งปลั๊กอิน Converter รุ่นเสถียรล่าสุด:
dotnet add package Doconut.NET8.Converterเพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับรุ่นที่เอกสารนี้อธิบาย, ส่งเวอร์ชันแยกต่างหาก:
dotnet add package Doconut.NET8.Converter --version 26.10.0รักษาแพคเกจ Converter ให้เป็นเวอร์ชันเดียวกับ Doconut.NET8. ID ของแพคเกจคือ
Doconut.NET8.Converter; .<version> ปรากฏเฉพาะในชื่อไฟล์ .nupkg ที่ดาวน์โหลด.
ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Converter.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; มันจะถูกอ่านพร้อมกับใบอนุญาตของ viewer.
แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET8 ทำงาน: Windows, และ Linux ที่ใช้ glibc บน x64 (ไม่ใช่ Alpine หรือดิสทริบิวชันที่ใช้ musl อื่นๆ) บน Linux, ให้ติดตั้งไลบรารีการกำหนดค่าแบบอักษรก่อนที่เอกสารแรกจะเปิด:
apt-get update && apt-get install -y libfontconfig1บน RHEL, Fedora และดิสทริบิวชันที่คล้ายกัน แพคเกจคือ fontconfig. หากไม่มีมัน การเปิดเอกสารจะล้มเหลวด้วย The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
ลงทะเบียนปลั๊กอิน
ไม่มีวิธี AddConverter() — โมเดลปลั๊กอินของ Doconut มีความสม่ำเสมอ ทุกปลั๊กอินรวมถึง Converter จะลงทะเบียนในลักษณะเดียวกัน: เรียก AddPlugin<TPlugin>() ภายใน AddDoconut(). ConverterPlugin มาพร้อมกับแพคเกจ NuGet ของตนเอง, Doconut.NET8.Converter, ที่ติดตั้งพร้อมกับแพคเกจ viewer พื้นฐาน.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});นั่นคือทั้งหมดที่ façade ของ C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddConverterWidget() (ดู วิดเจ็ตดรอปอิน).
ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Converter. หากไม่มี, AddDoconut() จะโยน InvalidOperationException ที่การเริ่มต้น, ก่อนที่แอปจะให้บริการคำขอ:
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.มันจะโยนข้อผิดพลาดเมื่อไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ไม่มี Converter, และใบอนุญาตแบบชำระเงินที่ใช้เกินช่วงเวอร์ชัน. ใบอนุญาต Demo/NFR ชั่วคราวจะได้รับการยอมรับ. ไม่มีระดับฟรีแบบเงียบ. ดู การตั้งค่าใบอนุญาต สำหรับวิธีการโหลดใบอนุญาต.
การให้ใบอนุญาต & ลายน้ำ
| สถานะใบอนุญาต | การเริ่มต้น | ผลลัพธ์การแปลง |
|---|---|---|
ใบอนุญาต viewer แบบชำระเงินที่ให้สิทธิ Converter, ภายในช่วงเวอร์ชันของมัน | เริ่มทำงาน | สะอาด — watermarked: false |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่ใช้งานอยู่ | เริ่มทำงาน | แปลง, พร้อมลายน้ำการประเมิน — watermarked: true |
| ใบอนุญาตชั่วคราว (Demo/NFR) ที่หมดอายุ | เริ่มทำงาน | แปลง, พร้อมลายน้ำการประเมิน — watermarked: true |
ไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมัน | AddDoconut() โยนข้อผิดพลาด | — |
เส้นทางการเรียกใช้ทั้งสองคำนวณแฟล็กจากกฎเดียวกัน: façade C# ของ DocumentConverter สร้างขึ้นจากภายในโดยอิงจากสถานะ IsViewerLicensed และ IsTemporary ของใบอนุญาต, และตัวจัดการ ?convert=run ของวิดเจ็ตทำการตรวจสอบเทียบเท่า (IsViewerLicensed && !IsTrial && !IsTemporary) เพื่อเติมฟิลด์ watermarked ที่มันส่งคืน. การบูรณาการสามารถสร้างและทดสอบแบบครบวงจรบนใบอนุญาตการประเมินก่อนซื้อ — เพียงแค่ไบต์ผลลัพธ์ที่เปลี่ยนแปลง.
แหล่ง DICOM (.dcm, .ima) ยังต้องการความสามารถ Dicom. หากไม่มี, ConvertAsync จะโยน LicenseException (Converting '.dcm' requires the Dicom capability license.) และ open ของวิดเจ็ตตอบกลับด้วย 403.
ใช้จาก C#
การแปลงแต่ละครั้งจะคืนค่า MemoryStream ที่สามารถเลื่อนตำแหน่งได้โดยตั้งที่ 0 พร้อมให้อ่านหรือคัดลอกได้ทันที. แก้ไข DocumentConverter จาก DI ที่ใดก็ได้ที่คุณต้องการ — มันไม่มีสถานะตามการออกแบบ ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้งานซ้ำหลายคำขอ.
// Inject DocumentConverter; ตัวสร้างของมันเป็น internal ดังนั้นห้าม `new` มัน
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension มีจุดนำหน้าอยู่. password จะเป็น null เว้นแต่เอกสารถูกป้องกัน
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: Stream ที่ถือ HTML เพื่อแปลงกลับเป็นเอกสาร Word, เช่นผลลัพธ์ของ WordToHtmlAsync
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);สองรายละเอียดที่ง่ายต่อการทำผิด: sourceExtension บน overload ของสตรีมต้องรวมจุดนำหน้า (".xlsx", ไม่ใช่ "xlsx") — ตัวแปลงจะจับคู่กับแคตาล็อกฟอร์แมตและส่วนขยายเปล่า ๆ จะไม่สามารถแก้ได้. และแม้ชื่อจะบ่งบอก, WordToHtmlAsync คืนค่า Task<Stream>, ไม่ใช่ Task<string> — คุณจะได้เอกสาร HTML (รูปภาพฝังเป็น Base64) เป็นสตรีม, เช่นเดียวกับผลลัพธ์การแปลงอื่น ๆ ทุกกรณี.
ผู้เรียกใช้เป็นเจ้าของสตรีมที่คืนค่าและควรทำการ dispose หลังจากคัดลอกหรือส่งคืนเนื้อหา. เซอร์วิส DocumentConverter เองถูกแก้จาก dependency injection; อย่าสร้างหรือทำการ dispose ด้วยตนเอง.
ฟอร์แมตเป้าหมาย
ConversionTarget (namespace Doconut.Configs.Conversion) มีสมาชิกทั้งหมด 45 รายการ:
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ไม่ใช่ทุกแหล่งจะสามารถแปลงเป็นทุกเป้าหมาย — ปลั๊กอินจะแมปแต่ละตระกูลฟอร์แมตของแหล่ง (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, เอกสารเว็บ, DICOM) ไปยังชุดเป้าหมายที่กำหนดไว้ของมันเอง. การแปลงแหล่ง DICOM (.dcm, .ima) ยังต้องการใบอนุญาตที่ให้ความสามารถ Dicom; เป้าหมายของมันคือ Pdf, Png, Jpeg, Bmp, Tiff และ Gif. อย่า hardcode enum นี้เป็นรายการเป้าหมายของ UI ของคุณ: ?convert=open คืนค่า allowedTargets ที่แท้จริงสำหรับไฟล์ที่เพิ่งอัปโหลดและนั่นคือสิ่งที่ควรใช้เป็นตัวกำหนดตัวเลือก.
วิดเจ็ตแบบ Drop-in
เปิดใช้งาน endpoints
Endpoints ?convert=open|run|download ของวิดเจ็ตเป็นแบบ opt-in และถูกปิดใช้งานโดยค่าเริ่มต้น — ปลอดภัยโดยค่าเริ่มต้น. เปิดใช้งานพวกมันบนเซิร์ฟเวอร์พร้อมกับการลงทะเบียนปลั๊กอิน:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});AddConverterWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น (MaxUploadMb = 25). มันไม่ได้ให้สิทธิ์การแปลงโดยตัวเอง: มันต้องการ AddPlugin<ConverterPlugin>(), หรือ AddDoconut() จะทำการ throw:
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.หากไม่มี AddConverterWidget(), สาม endpoints ?convert= จะตอบกลับด้วย 404 — แต่ไฟล์ JS เองยังคงให้บริการอยู่ (เป็นทรัพยากรสแตติกที่ฝังอยู่; มีเพียง endpoints ที่มันสื่อสารที่ถูกจำกัด).
ฝังวิดเจ็ต
<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) รับ CSS selector หรือ element, จะ throw หากไม่พบ mount, และคืนค่า handle. วิดเจ็ตอัปโหลดไฟล์, แสดงตัวอย่างของหน้า 1, ให้ผู้ใช้เลือกหนึ่งใน allowedTargets, ทำการแปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอให้ดาวน์โหลด.
ตัวเลือก
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | /doconut | เส้นทางฐานสำหรับ endpoint ของ ?convert=; ต้องตรงกับสาขา ASP.NET ที่ UseDoconut() ถูกเมานท์จริง (โดยปกติประสานงานผ่าน MiddlewarePath) |
resPath | string | /doconut-res | ยอมรับเพื่อความสอดคล้องของการกำหนดค่ากับวิดเจ็ต Doconut อื่น ๆ; วิดเจ็ตแปลงยังไม่ได้สร้าง URL ใด ๆ จากค่าเหล่านี้ |
maxUploadMb | number | 25 | ตรวจสอบล่วงหน้าที่ฝั่งไคลเอนต์เท่านั้น — ปฏิเสธไฟล์ที่ใหญ่เกินขนาดก่อนอัปโหลด. เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเองอย่างอิสระและตอบกลับ 413 หากเกิน |
licenseUrl | string | null | null | เมื่อกำหนดค่า จะเปลี่ยนข้อความลายน้ำบนหน้าจอผลลัพธ์ให้เป็นลิงก์ไปยัง URL นี้ |
labels | object | {} | แทนที่ส่วนใดส่วนหนึ่งของสตริงค่าเริ่มต้นภาษาอังกฤษของวิดเจ็ต (ข้อความลากลง, ปุ่ม, การประกาศ aria-live, ข้อความแสดงข้อผิดพลาด) |
คอลแบ็ก
| คอลแบ็ก | เกิดขึ้นเมื่อ | ข้อมูลที่ส่ง |
|---|---|---|
onReady() | วิดเจ็ตได้แสดงหน้าจอว่าง/ลากลง | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open succeeds | โทเคนเซสชันของแหล่ง, จำนวนหน้า, ส่วนขยายของแหล่ง (ไม่มีจุดนำหน้า), รายการเป้าหมายที่อนุญาต |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run succeeds | ฟิลด์เดียวกันกับการตอบสนองการทำงาน, พร้อมกับ target ที่ร้องขอ |
onDownload({ downloadName, downloadToken }) | ผู้ใช้คลิกลิงก์ดาวน์โหลด | ทำงานพร้อมกับการดาวน์โหลดตามปกติของเบราว์เซอร์ — ไม่ดักจับหรือแทนที่ |
onError({ phase, message }) | การร้องขอเปิดหรือทำงานล้มเหลว | phase คือ 'open' หรือ 'run'; message คือข้อผิดพลาดจากเซิร์ฟเวอร์ที่ทำความสะอาดแล้ว (หรือข้อความจากไคลเอนต์สำหรับการตรวจสอบขนาดอัปโหลดล่วงหน้า) |
คอลแบ็กที่เกิดข้อยกเว้นจะถูกจับและบันทึก; มันไม่ทำให้การทำงานของวิดเจ็ตหยุด
ตัวจัดการเชิงบังคับ
Doconut.convert() คืนค่าอินสแตนซ์ของวิดเจ็ตเอง — เก็บไว้เพื่อควบคุมวิดเจ็ตด้วยโปรแกรม:
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // ไฟล์จาก <input type="file" id="picker"> ของคุณเอง
conv.reset(); // กลับไปที่หน้าจอว่าง/ปล่อย; ไม่ทำการเรียก onReady อีกครั้ง
conv.loadFile(file); // เริ่มกระบวนการด้วยอ็อบเจ็กต์ File; ไม่ทำอะไรหากไม่ได้อยู่ในสถานะว่าง
conv.destroy(); // ลบ listener, ทำให้ mount ว่าง; อินสแตนซ์จะไม่สามารถใช้ได้หลังจากนี้ป้ายกำกับ
ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels แทนที่ส่วนใดส่วนหนึ่งและส่วนที่เหลือคงเป็นภาษาอังกฤษ. ส่วนที่เปลี่ยนแปลงในขณะทำงานใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.
| คีย์ | ค่าเริ่มต้นภาษาอังกฤษ |
|---|---|
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. |
คีย์เพิ่มเติมครอบคลุม aria-label ของโซนลากลง (dropAriaLabel), ข้อความพรีวิว alt (previewAlt, resultAlt), รูปแบบเชื่อมโยงของข้อความลายน้ำที่ใช้กับ licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), การตอบสนองที่ไม่สามารถอ่านได้ (badResponse) และการประกาศ aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะแสดงตามที่เซิร์ฟเวอร์เขียนไว้; serverError ใช้เฉพาะเมื่อการตอบสนองที่ล้มเหลวไม่มีข้อผิดพลาด JSON, เช่น 404 ของวิดเจ็ตที่ปิดการใช้งาน.
ธีม
วิดเจ็ตจะเพิ่มคลาส dcw ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS แบบกำหนดเอง, ดังนั้นคุณสามารถกำหนดธีมได้โดยไม่ต้องแก้ไขภายในของมัน:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}ค่าเริ่มต้น: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, และฟอนต์ UI ของระบบสำหรับ --dcw-font.
สร้างส่วนหน้าของคุณเอง
วิดเจ็ตเป็นเพียงไคลเอนต์สำหรับสัญญา HTTP นี้ — สร้างส่วนหน้าของคุณเองโดยตรงเพื่อประสบการณ์ผู้ใช้ที่แตกต่าง ทั้งสามเส้นทางอยู่ภายใต้สาขา ASP.NET ที่มีการเมานท์ UseDoconut() (โดยปกติคือ /doconut) และพวกมันจะตอบกลับ 404 จนกว่า AddConverterWidget() จะถูกเรียกใช้ ข้อผิดพลาดจะมีเนื้อหา JSON, { "error": "..." }, ยกเว้นในกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?convert= จะตอบกลับ 400.
| เส้นทาง | วัตถุประสงค์ | การตอบสนองสำเร็จ |
|---|---|---|
POST ?convert=open (หลายส่วน, หนึ่งไฟล์) | อัปโหลดและเปิดเอกสารต้นทางเพื่อแสดงตัวอย่าง | 200 — { token, pages, sourceExt, allowedTargets } |
POST ?token=<token>&convert=run&target=<ext> | แปลงแหล่งที่เก็บไว้เป็น target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | สตรีมไฟล์ที่แปลงแล้ว | 200 — ไบต์ของไฟล์, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt ในการตอบสนอง open ไม่มีจุดนำหน้า (เช่น "docx") — เป็นแนวปฏิบัติที่ตรงกันข้ามกับพารามิเตอร์ sourceExtension บน DocumentConverter.ConvertAsync ซึ่งต้องมีจุด. allowedTargets แสดงรายการชื่อเป้าหมายเป็นตัวพิมพ์เล็ก ("pdf", "html", …); ส่งหนึ่งในนั้นเป็น target, ซึ่งจะจับคู่โดยไม่สนใจตัวพิมพ์ใหญ่/เล็ก. open ใช้ไฟล์แรกในส่วน multipart.
resultToken คือ null, และ resultPages คือ 0, เมื่อผลลัพธ์ไม่สามารถแสดงตัวอย่างได้. downloadName คือชื่อไฟล์ต้นทางพร้อมนามสกุลของเป้าหมาย.
ภาพตัวอย่างใช้เส้นทางภาพผู้ชมมาตรฐาน, {basePath}?token={token}&page=1&thumb=1&width={px}, พร้อมกับ token จาก open หรือ resultToken จาก run. วิดเจ็ตขอ width=240.
ไบต์ของแหล่งที่อัปโหลดจะถูกเก็บไว้บนเซิร์ฟเวอร์และคงอยู่เป็นเวลา 30 นาทีหลังจากที่อ่านครั้งสุดท้าย; เมื่อช่วงเวลานั้นหมด, run จะตอบกลับ 404 และไฟล์ต้องเปิดใหม่อีกครั้ง. ผลลัพธ์ที่แปลงแล้วอยู่ใน stash เดียวกัน — downloadToken จะได้รับช่วงเวลา 30 นาทีใหม่เมื่อการแปลงเสร็จ — ในขณะที่ resultToken เป็นโทเคนเซสชันผู้ชมทั่วไปสำหรับการแสดงตัวอย่างผลลัพธ์. เมื่อผลลัพธ์สามารถแสดงตัวอย่างได้, downloadToken และ resultToken มีค่าเดียวกัน. การปิดผลลัพธ์ผู้ชมจะไม่ลบ stash การดาวน์โหลดที่ยังมีอายุ, และการรีเซ็ตวิดเจ็ตในเบราว์เซอร์จะไม่ขยายช่วงเวลาใด ๆ.
โหมดความล้มเหลว, แบ่งตามเส้นทาง:
| เส้นทาง | สถานะ | เมื่อ | เนื้อหา |
|---|---|---|---|
| any | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) — ตรวจสอบก่อนที่เส้นทางทั้งสามจะถูกส่ง | status only |
| any | 405 | วิธี HTTP ไม่ถูกต้อง (open/run ต้องการ POST; download ต้องการ GET) | status only |
open | 400 | ไม่ใช่การอัปโหลด multipart | Expected a multipart file upload. |
open | 400 | ไม่มีไฟล์ หรือไฟล์ว่าง | No file uploaded. |
open | 400 | ส่วนขยายของแหล่งที่ไม่สามารถแปลงได้ | This file type cannot be converted. |
open | 403 | ประเภทไฟล์ต้องการความสามารถที่ใบอนุญาตไม่ได้ให้ (ไฟล์ DICOM ที่ไม่มี Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | ไฟล์ที่อัปโหลดเกิน MaxUploadMb, ตรวจสอบกับ Content-Length และขณะอ่านการอัปโหลด | File is too large. |
run | 400 | โทเคนรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID) | Invalid token. |
run | 400 | target ที่ไม่สามารถแปลงเป็น ConversionTarget | Unknown target format. |
run | 400 | target ไม่ได้อยู่ใน allowedTargets ของแหล่ง | That target format is not available for this file. |
run | 404 | การอัปโหลดที่เก็บไว้หมดอายุหรือโทเคนไม่เคยเปิด | Upload expired — please re-open the file. |
open, run | 500 | การประมวลผลล้มเหลือภายใน | ข้อความที่ทำให้เป็นมาตรฐาน — ทำให้เป็นมาตรฐานเช่นเดียวกับเส้นทางข้อผิดพลาด Doconut ทุกเส้นทาง; ไม่เปิดเผยรายละเอียดภายใน |
download | 400 | โทเคนรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID) | status only |
download | 404 | โทเคนการดาวน์โหลดที่ไม่รู้จักหรือหมดอายุ | status only |
การทำรอบครบวงจรด้วย fetch:
// file: ไฟล์ที่ต้องแปลง, ตัวอย่างเช่นจาก <input type="file">.
async function convertFile(file) {
const base = '/doconut';
// 1. open: อัปโหลดไฟล์
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: แปลงเป็น PDF เมื่อได้รับอนุญาต, มิฉะนั้นเป็นเป้าหมายที่ได้รับอนุญาตเป็นอันดับแรก
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: การ GET ธรรมดาที่เบราว์เซอร์สามารถทำตามได้
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}จุดเชื่อมต่อเป็น same-origin: เวอร์ชันนี้ไม่มีการสนับสนุน CORS. ให้บริการ UI ของคุณและสคริปต์วิดเจ็ตจากต้นทางเดียวกันกับ Doconut, หรือทำ reverse-proxy ทั้งสองเส้นทาง /doconut (เส้นทาง middleware และเส้นทาง resources) ภายใต้ต้นทางของ UI ของคุณ.
ในสภาพการผลิต
- ติดตั้งปลั๊กอิน ข้างแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน:
dotnet add package Doconut.NET8.Converter. - เพิ่มไฟล์ใบอนุญาต. ใส่
Doconut.Viewer.Converter.licในโฟลเดอร์เดียวกันกับDoconut.Viewer.lic. - ตั้งค่าขีดจำกัดของเซิร์ฟเวอร์.
MaxUploadMbในAddConverterWidgetคือขีดจำกัดที่เซิร์ฟเวอร์บังคับใช้;maxUploadMbของวิดเจ็ตเป็นเพียงการตรวจสอบบนฝั่งไคลเอนต์เท่านั้น. ให้สองค่าเท่ากัน. - ให้บริการ UI จากต้นทางเดียวกัน กับ Doconut endpoints, หรือทำ reverse‑proxy ให้ (ดู สร้างส่วนหน้าของคุณเอง).
- ทำลายผลการแปลง. สตรีม
ConvertAsyncที่คืนค่ามานั้นอยู่ในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.
ฟาร์มเว็บ
วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ของมันในหน่วยความจำบนโหนดที่ให้บริการ open. หลังจากโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือการพรีวิวที่ตามมาภายหลังอาจไปถึงโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสเพียงครั้งเดียว, หลังจาก AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
store.FarmKey = farmKey; // อย่างน้อย 32 ไบต์, เหมือนกันบนทุกโหนด
// store.Ttl = TimeSpan.FromMinutes(30); // ระยะเวลาที่การอัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});- เซิร์ฟเวอร์เดียวไม่ต้องทำอะไร: หากไม่ได้เรียกนี้ จะใช้ที่เก็บในหน่วยความจำ.
- การอัปโหลดและผลลัพธ์ถูกเข้ารหัสเมื่อพักอยู่บนแชร์ (AES-256, encrypt-then-MAC), และแต่ละไฟล์ผูกกับโทเค็นของมัน, ดังนั้นโทเค็นหนึ่งจะไม่สามารถอ่านไฟล์ของโทเค็นอื่นได้.
- บนแชร์, การอัปโหลดหรือผลลัพธ์จะถูกเก็บไว้เป็นเวลา
Ttlหลังจากที่เขียนแล้ว; การอ่านไม่ขยายช่วงเวลานั้น. FarmKeyต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยนArgumentExceptionเมื่อRootPathหายไปหรือFarmKeyมีความยาวน้อยกว่า 32 ไบต์.- ตั้งค่า
RootPathให้ชี้ไปที่ตำแหน่งแชร์เดียวกันที่ผู้ชมแบบกระจายใช้.
อ้างอิง API
Facade และตัวเลือกวิดเจ็ตอยู่ใน namespace Doconut; ConversionTarget อยู่ใน Doconut.Configs.Conversion. ConverterPlugin อยู่ใน 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);
}ได้รับการแก้ไขจาก dependency injection; ตัวสร้างเป็น internal. sourceExtension มีจุดนำหน้า. HtmlToWordAsync เขียนไฟล์ .doc เมื่อ outputFormat เป็น ConversionTarget.Doc, และไฟล์ .docx สำหรับค่าอื่นใด.
ConversionTarget
รูปแบบผลลัพธ์ 45 แบบที่ระบุใน รูปแบบเป้าหมาย.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}ตั้งค่าผ่าน DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียงต่อกันได้.
การแก้ไขปัญหา
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
AddDoconut() throws The Converter plugin is registered via AddPlugin but no active license grants Converter. | ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมัน | ติดตั้งใบอนุญาตที่ให้สิทธิ์ Converter, หรือเอา AddPlugin<ConverterPlugin>() ออก |
AddDoconut() throws AddConverterWidget() was called but the Converter plugin is not registered. | วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมัน | เพิ่ม options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
Resolving DocumentConverter throws No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin ยังไม่ได้ลงทะเบียน | เพิ่ม AddPlugin<ConverterPlugin>() ภายใน AddDoconut() |
| Stream conversion says the format is unsupported | sourceExtension ไม่มีจุดนำหน้า | ส่ง ".xlsx", ไม่ใช่ "xlsx" |
ConvertAsync throws Converting '.dcm' requires the Dicom capability license. | แหล่ง DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ์ Dicom |
| The output is watermarked | ใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR) | ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ์ Converter |
The widget loads but its requests answer 404 | AddConverterWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับสาขาที่ UseDoconut() ถูกเมานท์ | เรียก AddConverterWidget(); แก้ไข basePath |
open answers 403 Converting this file type requires the Dicom capability license. | การอัปโหลด DICOM, และใบอนุญาตไม่ได้ให้สิทธิ์ Dicom | ใช้ใบอนุญาตที่ให้สิทธิ์ Dicom |
open answers 413 File is too large. | การอัปโหลดเกิน MaxUploadMb | ยก MaxUploadMb ใน AddConverterWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบบนฝั่งไคลเอนต์ |
run answers 400 That target format is not available for this file. | เป้าหมายไม่ใช่หนึ่งใน allowedTargets ของแหล่ง | เสนอเฉพาะ allowedTargets จาก open |
run or download answers 404 (Upload expired — please re-open the file. from run) | ช่วงเวลา 30 นาทีสิ้นสุดแล้ว, หรือโหนดเว็บฟาร์มไม่มีการอัปโหลด | เปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets |
| The widget fails when the UI is on another origin | Endpoints ไม่มีการสนับสนุน CORS | ให้บริการ UI จากต้นทางเดียวกัน, หรือทำ reverse‑proxy ให้กับเส้นทาง Doconut |
| The theme does not apply | ตัวแปรถูกตั้งค่าบนพาเรนท์หรือบนองค์ประกอบภายใน mount; กฎ .dcw ของวิดเจ็ตเองตั้งค่าไว้บน mount | กำหนดเป้าหมายที่ mount เอง: #doconut-convert.dcw หรือ #doconut-convert |
หน้านี้เป็นประโยชน์หรือไม่?