استخدام واجهة برمجة التطبيقات DModal لعرض النوافذ المنبثقة (المعروفة أيضًا بالنوافذ المنبثقة أو مربعات الحوار) في Discourse

يأتي Discourse 3.1.0.beta6 مع واجهة برمجة تطبيقات جديدة تماماً قائمة على المكوّن <DModal>. يعد DModal جزءاً من حزمة واجهة المستخدم ويتم استيراده من discourse/ui-kit/d-modal.

:information_source: يحل هذا محل واجهة برمجة التطبيقات القديمة القائمة على المتحكمات (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}}

:information_source: يُستخدم هنا mut helper كطريقة خاصة بـ 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.

17 إعجابًا

تم تقسيم منشور إلى موضوع جديد: هل يمكنني عرض نافذة منبثقة من head_tag