ملحق التحويل
تحويل المستندات إلى 45 صيغة مستهدفة
يقوم ملحق Converter بتحويل Doconut إلى خدمة تحويل المستندات. إنه يساهم بالمحرك وراء الواجهة العامة DocumentConverter، و— عند الاختيار — ويدجت جاهز بعقد HTTP خاص به، بحيث يمكنك تحويل المستندات من C#، أو من الويدجت، أو من واجهة أمامية تقوم بكتابتها بنفسك.
| السطح | متى تستخدمه |
|---|---|
DocumentConverter (C#) | تقوم بالتحويل على الخادم، دون مشاركة المتصفح |
Drop-in widget (doconutConverter.js) | تريد شاشة جاهزة للرفع، التحويل والتحميل في صفحتك |
HTTP endpoints (?convert=open|run|download) | تبني واجهة تحويل خاصة بك ضد عقد خادم موثّق |
تثبيت الحزمة
قم بتثبيت أحدث نسخة مستقرة من ملحق Converter:
dotnet add package Doconut.NETStandard.Converterلتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
dotnet add package Doconut.NETStandard.Converter --version 26.10.0احرص على أن تكون حزمة Converter بنفس إصدار Doconut.NETStandard. معرف الحزمة هو Doconut.NETStandard.Converter؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.
ملف ترخيص الملحق، Doconut.Viewer.Converter.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص العارض.
تسجيل الملحق
لا توجد طريقة AddConverter() — نموذج ملحقات Doconut موحد. كل ملحق، بما في ذلك Converter، يُسجَّل بنفس الطريقة: استدعِ AddPlugin<TPlugin>() داخل AddDoconut(). يأتي ConverterPlugin في حزمة NuGet الخاصة به، Doconut.NETStandard.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.رسالة الخطأ المتوقعة: InvalidOperationException: لا توجد صلاحيات تحويل
بدون 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 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; no-op ما لم يكن خاملًا حاليًا
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 (متعدد الأجزاء، ملف واحد) | رفع وفتح مستند مصدر للمعاينة | 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 ويجب إعادة فتح الملف. النتيجة المحوّلة تعيش في نفس التخزين — يحصل 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، أو استخدم reverse‑proxy لكلا مساري /doconut (مسار الوسيط ومسار الموارد) تحت أصل واجهة المستخدم الخاصة بك.
في الإنتاج
- تثبيت الإضافة بجوار حزمة النواة، بنفس الإصدار:
dotnet add package Doconut.NETStandard.Converter. - إضافة ملف الترخيص. ضع
Doconut.Viewer.Converter.licفي نفس المجلد معDoconut.Viewer.lic. - تعيين حد الخادم.
MaxUploadMbفيAddConverterWidgetهو الحد الذي يفرضه الخادم؛maxUploadMbالخاص بالأداة هو مجرد فحص من جانب العميل. حافظ على مساواة الاثنين. - خدمة واجهة المستخدم من نفس الأصل كما نقاط النهاية Doconut، أو عكس‑وكيلها (انظر بناء الواجهة الأمامية الخاصة بك).
- التخلص من نتائج التحويل. الدفق الذي تُعيده
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 bytes، متطابق على كل عقدة
// 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 | قدِّم واجهة المستخدم من نفس الأصل، أو عكس‑وكّل مسارات Doconut |
| السمة لا تُطبق | المتغيّرات مضبوطة على سلف أو على عنصر داخل التركيب؛ قاعدة .dcw الخاصة بالأداة تضبطها على التركيب | استهدف التركيب نفسه: #doconut-convert.dcw أو #doconut-convert |
ملاحظات الإطار
viewer.Converter.GetConverter()غير موجود هنا. لم يعد يتم الوصول إلى التحويل عبر مثيل العارض: قم بحقنDoconut.DocumentConverterبدلاً من ذلك.- هذا الـ
ConversionTargetenum يغطي كل عائلة مصدر. المكتبة السابقة كان لديها نوع*ConfigConverterلكل عائلة —WordConfigConverter،ExcelConfigConverter، وهكذا — كل منها يحتوي على enum متداخلEnTargetFormat، بالإضافة إلى enumSourceFormatConverterللمدخل. جميعها اختفت؛ راجع دليل الترحيل. - Windows فقط, مثل باقي حزمة .NET Standard.
هل كانت هذه الصفحة مفيدة؟