مقدمة
@powerduck/md-editor محرّر Markdown عالي الأداء يمكن تضمينه في المتصفح. يجمع بين مساحة تحرير CodeMirror 6 ومعاينة مباشرة يعرضها markdown-it، ويضيف معادلات KaTeX والخرائط الذهنية Markmap وتلوين الشيفرة وكتل التنبيه وشريط أدوات قابلًا للتخصيص واختصارات لوحة المفاتيح وخطافات رفع الصور و@الإشارات وإدراج روابط المستندات.
- اسم الحزمة:
@powerduck/md-editor - الترخيص: MIT
- صيغة الوحدة: وحدة ECMAScript (
type: "module")، مع بنائي ESM (dist/index.mjs) وCJS (dist/index.cjs) وتعريفات الأنواع المرفقة (dist/index.d.ts).
الميزات الأساسية
تستند الميزات التالية إلى الوحدات المنفّذة في الشيفرة المصدرية:
- تحرير Markdown باستخدام CodeMirror 6، مع تلوين صياغة Markdown وسِمات تلوين فاتحة وداكنة.
- معادلات KaTeX عبر إضافة مستقلة لـ markdown-it: ضمن السطر
$...$أو في كتلة$$...$$. تُستثنى القيم النقدية مثل$5من تحليل المعادلات باستخدام قواعد استدلالية. - خرائط Markmap الذهنية من كتل الشيفرة المحددة بـ
```mindmap. تُستورد markmap-lib وmarkmap-view ديناميكيًا، فلا تزيدان حجم الحزمة المحمّلة أولًا عند عدم وجود خرائط ذهنية. - تلوين الشيفرة باستخدام highlight.js، مع ترويسة بثلاث نقاط ملوّنة على نمط macOS واسم اللغة وزر للنسخ بنقرة واحدة.
- كتل التنبيه (
:::noticeو:::infoو:::tipو:::successو:::warningو:::danger) مع أيقونات وألوان مناسبة. - معاينة بنمط GitHub باستخدام
github-markdown-css. - شريط أدوات متكامل يضم 22 إجراءً ونوافذ لإدراج الصور والفيديو وYouTube والجداول، واختيار قوالب المعادلات والخرائط الذهنية، ونافذة مساعدة تسرد جميع الاختصارات.
- اختصارات لوحة المفاتيح باستخدام
Modالذي يقابل Ctrl في Windows/Linux وCmd في macOS. - شريط أدوات قابل للتخصيص عبر مصفوفة بالعناصر المطلوب إظهارها أو إعدادات لكل عنصر (
showوlabelوicon). - خطاف رفع الصور (
onImageUpload) يُستدعى عند لصق صورة في المحرّر أو سحبها وإفلاتها فيه. - قائمة @الإشارات المنسدلة تُضبط عبر خيارات
mention، وتظهر الإشارات المختارة كشارات منسّقة في المعاينة. - إدراج روابط المستندات يُضبط عبر
docLink: روابط عادية أو بطاقات معاينة:::doc-link. يجلب المحمّل المضمّن أو خطاف مخصّص البيانات الوصفية؛ وتخضع الطلبات بين المصادر المختلفة لقواعد CORS في المتصفح. - عرض الفيديو: تتحول صياغة الصور ذات URL المنتهي بـ
.mp4أو.webmأو.oggأو امتداد معروف آخر إلى عنصر<video controls>. - عارض مستقل (
renderMarkdown(source, options)) ينتج HTML بالإضافات والأنماط نفسها المستخدمة في المعاينة دون تركيب محرّر. - عرض تزايدي على مستوى الكتل: يُقسَّم المصدر عند عناوين ATX ولا يُعاد عرض إلا الكتل المتغيرة. تعيد الكتل الأخرى استخدام عقد DOM الحالية، بما فيها رسوم SVG للخرائط الذهنية التي سبق تهيئتها. تُخزَّن النتائج مؤقتًا حسب بصمة المحتوى.
- تأخير تكيفي: يتغير تأخير تحديث المعاينة بحسب طول المستند، من 120 مللي ثانية إلى حد أقصى 600 مللي ثانية.
- وضعا تحرير:
simpleللتحرير والمعاينة دون شريط أدوات، وcomplexمع شريط أدوات وشريط حالة، مع إمكانية التبديل أثناء التشغيل. - سِمتان:
lightوdark، تُطبَّقان عبر السمةdata-themeوخصائص CSS المخصّصة.
نظرة عامة على البنية
توفّر المكتبة واجهتين:
-
صنف JavaScript مباشر — تتمحور الواجهة الأساسية حول
MarkdownEditorالذي يُنشأ باستخدام عنصر حاوية. يجمعCodeEditor(غلاف CodeMirror) وRenderer(غلاف markdown-it) وIncrementalRendererللمعاينة، ويضيفToolbarوStatusBarفي وضعcomplex. النوافذ المنبثقة ومتحكّم @الإشارات ومتحكّم روابط المستندات وحدات تُركَّب عند الحاجة. -
تصدير React عبر مسار فرعي —
MarkdownEditorReactمكوّنforwardRefيُصدَّر من./react. يغلّف مثيلMarkdownEditorالمباشر ويدعم الاستخدام المتحكَّم به وغير المتحكَّم به لـvalue، ويتيحMarkdownEditorHandleأمريًا عبر ref. نقطة دخول React منفصلة حتى لا تُلزم المشاريع التي لا تستخدم React بتثبيتreactوreact-dom.
ينقسم العرض إلى مرحلة markdown-it متزامنة تنتج HTML مؤقتًا للخرائط الذهنية، ثم تهيئة غير متزامنة باستخدام Renderer.hydrate لتحويله إلى مخططات SVG تفاعلية. تُرجع renderMarkdown نص HTML المتزامن؛ لإنشاء SVG للخرائط، استخدم Renderer.render ثم أدرج HTML في DOM واستدعِ Renderer.hydrate. يعمل العارض التزايدي مباشرةً على حاوية المعاينة.
دعم المتصفحات
تستهدف المكتبة المتصفحات الحديثة التي توفّر DOM. CodeMirror 6 وKaTeX وmarkmap-view اعتماديات للحزمة وليست ميزات في المتصفح؛ وتستخدم الخرائط الذهنية التفاعلية ResizeObserver. تُستخدم Clipboard API عند توفرها. إذا تعذّر استخدام navigator.clipboard، مثلًا خارج HTTPS، يُستخدم document.execCommand('copy') لنسخ كتل الشيفرة. لا تثبّت وحدة الخرائط تطبيقًا فارغًا لـ ResizeObserver إلا عند غياب الكائن العام، لتجنب خطأ الاستيراد بسبب غيابه؛ ولا يوفّر هذا التطبيق إشعارات فعلية بتغير الحجم.
الترخيص
تُوزَّع @powerduck/md-editor بموجب ترخيص MIT.