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

[Discourse]

يأتي Discourse 3.1.0.beta6 مع واجهة برمجة تطبيقات (API) جديدة بالكامل تعتمد على مكون <DModal>.

هذه الواجهة تحل محل واجهة التحكم القديمة القائمة على المتحكمات (controllers)، والتي أصبحت الآن غير مستخدمة. إذا كان لديك نوافذ منبثقة (modals) موجودة تستخدم واجهات API القديمة، راجع دليل الترحيل هنا.

عرض نافذة منبثقة (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}}

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

تحتوي العديد من النوافذ المنبثقة على نوع من الدعوة لاتخاذ إجراء (call-to-action). في 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 باستخدام التقنية التصريحية الموضحة أعلاه. إذا لم يكن ذلك ممكنًا لحالتك الاستخدامية، فيمكن القيام بذلك عن طريق حقن خدمة 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)، لذا يمكنك الانتظار حتى يتم إغلاقه
// سيتم حله بالبيانات الممررة إلى إجراء `@closeModal`
const result = await this.modal.show(MyModal);

المزيد من التخصيص!

يحتوي <DModal> على عدد من الكتل المسماة والوسائط. راجع دليل الأنماط التفاعلي للوسائط، و تنفيذ قالب d-modal للكتل المسماة.

---

يخضع هذا المستند للتحكم في الإصدار - اقترح التغييرات على GitHub.