ملحق المحول

ملحق المحول يحول 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 أينما احتجت إليه — فهو بلا حالة حسب التصميم، لذا يمكن إعادة استخدام نسخة واحدة بأمان عبر الطلبات.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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 — فهو لا يمنح حقوق التحويل بمفرده.

تخصيص العنصر

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

الاستدعاءات:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

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

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

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

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

أوضاع الفشل، مُجمَّعة حسب المسار

ملكية الموارد

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

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

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

العلامة المائية

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

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