ملحق المحول

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

تثبيت الحزمة

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

dotnet add package Doconut.NET6.Converter

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

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

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

تسجيل الملحق

لا توجد طريقة 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>();
});

يثير هذا الاستدعاء خطأً عند بدء التشغيل بسبب ترخيص مفقود، أو ملف 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") — وهو عكس الاتفاقية للمعامل sourceExtension على DocumentConverter.ConvertAsync، الذي يتطلب واحدة.

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

ملكية المورد

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

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

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

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

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

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