ปลั๊กอินแปลงไฟล์

แปลงเอกสารเป็น 45 รูปแบบเป้าหมาย

ปลั๊กอิน Converter ทำให้ Doconut กลายเป็นบริการแปลงเอกสาร มันเป็นส่วนที่ให้เครื่องยนต์เบื้องหลังส่วนหน้าสาธารณะ DocumentConverter และ — หากเลือกใช้ — วิดเจ็ตแบบ drop‑in ที่มีสัญญา HTTP ของตนเอง เพื่อให้คุณสามารถแปลงเอกสารจาก C#, จากวิดเจ็ต, หรือจากส่วนหน้า (frontend) ที่คุณเขียนเองได้

พื้นผิวใช้เมื่อ
DocumentConverter (C#)คุณแปลงบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง
วิดเจ็ตแบบ drop‑in (doconutConverter.js)คุณต้องการหน้าจออัปโหลด, แปลงและดาวน์โหลดที่พร้อมใช้งานในหน้าเว็บของคุณ
จุดเชื่อมต่อ HTTP (?convert=open|run|download)คุณสร้าง UI การแปลงของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสาร

ติดตั้งแพ็กเกจ

ติดตั้งปลั๊กอิน Converter รุ่นเสถียรล่าสุด:

bash
dotnet add package Doconut.NETStandard.Converter

เพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับเอกสารนี้ ให้ระบุเวอร์ชันแยกต่างหาก:

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

รักษาแพ็กเกจ Converter ให้มีเวอร์ชันเดียวกับ Doconut.NETStandard แพ็กเกจ ID คือ Doconut.NETStandard.Converter; .<version> ปรากฏเฉพาะในชื่อไฟล์ .nupkg ที่ดาวน์โหลดมา

ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Converter.lic, จะวางในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; ไฟล์นี้จะถูกอ่านพร้อมกับใบอนุญาตของ viewer

ลงทะเบียนปลั๊กอิน

ไม่มีเมธอด AddConverter() — โมเดลปลั๊กอินของ Doconut มีรูปแบบเดียวกัน ทุกปลั๊กอินรวมถึง Converter จะลงทะเบียนด้วยวิธีเดียวกัน: เรียก AddPlugin<TPlugin>() ภายใน AddDoconut(). ConverterPlugin มีแพ็กเกจ NuGet ของตนเอง, Doconut.NETStandard.Converter, ที่ติดตั้งพร้อมกับแพ็กเกจ viewer พื้นฐาน

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

นี่คือทั้งหมดที่ส่วนหน้า C# ต้องการ วิดเจ็ตและจุดเชื่อมต่อ HTTP ของมันเป็นส่วนที่ต้องเลือกใช้เพิ่มเติม, AddConverterWidget() (ดู วิดเจ็ตแบบ drop‑in).

ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Converter หากไม่มี จะทำให้ AddDoconut() โยนข้อผิดพลาด InvalidOperationException ขณะเริ่มต้น ก่อนแอปจะให้บริการคำขอใด ๆ:

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.

ข้อผิดพลาดจะเกิดเมื่อไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ขาด Converter, หรือใบอนุญาตที่ชำระแล้วใช้เกินช่วงเวอร์ชันที่กำหนด ใบอนุญาต Demo/NFR ชั่วคราวก็ได้รับการยอมรับ ไม่มีระดับฟรีแบบเงียบ ๆ ดู การตั้งค่าใบอนุญาต เพื่อดูวิธีโหลดใบอนุญาต

การให้สิทธิ์และลายน้ำ

สถานะใบอนุญาตการเริ่มต้นผลลัพธ์การแปลง
ใบอนุญาต viewer แบบชำระที่ให้ความสามารถ Converter, อยู่ในช่วงเวอร์ชันที่กำหนดเริ่มทำงานสะอาด — watermarked: false
ใบอนุญาตชั่วคราว (Demo/NFR) ที่ใช้งานอยู่เริ่มทำงานแปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true
ใบอนุญาตชั่วคราว (Demo/NFR) ที่หมดอายุเริ่มทำงานแปลงได้, พร้อมลายน้ำการประเมินผล — watermarked: true
ไม่มีใบอนุญาต, ไฟล์ legacy TRIAL, ใบอนุญาตที่ขาด Converter, หรือใบอนุญาตชำระที่อยู่นอกช่วงเวอร์ชันAddDoconut() โยนข้อผิดพลาด—

เส้นทางการเรียกทั้งสองคำนวณค่าสถานะจากกฎเดียวกัน: ส่วนหน้า C# DocumentConverter สร้างค่านี้จากสถานะ IsViewerLicensed และ IsTemporary ของใบอนุญาตภายใน, ส่วน handler ?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 ที่ใดก็ได้ที่คุณต้องการ — มันไม่มีสถานะตามการออกแบบ ดังนั้นอินสแตนซ์เดียวจึงปลอดภัยต่อการใช้งานซ้ำหลายคำขอ.

csharp
// Inject DocumentConverter; ตัวสร้างของมันเป็น internal, ดังนั้นห้าม `new` มัน
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension รวมจุดนำหน้าด้วย. password จะเป็น null เว้นแต่เอกสารถูกป้องกัน
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// 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 รายการ:

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

ไม่ใช่ทุกแหล่งจะสามารถแปลงเป็นทุกเป้าหมาย — ปลั๊กอินจะแมปแต่ละตระกูลฟอร์แมตของแหล่ง (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

endpoint ?convert=open|run|download ของวิดเจ็ตเป็นแบบ opt-in และถูกปิดใช้งานโดยค่าเริ่มต้น — ปลอดภัยโดยค่าเริ่มต้น. เปิดใช้งานพวกมันบนเซิร์ฟเวอร์พร้อมกับการลงทะเบียนปลั๊กอิน:

csharp
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() จะทำการโยนข้อยกเว้น:

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.

หากไม่มี AddConverterWidget(), สาม endpoint ?convert= จะตอบกลับด้วย 404 — แต่ไฟล์ JS เองยังคงให้บริการอยู่ (เป็นทรัพยากรสแตติกที่ฝังอยู่; มีเพียง endpoint ที่มันสื่อสารที่ถูกจำกัด).

ฝังไว้

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) รับตัวเลือก CSS หรือองค์ประกอบ, ขว้างข้อผิดพลาดหากไม่พบการเมานท์, และคืนค่า handle. วิดเจ็ตอัปโหลดไฟล์, แสดงตัวอย่างของหน้า 1, ให้ผู้ใช้เลือกหนึ่งใน allowedTargets, แปลง, แสดงตัวอย่างผลลัพธ์เมื่อทำได้, และเสนอการดาวน์โหลด.

ตัวเลือก

ตัวเลือกประเภทค่าเริ่มต้นหมายเหตุ
basePathstring/doconutเส้นทางฐานสำหรับ endpoint ของ ?convert=; ต้องตรงกับสาขา ASP.NET ที่ UseDoconut() ถูกเมานท์จริง (โดยปกติประสานงานผ่าน MiddlewarePath)
resPathstring/doconut-resรับเพื่อความสอดคล้องของการกำหนดค่ากับวิดเจ็ต Doconut ตัวอื่น; วิดเจ็ตแปลงยังไม่ได้สร้าง URL ใดจากค่าเหล่านี้
maxUploadMbnumber25ตรวจสอบล่วงหน้าที่ฝั่งไคลเอนต์เท่านั้น — ปฏิเสธไฟล์ที่ใหญ่เกินขนาดก่อนอัปโหลด. เซิร์ฟเวอร์บังคับใช้ขีดจำกัดของตนเองอย่างอิสระและตอบกลับ 413 หากเกิน
licenseUrlstring | nullnullเมื่อกำหนดค่า, จะเปลี่ยนข้อความลายน้ำบนหน้าผลลัพธ์ให้เป็นลิงก์ไปยัง URL นี้
labelsobject{}แทนที่ส่วนย่อยใด ๆ ของสตริงค่าเริ่มต้นภาษาอังกฤษของวิดเจ็ต (ข้อความลากลง, ปุ่ม, การประกาศ aria-live, ข้อความแสดงข้อผิดพลาด)

การเรียกกลับ

การเรียกกลับเกิดขึ้นเมื่อข้อมูลที่ส่ง
onReady()วิดเจ็ตได้แสดงหน้าจอพัก/ลากลง—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open สำเร็จโทเค็นเซสชันต้นทาง, จำนวนหน้า, ส่วนขยายของแหล่ง (ไม่มีจุดนำหน้า), รายการเป้าหมายที่อนุญาต
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run สำเร็จฟิลด์เดียวกันกับการตอบสนองการรัน, พร้อมกับ target ที่ร้องขอ
onDownload({ downloadName, downloadToken })ผู้ใช้คลิกที่ลิงก์ดาวน์โหลดทำงานพร้อมกับการดาวน์โหลดตามธรรมชาติของเบราว์เซอร์ — ไม่ดักจับหรือแทนที่
onError({ phase, message })คำขอเปิดหรือรันล้มเหลวphase คือ 'open' หรือ 'run'; message คือข้อผิดพลาดจากเซิร์ฟเวอร์ที่ทำความสะอาดแล้ว (หรือข้อความจากไคลเอนต์สำหรับการตรวจสอบขนาดอัปโหลดล่วงหน้า)

การเรียกกลับที่ขว้างข้อยกเว้นจะถูกจับและบันทึก; มันไม่เคยทำให้วิดเจ็ตหยุดทำงาน.

ตัวจัดการเชิงบังคับ

Doconut.convert() คืนค่าตัวอย่างของวิดเจ็ตเอง — เก็บไว้เพื่อควบคุมวิดเจ็ตโดยโปรแกรม:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // File จากของคุณเอง <input type="file" id="picker">
conv.reset();         // กลับไปที่หน้าจอ idle/drop; ไม่ทำการ fire ใหม่ onReady
conv.loadFile(file);  // เริ่ม flow ด้วยอ็อบเจกต์ File; no-op ยกเว้นเมื่อกำลัง idle
conv.destroy();       // ลบ listeners, ทำให้ mount ว่าง; instance จะไม่สามารถใช้ได้หลังจากนี้

ป้ายกำกับ

ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels แทนที่ส่วนย่อยใด ๆ และส่วนที่เหลือคงเป็นภาษาอังกฤษ. ส่วนที่เปลี่ยนแปลงระหว่างการทำงานใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.

คีย์ค่าเริ่มต้นภาษาอังกฤษ
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.

คีย์เพิ่มเติมครอบคลุม aria-label ของโซนลากลง (dropAriaLabel), ข้อความ preview alt (previewAlt, resultAlt), รูปแบบลิงก์ของข้อความลายน้ำที่ใช้กับ licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), การตอบสนองที่ไม่สามารถอ่านได้ (badResponse) และการประกาศ aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะแสดงตามที่เซิร์ฟเวอร์เขียนไว้; serverError ใช้เฉพาะเมื่อการตอบสนองที่ล้มเหลวไม่มีข้อผิดพลาด JSON, เช่น 404 ของวิดเจ็ตที่ถูกปิดใช้งาน.

ธีม

วิดเจ็ตเพิ่มคลาส dcw ไปยังองค์ประกอบที่เมานท์และอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS ที่กำหนดเอง, ดังนั้นคุณสามารถปรับธีมได้โดยไม่ต้องแก้ไขภายในของมัน:

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 (multipart, one file)อัปโหลดและเปิดเอกสารต้นทางเพื่อดูตัวอย่าง200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>แปลงต้นทางที่เก็บไว้เป็น target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>สตรีมไฟล์ที่แปลงแล้ว200 — file bytes, 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 และไฟล์ต้องเปิดใหม่. ผลลัพธ์ที่แปลงแล้วอยู่ในที่เก็บเดียวกัน — downloadToken จะได้รับช่วงเวลา 30 นาทีใหม่เมื่อการแปลงเสร็จสิ้น — ส่วน resultToken เป็นโทเค็นเซสชันผู้ชมทั่วไปสำหรับดูตัวอย่างผลลัพธ์. เมื่อผลลัพธ์สามารถดูตัวอย่างได้, downloadToken และ resultToken มีค่าเดียวกัน. การปิดผลลัพธ์ผู้ชมจะไม่ลบที่เก็บดาวน์โหลดที่ยังมีอายุ, และการรีเซ็ตวิดเจ็ตในเบราว์เซอร์จะไม่ขยายช่วงเวลาใด ๆ.

โหมดความล้มเหลว, จัดกลุ่มตามเส้นทาง:

เส้นทางสถานะเมื่อเนื้อหา
any404วิดเจ็ตไม่ได้เปิดใช้งาน (AddConverterWidget() ไม่เคยถูกเรียก) — ตรวจสอบก่อนที่เส้นทางทั้งสามจะถูกส่งเฉพาะสถานะ
any405HTTP verb ไม่ถูกต้อง (open/run ต้องการ POST; download ต้องการ GET)เฉพาะสถานะ
open400ไม่ใช่การอัปโหลดแบบ multipartExpected a multipart file upload.
open400ไม่มีไฟล์ หรือไฟล์ว่างNo file uploaded.
open400ส่วนขยายของแหล่งที่ไม่สามารถแปลงได้This file type cannot be converted.
open403ประเภทไฟล์ต้องการความสามารถที่ใบอนุญาตไม่ได้ให้ (ไฟล์ DICOM ที่ไม่มี Dicom)Converting this file type requires the Dicom capability license.
open413ไฟล์ที่อัปโหลดเกิน MaxUploadMb, ตรวจสอบเทียบกับ Content-Length และขณะอ่านการอัปโหลดFile is too large.
run400โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID)Invalid token.
run400target ที่ไม่สามารถแปลงเป็น ConversionTargetUnknown target format.
run400target ไม่ได้อยู่ใน allowedTargets ของแหล่งThat target format is not available for this file.
run404การอัปโหลดที่เก็บไว้หมดอายุหรือโทเค็นไม่เคยเปิดUpload expired — please re-open the file.
open, run500การประมวลผลล้มเหลือภายในข้อความที่ทำให้สะอาด — ทำให้สะอาดเช่นเดียวกับเส้นทางข้อผิดพลาด Doconut ทุกเส้นทาง; ไม่เปิดเผยรายละเอียดภายใน
download400โทเค็นรูปแบบไม่ถูกต้อง (ไม่ใช่ GUID)เฉพาะสถานะ
download404โทเค็นดาวน์โหลดที่ไม่รู้จักหรือหมดอายุเฉพาะสถานะ

การเดินทางรอบเต็มด้วย fetch:

javascript
// 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 ของคุณ.

ในการผลิต

  1. ติดตั้งปลั๊กอิน ข้างแพ็กเกจหลัก, ที่เวอร์ชันเดียวกัน: dotnet add package Doconut.NETStandard.Converter.
  2. เพิ่มไฟล์ใบอนุญาต. ใส่ Doconut.Viewer.Converter.lic ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic.
  3. ตั้งค่าขีดจำกัดของเซิร์ฟเวอร์. MaxUploadMb ใน AddConverterWidget คือขีดจำกัดที่เซิร์ฟเวอร์บังคับใช้; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์เท่านั้น. ให้สองค่าตรงกัน.
  4. ให้บริการ UI จากต้นทางเดียวกัน กับจุดเชื่อมต่อ Doconut, หรือทำ reverse‑proxy (ดู สร้างส่วนหน้าเอง).
  5. ทำลายผลการแปลง. สตรีม ConvertAsync ที่คืนค่ามานั้นอยู่ในพูล; การทำลายมันจะคืนบัฟเฟอร์กลับไปยังพูล.

ฟาร์มเว็บ

วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนโหนดที่ให้บริการ open. หากอยู่หลังโหลดบาลานเซอร์ที่ไม่มี sticky sessions, คำขอ run, download หรือ preview ที่ตามมาภายหลังอาจไปยังโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสหนึ่งครั้ง, หลังจาก AddDoconut():

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
    store.FarmKey = farmKey;                   // อย่างน้อย 32 bytes, เหมือนกันบนทุกโหนด
    // store.Ttl = TimeSpan.FromMinutes(30);   // ระยะเวลาที่ไฟล์อัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});
  • เซิร์ฟเวอร์เดียวไม่ต้องทำอะไร: หากไม่มีการเรียกนี้ จะใช้ที่เก็บในหน่วยความจำ
  • การอัปโหลดและผลลัพธ์ถูกเข้ารหัสที่พักบนแชร์ (AES-256, encrypt-then-MAC), และไฟล์แต่ละไฟล์ผูกกับโทเคนของมัน, ดังนั้นโทเคนหนึ่งไม่สามารถอ่านไฟล์ของโทเคนอื่นได้.
  • บนแชร์, การอัปโหลดหรือผลลัพธ์จะถูกเก็บไว้เป็นเวลา Ttl หลังจากเขียน; การอ่านไม่ขยายช่วงเวลานั้น.
  • FarmKey ต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยน ArgumentException เมื่อ RootPath หายไปหรือ FarmKey มีความยาวน้อยกว่า 32 ไบต์.
  • ตั้งค่า RootPath ให้ชี้ไปที่ตำแหน่งแชร์เดียวกันที่ตัวดูแบบกระจายใช้.

เอกสารอ้างอิง API

ฟาซาเดและตัวเลือกของวิดเจ็ตอยู่ในเนมสเปซ Doconut; ConversionTarget อยู่ใน Doconut.Configs.Conversion. ConverterPlugin อยู่ใน 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);
}

ได้รับจากการฉีดพึ่งพา; ตัวสร้างเป็น internal. sourceExtension มีจุดนำหน้า. HtmlToWordAsync เขียนไฟล์ .doc เมื่อ outputFormat เป็น ConversionTarget.Doc, และไฟล์ .docx สำหรับค่าที่อื่นใด

ConversionTarget

45 รูปแบบผลลัพธ์ที่ระบุใน รูปแบบเป้าหมาย.

ConverterWidgetOptions

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

ตั้งค่าผ่าน DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียงคำสั่งได้

การแก้ไขปัญหา

อาการสาเหตุวิธีแก้
AddDoconut() ขว้าง The Converter plugin is registered via AddPlugin but no active license grants Converter.ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Converter, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมันติดตั้งใบอนุญาตที่ให้สิทธิ Converter, หรือเอา AddPlugin<ConverterPlugin>() ออก
AddDoconut() ขว้าง AddConverterWidget() was called but the Converter plugin is not registered.วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมันเพิ่ม options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
การแก้ไข DocumentConverter ขว้าง No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin ยังไม่ได้ลงทะเบียนเพิ่ม AddPlugin<ConverterPlugin>() ภายใน AddDoconut()
การแปลงสตรีมบอกว่ารูปแบบไม่รองรับsourceExtension ไม่มีจุดนำหน้าส่ง ".xlsx", ไม่ใช่ "xlsx"
ConvertAsync ขว้าง Converting '.dcm' requires the Dicom capability license.แหล่ง DICOM, และใบอนุญาตไม่ได้ให้สิทธิ Dicomใช้ใบอนุญาตที่ให้สิทธิ Dicom
ผลลัพธ์มีลายน้ำใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR)ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Converter
วิดเจ็ตโหลดแล้วแต่คำขอตอบกลับด้วย 404AddConverterWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับสาขาที่ UseDoconut() ถูกเมานท์เรียก AddConverterWidget(); แก้ basePath
open ตอบกลับ 403 Converting this file type requires the Dicom capability license.การอัปโหลด DICOM, และใบอนุญาตไม่ได้ให้สิทธิ Dicomใช้ใบอนุญาตที่ให้สิทธิ Dicom
open ตอบกลับ 413 File is too large.การอัปโหลดเกิน MaxUploadMbยก MaxUploadMb ใน AddConverterWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์
run ตอบกลับ 400 That target format is not available for this file.เป้าหมายไม่ใช่หนึ่งใน allowedTargets ของแหล่งเสนอเฉพาะ allowedTargets จาก open
run หรือ download ตอบกลับ 404 (Upload expired — please re-open the file. จาก run)ช่วงเวลา 30 นาทีหมดแล้ว, หรือโหนดเว็บฟาร์มไม่มีการอัปโหลดเปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets
วิดเจ็ตล้มเหลวเมื่อ UI อยู่บนต้นทางอื่นจุดเชื่อมต่อไม่มีการสนับสนุน CORSให้บริการ UI จากต้นทางเดียวกัน, หรือทำ reverse‑proxy เส้นทาง Doconut
ธีมไม่ทำงานตัวแปรถูกตั้งค่าบนองค์ประกอบบรรพบุรุษหรือบนองค์ประกอบภายใน mount; กฎ .dcw ของวิดเจ็ตเองตั้งค่าไว้บน mountกำหนดเป้าหมายที่ mount เอง: #doconut-convert.dcw หรือ #doconut-convert

หมายเหตุของเฟรมเวิร์ก

  • viewer.Converter.GetConverter() ไม่มีอยู่ที่นี่. การแปลงไม่สามารถเข้าถึงผ่านอินสแตนซ์ของ viewer ได้อีกต่อไป: แทรก Doconut.DocumentConverter แทน.
  • enum ConversionTarget นี้ครอบคลุมทุกครอบครัวของแหล่งข้อมูล. ไลบรารีก่อนหน้านี้มีประเภท *ConfigConverter แยกตามครอบครัว — WordConfigConverter, ExcelConfigConverter, เป็นต้น — แต่ละประเภทมี enum EnTargetFormat ซ้อนอยู่ของตนเอง, พร้อมกับ enum SourceFormatConverter สำหรับอินพุต. ทั้งหมดหายไป; ดู คู่มือการย้าย.
  • เฉพาะ Windows เช่นเดียวกับส่วนที่เหลือของแพคเกจ .NET Standard.

หน้านี้เป็นประโยชน์หรือไม่?