يأتي Discourse 3.1.0.beta6 مع واجهة برمجة تطبيقات جديدة تماماً قائمة على المكوّن <DModal>. يعد DModal جزءاً من حزمة واجهة المستخدم ويتم استيراده من discourse/ui-kit/d-modal.
يحل هذا محل واجهة برمجة التطبيقات القديمة القائمة على المتحكمات (controllers)، والتي أصبحت الآن غير مستحسنة. إذا كانت لديك نوافذ منبثقة (modals) تستخدم واجهات برمجة التطبيقات القديمة، فاطّلع على دليل الترحيل هنا.
عرض نافذة منبثقة (Modal)
تتم النوافذ المنبثقة عن طريق تضمين المكوّن <DModal> في قالب handlebars. إذا لم يكن لديك قالب مناسب بالفعل، فاطّلع على Using Plugin Outlet Connectors from a Theme or Plugin.
ستبدو النافذة المنبثقة البسيطة على النحو التالي:
<DButton
@translatedLabel="إظهار النافذة"
@action={{fn (mut this.modalIsVisible) true}}
/>
{{#if this.modalIsVisible}}
<DModal @title="نافذتي" @closeModal={{fn (mut this.modalIsVisible) false}}>
مرحباً بالعالم، هذا بعض المحتوى في نافذة منبثقة
</DModal>
{{/if}}
يُستخدم هنا
muthelper كطريقة خاصة بـ hbs لتحديد قيمة. يمكنك أيضاً تعيينmodalIsVisibleباستخدام أي طريقة Ember قياسية أخرى.
سيرجع هذا المثال نافذة منبثقة بسيطة كالتالي:
تغليفه في مكوّن
قبل تقديم أي تعقيد إضافي، من الأفضل عادةً تغليف نافذتك المنبثقة الجديدة في تعريف مكوّن خاص بها. لننقل محتويات <DModal> إلى داخل مكوّن جديد <MyModal />
// components/my-modal.gjs
<template>
<DModal @title="نافذتي" @closeModal={{@closeModal}}>
مرحباً بالعالم، هذا بعض المحتوى في نافذة منبثقة
</DModal>
</template>
سيسمح ترقية هذا الملف .gjs إلى مكوّن قائم على الكلاسات (class-based component) بتقديم منطق وحالة أكثر تعقيداً.
لاستخدام المكوّن الجديد، حدّث موقع الاستدعاء للإشارة إليه، مع التأكد من تمرير معامل @closeModal.
<DButton
@translatedLabel="إظهار النافذة"
@action={{fn (mut this.modalIsVisible) true}}
/>
{{#if this.modalIsVisible}}
<MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}
إضافة تذييل (Footer)
تحتوي العديد من النوافذ المنبثقة على نوع من أنواع الدعوات لاتخاذ إجراء. في Discourse، تميل هذه العناصر إلى أن تكون موجودة في أسفل النافذة المنبثقة. لجعل هذا ممكناً، يمتلك DModal عدداً من ‘الأجزاء المسماة’ (named blocks) التي يمكن أن يكون المحتوى مضمناً داخلها. إليك المثال المحدّث ليتضمن زرّين في التذييل، أحدهما هو زر DModalCancel القياسي الخاص بنا
<DModal @title="نافذتي" @closeModal={{@closeModal}}>
<:body>
مرحباً بالعالم، هذا بعض المحتوى في نافذة منبثقة
</:body>
<:footer>
<DButton class="btn-primary" @translatedLabel="إرسال" />
<DModalCancel @close={{@closeModal}} />
</:footer>
</DModal>
عرض نافذة منبثقة من سياق غير hbs
مثاليّاً، يجب عرض مثيلات <DModal> من داخل قالب Ember باستخدام التقنية التصريحية (declarative) الموضحة أعلاه. إذا لم يكن ذلك ممكناً لحالة الاستخدام الخاصة بك، فيمكن تحقيق ذلك من خلال حقن خدمة modal واستدعاء modal.show().
تأكد من تغليف النافذة المنبثقة الخاصة بك في مكوّن خاص بها كما هو موضح أعلاه. ثم، قم بتشغيل النافذة المنبثقة عن طريق تمرير مرجع إلى فئة المكوّن الخاصة بك إلى showModal:
import MyModal from "discourse/components/my-modal";
// (أدخل خدمة modal في المكان المناسب)
// أضف هذا الاستدعاء كلما أردت فتح النافذة المنبثقة.
// سيتم تمرير معامل `@closeModal` إلى المكوّن الخاص بك تلقائياً.
this.modal.show(MyModal);
// اختياريّاً، مرر مُعامل '`model`'. يمرر كـ `@model` إلى المكوّن الخاص بك.
// يمكن أن يتضمن هذا بيانات، وأيضاً إجراءات/استدعاءات رجعية (callbacks) لاستخدامها من قبل نافذتك المنبثقة.
this.modal.show(MyModal, {
model: { topic: this.topic, someAction: this.someAction },
});
// ترجع `modal.show()` وعداً (promise)، لذا يمكنك الانتظار حتى يتم إغلاقها
// سيتم حلها (resolve) مع البيانات الممررة إلى إجراء `@closeModal`
const result = await this.modal.show(MyModal);
مزيد من التخصيص!
يمتلك <DModal> عدداً من الأجزاء المسماة (named blocks) المعاملات.
المعاملات (Arguments)
| المعامل | الغرض |
|---|---|
@closeModal |
مطلوب لظهور واجهة الإغلاق تماماً. |
@title |
يعرض <h1 id="discourse-modal-title">؛ يربط aria-labelledby. |
@subtitle |
نص صغير أسفل العنوان. |
@flash / @flashType |
تنبيه مضمّن (inline alert) في أعلى النافذة المنبثقة (DFlashMessage). |
@hideHeader, @hideFooter |
إخفاء مناطق كاملة. |
@headerClass, @bodyClass |
فئة إضافية على أغلفة الرأس/المحتوى (header/body wrappers). |
@dismissable |
القيمة الافتراضية true عند تعيين @closeModal. يعطل مفتاح Esc / النقر على الخلفية / أيقونة X. |
@autofocus |
القيمة الافتراضية true. يركز تلقائياً على أول عنصر قابل للتركيز عبر dTrapTab. |
@submitOnEnter |
القيمة الافتراضية true. ينقر مفتاح Enter على .d-modal__footer .btn-primary ما لم يكن التركيز داخل نموذج / textarea / select-kit. |
@beforeClose |
async ({ initiatedBy }) => boolean. أعد false لإلغاء الإغلاق (مثل تأكيد نموذج غير محفوظ). |
@hidden |
يوقف معالجة لوحة المفاتيح؛ يُستخدم عندما تكون نافذة منبثقة متداخلة في الأعلى. |
@tagName |
"div" (افتراضي) أو "form". استخدم "form" للنماذج بحيث يعمل الإرسال الأصلي (native submit). |
الأجزاء (Blocks)
| الجزء | الموضع | متى يُستخدم |
|---|---|---|
default / :body |
منطقة المحتوى الرئيسية | المنطقة الافتراضية |
:aboveHeader |
أعلى الجزء تماماً، قبل الرأس | نادراً ما يكون مطلوباً؛ للمحتوى الذي يجب أن يظهر فوق شريط العنوان (مثل بانر). |
:headerAboveTitle |
داخل الرأس، قبل العنوان | موجود لكنه غير مستخدم. نادراً ما يكون مطلوباً. |
:belowModalTitle |
داخل .d-modal__title، بعد <h1> |
موضع ممتاز للمعلومات الوصفية التكميلية. |
:headerBelowTitle |
داخل الرأس، بعد كتلة العنوان | علامات التبويب، التنقل الفرعي، أو إدخال البحث الذي يعتبر جزءاً من الرأس. |
:headerPrimaryAction |
الجانب الأيمن من الرأس على الهاتف المحمول فقط | يستبدل زر الإغلاق X بإجراء أساسي (مثل “حفظ”). كما يعرض تلقائياً زر “إلغاء” على اليسار ويضيف .--has-primary-action إلى الرأس. |
:belowHeader |
بين الرأس والمحتوى | محتوى رأس فرعي دائم (مثل شريط البحث) يقع خارج منطقة المحتوى القابلة للتمرير، مما يتيح عرضاً ثابتاً (sticky display). |
:aboveFooter |
بين المحتوى والتذييل | يتم قمعها عند تعيين @hideFooter. استخدمها للمحتوى المرتبط بالتذييل لكنه خارجه. نادراً ما تكون مطلوبة. |
:footer |
شريط الإجراءات السفلي | الأزرار الأساسية والثانوية. أول .btn-primary هنا هو ما يحفزه مفتاح Enter. |
:belowFooter |
بعد التذييل | نادراً ما يكون مطلوباً؛ يتجاهل @hideFooter. مفيد لنص الحالة خارج منطقة التذييل المحددة بإطار. |
المصادر: دليل الأنماط التفاعلي للمعاملات، و تنفيذ قالب d-modal للأجزاء المسماة (named blocks).
CSS
استخدم فئات .d-modal كنقطة ارتكاز (anchor) لتجاوز الأساسي، وتجنب المحدد القديم .modal.
هناك 4 معدِّلات (modifiers) متاحة:
.d-modal--largeيضبط أقصى عرض إلى 800px (سطح المكتب فقط).d-modal--maxيضبط أقصى عرض إلى 90vw (سطح المكتب فقط).d-modal--has-searchيضبط ارتفاعاً ثابتاً (80vh): مقصود للنوافذ المنبثقة التي تحتوي على نظام بحث/تصفية لتجنب تغير الارتفاع بناءً على طول النتائج (سطح المكتب فقط).d-modal--stackedيجعل أزرار التذييل مكدسة عمودياً (الهاتف المحمول فقط)
هذا المستند خاضع لمراقبة الإصدارات - اقترح تغييرات على GitHub.

