ملحق المحول
تحويل المستندات إلى 45 تنسيقًا مستهدفًا
يحوِّل ملحق المحول Doconut إلى خدمة تحويل المستندات. إنه يساهم بالمحرك وراء الواجهة العامة DocumentConverter، و— عند الاختيار — عنصر واجهة جاهز بعقد HTTP الخاص به، بحيث يمكنك تحويل المستندات من C#، أو من عنصر الواجهة، أو من الواجهة الأمامية التي تكتبها بنفسك.
| الواجهة | متى تستخدمه |
|---|---|
DocumentConverter (C#) | تقوم بالتحويل على الخادم، دون مشاركة المتصفح |
أداة واجهة جاهزة (doconutConverter.js) | تريد شاشة جاهزة للرفع والتحويل والتنزيل في صفحتك |
نقاط النهاية HTTP (?convert=open|run|download) | تبني واجهة تحويل خاصة بك ضد عقد خادم موثَّق |
تثبيت الحزمة
ثبّت أحدث نسخة مستقرة من ملحق المحول:
dotnet add package Doconut.NET6.Converterلتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
dotnet add package Doconut.NET6.Converter --version 26.10.0احرص على أن تكون حزمة المحول بنفس نسخة Doconut.NET6. معرف الحزمة هو
Doconut.NET6.Converter؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.
ملف ترخيص الملحق، Doconut.Viewer.Converter.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يُقرأ مع ترخيص المشاهد.
المنصات. يعمل الملحق أينما يعمل Doconut.NET6: 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 موحد. كل ملحق، بما في ذلك المحول، يُسجَّل بنفس الطريقة: استدعِ AddPlugin<TPlugin>() داخل AddDoconut(). ConverterPlugin يُوزَّع في حزمة NuGet الخاصة به، Doconut.NET6.Converter، تُثبت جنبًا إلى جنب مع حزمة المشاهد الأساسية.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});هذا كل ما تحتاجه واجهة C#. عنصر الواجهة ونقاط النهاية HTTP الخاصة بهما خيار منفصل، 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.يحدث الاستثناء عند عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Converter، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. لا توجد طبقة مجانية صامتة. انظر إعداد الترخيص لمعرفة كيفية تحميل التراخيص.
الترخيص والعلامة المائية
| حالة الترخيص | بدء التشغيل | ناتج التحويل |
|---|---|---|
ترخيص عارض مدفوع يمنح Converter، ضمن نافذة إصداره | يبدأ | نظيف — watermarked: false |
| ترخيص مؤقت نشط (Demo/NFR) | يبدأ | يحوّل، مع العلامة المائية للتقييم — watermarked: true |
| ترخيص مؤقت منتهي (Demo/NFR) | يبدأ | يحوّل، مع العلامة المائية للتقييم — watermarked: true |
بدون ترخيص، ملف TRIAL قديم، ترخيص بدون Converter، أو ترخيص مدفوع خارج نافذة إصداره | يرمي AddDoconut() | — |
كلا مساري الاستدعاء يحسبان العلامة وفق القاعدة نفسها: واجهة 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 أينما احتجت إليه — فهو عديم الحالة حسب التصميم، لذا يمكن إعادة استخدام نسخة واحدة بأمان عبر الطلبات.
// قم بحقن DocumentConverter؛ مُنشئه داخلي، لذا لا تقم أبداً بإنشاءه باستخدام `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 على التحميل الزائد للمجرى على النقطة الرائدة (".xlsx"، وليس "xlsx") — يقوم المحول بمطابقته مع كتالوج الصيغ ولا يمكن حل امتداد مجرد. وعلى الرغم من اسمه، فإن WordToHtmlAsync يُعيد Task<Stream>، وليس Task<string> — ستحصل على مستند HTML (الصور مدمجة كـ Base64) كمجرى، نفس نتيجة كل تحويل آخر.
المستدعي يمتلك المجرى المعاد ويجب أن يفرغه بعد النسخ أو إرجاع محتوياته. خدمة DocumentConverter نفسها يتم حلها من حقن الاعتمادية؛ لا تقم بإنشائها أو تحريرها يدويًا.
صيغ الهدف
يحتوي ConversionTarget (المساحة الاسمية 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. لا تقم بترميز هذا التعداد صلبًا كقائمة أهداف واجهة المستخدم: ?convert=open يُعيد الـ allowedTargets الفعلي لأي ملف تم رفعه للتو، وهذا ما يجب أن يُقود أداة الاختيار.
عنصر واجهة المستخدم القابل للإدماج
تمكين نقاط النهاية
نقاط النهاية ?convert=open|run|download للعنصر هي اختيارية ومعطلة بشكل افتراضي — آمنة بشكل افتراضي. قم بتمكينها من جانب الخادم، جنبًا إلى جنب مع تسجيل الإضافة:
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() استثناءً:
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()، فإن نقاط النهاية الثلاثة ?convert= تُجيب بـ 404 — لكن ملف الـ JS نفسه لا يزال يُقدَّم على أي حال (إنه مورد ثابت مدمج بسيط؛ فقط نقاط النهاية التي يتواصل معها هي المحجوبة).
تضمينه
<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 أو عنصرًا، يطرح استثناءً إذا لم يُعثر على التركيب، ويعيد مقبضًا. العنصر يرفع ملفًا، يعرض معاينة للصفحة 1، يسمح للمستخدم باختيار أحد allowedTargets، يحول، يعرض معاينة للنتيجة عندما يستطيع، ويقدِّم التنزيل.
الخيارات
| الخيار | النوع | الافتراضي | ملاحظات |
|---|---|---|---|
basePath | string | /doconut | المسار الأساسي لنقاط النهاية ?convert=؛ يجب أن يتطابق مع فرع ASP.NET حيث يتم تثبيت UseDoconut() فعليًا (عادةً يتم تنسيق ذلك عبر MiddlewarePath) |
resPath | string | /doconut-res | مقبول لتوافق التكوين مع أدوات Doconut الأخرى؛ أداة التحويل لا تُنشئ حاليًا أي عنوان URL منها |
maxUploadMb | number | 25 | تحقق مسبق على جانب العميل فقط — يرفض ملفًا كبيرًا جدًا قبل الرفع. الخادم يفرض الحد الخاص به بشكل مستقل ويُجيب بـ 413 إذا تم تجاوزه |
licenseUrl | string | null | null | عند التعيين، يحول إشعار العلامة المائية على شاشة النتيجة إلى رابط لهذا العنوان |
labels | object | {} | يتجاوز أي مجموعة فرعية من سلاسل النص الإنجليزية الافتراضية للأداة (نص السحب، الأزرار، إعلانات 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() تُعيد كائن الأداة نفسه — احتفظ به لتوجيه الأداة برمجيًا:
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(); // يزيل المستمعين، يفرغ 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، وخط واجهة المستخدم النظامي لـ --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> | تحويل المصدر المخزن إلى target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | بث الملف المحول | 200 — بايتات الملف، Content-Disposition: attachment، Cache-Control: no-store |
sourceExt في استجابة open لا يحتوي على نقطة بادئة (مثال: "docx") — وهو عكس convention من المعامل 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 نفس القيمة. إغلاق نتيجة المشاهد لا يحذف التخزين القابل للتحميل ما زال صالحًا، وإعادة ضبط واجهة المتصفح لا يمدد أيًا من النافذتين.
أنماط الفشل، مجمعة حسب المسار:
| المسار | الحالة | متى | المحتوى |
|---|---|---|---|
| أي | 404 | الواجهة غير مفعلة (AddConverterWidget() لم يُستدعى أبداً) — يتم التحقق قبل تنفيذ أي من المسارات الثلاثة | فقط الحالة |
| أي | 405 | طريقة HTTP غير صحيحة (open/run تتطلب POST؛ download يتطلب GET) | فقط الحالة |
open | 400 | ليس تحميلًا متعدد الأجزاء | 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) | فقط الحالة |
download | 404 | رمز تحميل غير معروف أو منتهي الصلاحية | فقط الحالة |
جولة كاملة مع 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);
}النقاط النهائية هي نفس الأصل: هذا الإصدار لا يدعم CORS. قدّم واجهتك وسكربت الواجهة من نفس أصل Doconut، أو اعكس‑الوكيل كلا مساري /doconut (مسار الوسيط ومسار الموارد) تحت أصل واجهتك.
في الإنتاج
- تثبيت الإضافة بجوار حزمة النواة، بنفس الإصدار:
dotnet add package Doconut.NET6.Converter. - إضافة ملف الترخيص. ضع
Doconut.Viewer.Converter.licفي نفس المجلد معDoconut.Viewer.lic. - تعيين حد الخادم.
MaxUploadMbفيAddConverterWidgetهو الحد الذي يفرضه الخادم؛maxUploadMbالخاص بالودجيت هو مجرد فحص من جانب العميل. حافظ على مساواة الاثنين. - تقديم واجهة المستخدم من نفس الأصل كما نقاط النهاية Doconut، أو استخدم reverse-proxy لها (انظر ابنِ واجهتك الخاصة).
- إلغاء تحويل النتائج. التدفق الذي يُرجعه
ConvertAsyncمُجمع؛ إلغاء تخصيصه يعيد المخازن المؤقتة إلى التجمع.
مزارع الويب
الودجيت يحتفظ بكل تحميل ونتيجته في الذاكرة على العقدة التي قدمت open. خلف موازن تحميل بدون جلسات ثابتة، طلب لاحق 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، تشفير ثم MAC)، وكل ملف مرتبط برمز الوصول الخاص به، لذا لا يمكن لأي رمز قراءة ملف آخر.
- على المشاركة، يُحتفظ بتحميل أو نتيجة لمدة
Ttlبعد كتابتها؛ القراءة لا تُطيل تلك الفترة. - يجب أن يكون
FarmKeyعلى الأقل 32 بايت ومتماثل على كل عقدة. حمّله من مخزن سري؛ لا تقم بتثبيته صراحةً. التسجيل يُطلق استثناءArgumentExceptionعندما يكونRootPathمفقودًا أوFarmKeyأقصر من 32 بايت. - وجه
RootPathإلى نفس الموقع المشترك الذي يستخدمه العارض الموزع.
مرجع API
الواجهة وخيارات الودجيت موجودة في مساحة الاسم 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);
}يتم حله من حقن الاعتمادية؛ المُنشئ داخلي. 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() يرمي 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 |
الودجيت يُحمَّل لكن طلباته تُجيب بـ 404 | AddConverterWidget() لم يُستدعَ، أو 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 |
| يفشل الودجيت عندما تكون واجهة المستخدم على أصل آخر | نقاط النهاية لا تدعم CORS | قدِّم واجهة المستخدم من نفس الأصل، أو استخدم reverse-proxy لمسارات Doconut |
| المظهر لا يُطبق | المتغيرات مُعينة على سلف أو على عنصر داخل التركيب؛ قاعدة .dcw الخاصة بالودجيت تُعيّنها على التركيب | استهدف التركيب نفسه: #doconut-convert.dcw أو #doconut-convert |
هل كانت هذه الصفحة مفيدة؟