ملحق التحويل

يحوِّل ملحق التحويل Doconut إلى خدمة تحويل المستندات. يساهم بالمحرك وراء الواجهة العامة DocumentConverter، و— عند الاختيار— بأداة قابلة للإدراج لها عقد HTTP الخاص بها، بحيث يمكنك تحويل المستندات من C#، أو من الأداة، أو من الواجهة الأمامية التي تكتبها بنفسك.

تثبيت الحزمة

قم بتثبيت أحدث نسخة مستقرة من ملحق التحويل:

dotnet add package Doconut.NET8.Converter

لتثبيت الملحق على الإصدار الحالي 26.7.0، مرّر الإصدار بشكل منفصل:

dotnet add package Doconut.NET8.Converter --version 26.7.0

احتفظ بحزمة التحويل بنفس الإصدار كما هو في Doconut.NET8. معرّف الحزمة هو Doconut.NET8.Converter؛ يظهر .26.7.0 فقط في اسم الملف .nupkg الذي تم تنزيله.

تسجيل الملحق

لا توجد طريقة AddConverter() — نموذج ملحقات Doconut موحد. كل ملحق، بما في ذلك التحويل، يُسجَّل بنفس الطريقة: استدعِ AddPlugin<TPlugin>() داخل AddDoconut(). ConverterPlugin يأتي في حزمة NuGet الخاصة به، Doconut.NET8.Converter، مثبتًا جنبًا إلى جنب مع حزمة عارض الأساس.

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

يُطلق هذا الاستدعاء استثناءً عند بدء التشغيل بسبب ترخيص مفقود، أو ملف TRIAL قديم، أو ترخيص غير مؤقت لا يمنح القدرة على Converter — وهو InvalidOperationException يُثار من داخل AddDoconut()، قبل أن يبدأ التطبيق في معالجة الطلبات. تُقبل تسجيلات Demo/NFR المؤقتة؛ بعد انتهاء صلاحيتها، يظل التحويل متاحًا مع مخرجات مائية. لا توجد طبقة مجانية صامتة. راجع إعداد الترخيص لمعرفة كيفية تحميل التراخيص.

التحويل من 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(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

تفصيلان سهل الوقوع في الخطأ بشأنهما: يجب أن يتضمن sourceExtension في التحميل الزائد للمجرى النقطة الأولية (".xlsx"، وليس "xlsx") — يطابق المحول ذلك مع كتالوج الصيغ ولا يمكن للامتداد المجرد أن يُحل. وعلى الرغم من اسمه، يُعيد WordToHtmlAsync Task<Stream>، وليس Task<string> — ستحصل على مستند HTML (الصور مدمجة كـ Base64) كمجرى، وهو نفس نتيجة كل تحويل آخر.

صيغ الهدف

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

ليس كل مصدر يتحول إلى كل هدف — يقوم الملحق بربط عائلة صيغ كل مصدر (Word، Excel، PowerPoint، PDF، CAD، Image، Email، Diagram، Project/Task، PSD، مستند ويب) بمجموعة ثابتة من الأهداف المسموح بها. لا تُبرمج هذا التعداد صلبًا كقائمة أهداف لواجهتك: يُعيد ?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;
    });
});

<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>

بدون AddConverterWidget()، فإن نقاط النهاية الثلاثة ?convert= تجيب بـ 404 — لكن ملف الـ JS نفسه لا يزال يُقدَّم على أي حال (إنه مورد ثابت مضمّن بسيط؛ فقط نقاط النهاية التي يتواصل معها محجوبة). لا يزال AddConverterWidget() يتطلب تسجيل إضافة Converter ورخصة تُمنح Converter — لا تمنح حقوق التحويل بحد ذاتها.

تخصيص الأداة

خيارات التهيئة الممررة إلى Doconut.convert(selector, options):

النداءات العكسية:

Doconut.convert() يُعيد نسخة من كائن الأداة نفسه — احتفظ به لتوجيه الأداة برمجيًا:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // العودة إلى شاشة الخمول/الإسقاط؛ لا يعيد تشغيل onReady
conv.loadFile(file);  // يبدأ التدفق باستخدام كائن File؛ لا يفعل شيئًا إلا إذا كان في حالة الخمول
conv.destroy();       // يزيل المستمعين، يفرغ الـ mount؛ يصبح الكائن غير قابل للاستخدام بعد ذلك

بناء واجهة أمامية خاصة بك

الأداة مجرد عميل لهذا العقد HTTP — قم ببناء واجهة أمامية خاصة بك مباشرةً للحصول على تجربة مستخدم مختلفة. جميع المسارات الثلاثة تقع تحت فرع ASP.NET حيث يتم تثبيت UseDoconut() (عادةً /doconut):

يتم تخزين بايتات المصدر المرفوعة على الخادم مع TTL قدره 30 دقيقة؛ بمجرد انتهاء هذه الفترة، يجيب run بـ 404 ويجب إعادة فتح الملف. النتيجة المحوَّلة تعيش في نفس التخزين — يحصل downloadToken على نافذة جديدة لمدة 30 دقيقة عند اكتمال التحويل — بينما resultToken هو رمز جلسة عارض عادي تستمر مدة حياته وفقًا لذاكرة التخزين المؤقت لجلسة العارض، مستقلة عن التخزين.

sourceExt في استجابة open لا يحتوي على نقطة أمامية (مثال: "docx") — وهو عكس convention المعامل sourceExtension على DocumentConverter.ConvertAsync، الذي يتطلب واحدة.

أنماط الفشل، مجمعة حسب المسار:

ملكية المورد

يعيد المحول كائن MemoryStream قابل للتمرير موضعه عند الصفر. يمتلك المستدعي ذلك التدفق ويجب أن يفرغه بعد النسخ أو إرجاع محتوياته. خدمة DocumentConverter نفسها لا تحتفظ بحالة ويتم حلها عبر حقن الاعتماديات؛ لا تقم بإنشاء الخدمة أو تحريرها يدويًا.

بالنسبة لأداة الويب، فإن مخازن الرفع والتحميل لديها أوقات بقاء (TTL) مستقلة مدتها 30 دقيقة. يتبع عارض resultToken بدلاً من ذلك مدة جلسة العارض. إغلاق نتيجة العارض لا يحذف مخزن التحميل الذي لا يزال صالحًا، وإعادة ضبط أداة المتصفح لا يمدد أيًا من أوقات البقاء.

استكشاف الأخطاء وإصلاحها

وضع العلامة المائية

مع تسجيل ConverterPlugin، يكون ترخيص المضيف في إحدى ثلاث حالات:

كلا مساري الاستدعاء يحسبان العلامة وفقًا لنفس القاعدة: الواجهة DocumentConverter بلغة C# تستخلصها داخليًا من حالة IsViewerLicensed وIsTemporary للترخيص، ومعالج ?convert=run للواجهة يقوم بالتحقق المكافئ (IsViewerLicensed && !IsTrial && !IsTemporary) لملء الحقل watermarked الذي يُرجعه. يمكن بناء واختبار تكامل من الطرف إلى الطرف على ترخيص تقييم قبل الشراء — فقط بايتات الناتج تتغير.