عرض مصدر Bootstrap/toasts

<noinclude>{{DISPLAYTITLE:مكوِّن النخب Toasts في إطار العمل Bootstrap}}</noinclude>
أظهر إشعارات لزوارك عبر مكونات النخب (toast‎s)، وهي رسائل تنبيه قابلة للتخصيص بسهولة.

النخب هي إشعارات مُصمّمة لمحاكاة الإشعارات الفورية التي انتشرت في أنظمة تشغيل الجوالات وسطح المكتب. وقد بُنِيت باستخدام [[Bootstrap/flex|flexbox]]، لذا يسهُل محاذاتها وضبطها.

== نظرة عامة ==
هذه أشياء ينبغي أن تعرفها عند استخدام مكونات النخب:
* إن أردت بناء [[JavaScript]] من المصدر، فاعلم أنّ ذلك يتطلب [[Bootstrap/javascript#Util|util.js]].
* النخب اختيارية لأسباب تتعلق بالأداء، لذا '''يجب عليك تهيئتها بنفسك'''.
* '''يرجى ملاحظة أنك مسؤول عن تحديد مواضع النخب'''
* إن لم تعيّن الخاصية <code>autohide: false</code>، فستُخفى النخب تلقائيًا.
'''ملحوظة''': تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط <code>prefers-reduced-motion</code>، راجع [[Bootstrap/accessibility|صفحة سهولة الوصول]] لمزيد من المعلومات

== أمثلة ==

=== أمثلة قاعدية ===
ننصح باستخدام ترويسة ومتن في مكونات النخب لجعلها واضحة ومتوقعة. تستخدم ترويسات النخب <code>display: flex</code>، ممّا يسهّل محاذاة محتوياتها بفضل أدوات التحكم في الهامش وأدوات flexbox .

تتمتع النخب بمرونة عالية، ولا تتطلب إلا القليل من الترميز. إذ تتطلب النخب  كحدّ أدنى عنصرًا واحدًا لاحتواء محتوياتها. ننصح كذلك بإضافة زر استبعاد.<syntaxhighlight lang="html">
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small>قبل 11 دقيقة</small>
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <div class="toast-body">
    مرحبا بالعالم، هذه رسالة نخب
  </div>
</div>
</syntaxhighlight>

=== الشفافية ===
مكونات النخب شبه شفافة، لذلك تمتزج مع المكونات التي تظهر فوقها. بالنسبة للمتصفحات التي تدعم خاصية <code>filter-backdrop</code>، ستحاول أيضًا طمس العناصر الموجودة تحت مكون النخب.<syntaxhighlight lang="html">
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small class="text-muted">قبل 11 دقيقة</small>
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <div class="toast-body">
    مرحبا بالعالم، هذه رسالة نخب
  </div>
</div>

</syntaxhighlight>

=== تكديس مكونات النخب ===
إن عُرِضت عدّة مكونات نخب في الوقت نفسه، فإنّ Bootstrap ستكدسها رأسيًا لتجعلها قابلة للقراءة.<syntaxhighlight lang="html">
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small class="text-muted">الآن</small>
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <div class="toast-body">
    أرأيت؟ هكذا تماما
  </div>
</div>

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small class="text-muted">قبل ثانيتين</small>
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <div class="toast-body">
    ستُكدس مكونات النخب تلقائيا
  </div>
</div>
</syntaxhighlight>

== التموضع ==
حدد مواضع مكونات النخب عبر أنماط CSS مخصصة. غالبًا ما يُستخدم الجزء العلوي الأيمن والجزء العلوي الأوسط للإشعارات. إذا كنت ستكتفي بعرض نخب واحد فقط في كل مرة، فضع أنماط تحديد الموضع مباشرة على النخب <code>‎.toast</code>‎.<syntaxhighlight lang="html">
<div aria-live="polite" aria-atomic="true" style="position: relative; min-height: 200px;">
  <div class="toast" style="position: absolute; top: 0; right: 0;">
    <div class="toast-header">
      <img src="..." class="rounded mr-2" alt="...">
      <strong class="mr-auto">Bootstrap</strong>
      <small>قبل 11 دقيقة</small>
      <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
        <span aria-hidden="true">&times;</span>
      </button>
    </div>
    <div class="toast-body">
      مرحبا بالعالم، هذه رسالة نخب
    </div>
  </div>
</div>
</syntaxhighlight>

إن كنت تتوقع أن تستخدم عدة إشعارات، فضعها في غلاف حتى يسهُل تكديسها.<syntaxhighlight lang="html">
<div aria-live="polite" aria-atomic="true" style="position: relative; min-height: 200px;">
  <!-- الموضع -->
  <div style="position: absolute; top: 0; right: 0;">

    <!-- Then put toasts within -->
    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded mr-2" alt="...">
        <strong class="mr-auto">Bootstrap</strong>
        <small class="text-muted">الآن</small>
        <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="toast-body">
        أرأيت، هكذا تماما
      </div>
    </div>

    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded mr-2" alt="...">
        <strong class="mr-auto">Bootstrap</strong>
        <small class="text-muted">قبل ثانيتين</small>
        <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="toast-body">
        ستُكدّس مكونات النخب تلقائيا
      </div>
    </div>
  </div>
</div>
</syntaxhighlight>

يمكنك أيضًا التوسع في تصميم النخب باستخدام [[Bootstrap/flex|أدوات Flexbox]] لمحاذاة النخب أفقيًا و / أو عموديًا.<syntaxhighlight lang="html">
<!-- حاوية مرنة لمحاذاة مكونات النخب -->
<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center" style="min-height: 200px;">

  <!-- ضع النخب هنا -->
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded mr-2" alt="...">
      <strong class="mr-auto">Bootstrap</strong>
      <small>قبل 11 دقيقة</small>
      <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
        <span aria-hidden="true">&times;</span>
      </button>
    </div>
    <div class="toast-body">
     مرحبا بالعالم، هذه رسالة نخب
    </div>
  </div>
</div>
</syntaxhighlight>

== سهولة الوصول ==
صُمِّمت مكونات النخب لتقاطع المستخدم مقاطعة سريعة، إن أردت مساعدة الزوار الذين يستخدمون قارئات شاشة والتقنيات المساعدة المماثلة، يجب عليك تغليف مكونات النخب في [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions منطقة حية <code>aria-live</code>]. يتم الإعلان تلقائيًا عن التغييرات التي تطرأ على المناطق الحية (مثل عمليات إدخال / تحديث مكونات النخب) من قبل برامج قراءة الشاشة دون الحاجة إلى تشتيت تركيز المستخدم أو مقاطعته. احرص - علاوة على ذلك - على تضمين <code>aria-atomic = "true"</code>‎ لتتأكد من  الإعلان عن مكونات النخب دائمًا كوحدة (ذرية) واحدة، بدلاً من الاكتفاء بالإعلان عما تمّ تغييره (والذي قد يؤدّي إلى مشاكل في حال اكتفيت بتحديث جزء فقط من محتوى النخب، أو في حال عرض محتوى النخب نفسه في وقت لاحق). إذا كانت المعلومات المعروضة مهمة للعملية، كأن تعرض قائمة بالأخطاء في استمارة يملؤها الزائر، حينئذ قد يكون الأفضل أن تستخدم [[Bootstrap/alerts|مكوّنات التنبيه]] بدلاً من النخب.

تذكر أنّ المنطقة الحية يجب أن تكون موجودة في الترميز قبل إنشاء مكونات النخب أو تحديثها. إذا أنشأتهما ديناميكيًا في الوقت نفسه ثمّ أدرجتهما في الصفحة، فلن تعلن عنهما  التقنيات المساعدة عموما.

تحتاج أيضًا إلى تعديل الدور <code>role</code> ومستوى <code>aria-live</code> بناءً على المحتوى. إذا كانت الرسالة المعروضة مهمة، مثل عرض رسالة خطأ، فاستخدم <code>role = "alert" aria-live = "assertive"‎</code>، وإلا فاستخدم الخاصيات <code>role = "status" aria-live = "polite"‎</code>.

في أثناء تغير المحتوى المعروض، تأكد من تحديث مهلة التأخير حتى يتسنّى للناس الوقت الكافي لقراءة محتوى النخب.<syntaxhighlight lang="html">
<div class="toast" role="alert" aria-live="polite" aria-atomic="true" data-delay="10000">
  <div role="alert" aria-live="assertive" aria-atomic="true">...</div>
</div>
</syntaxhighlight>

في حال استخدام <code>autohide: false</code>، سيكون عليك إضافة زر إغلاق للسماح للمستخدمين بإغلاق النخب.<syntaxhighlight lang="html">
<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-autohide="false">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small>قبل 11 دقيقة</small>
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <div class="toast-body">
    مركبا بالعالم، هذه رسالة نخب
  </div>
</div>
</syntaxhighlight>

== سلوك JavaScript ==

=== طريقة الاستخدام ===
يمكنك تهيئة النخب عبر  JavaScript:<syntaxhighlight lang="javascript">
$('.toast').toast(option)

</syntaxhighlight>

=== خيارات ===
يمكن تمرير الخيارات عبر خاصيات البيانات أو جافا سكربت. فيما بخص خاصيات البيانات، ألحق اسم الخيار بـ <code>data-</code>‎، كما في <code>data-animation = ""</code>‎.

{| class="wikitable"
!الاسم
!النوع
!القيمة المبدئيّة
!الوصف
|-
|<code>animation</code> (التحريك)
|قيمة منطقيّة
|<code>true</code>
|تطبيق تأثير الخفوت في CSS على مكون النخب.
|-
|<code>autohide</code> (الإخفاء التلقائي)
| سلسلة محارف |قيمة منطقيّة
|<code>true</code>
|الإخفاء التلقائي للنخب
|-
|<code>delay</code> (تأخير)
| سلسلة محارف |عدد
|<code>500</code>
|تأخير إخفاء النخب (ملي ثانية)
|}

=== توابع ===
'''تنبيه: التوابع غير المتزامنة والانتقالات'''

توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال. راجع صفحة [[Bootstrap/javascript|javascript]] لمزيد من التفاصيل.

‎<code>$().toast(options)‎</code>

ربط معالج نخب (toast handler) بمجموعة عناصر.

‎<code>.toast('show')‎</code>

إظهار مكوّن النخب '''والعودة إلى المُستدعي قبل إظهار النخب فعليا''' (أي قبل وقوع الحدث <code>shown.bs.toast</code>). عليك استدعاء هذا التابع يدويًا وإلا فلن يظهر النخب.<syntaxhighlight lang="javascript">
$('#element').toast('show')

</syntaxhighlight>‎<code>.toast('hide')‎</code>

إخفاء مكون النخب '''والعودة إلى المُستدعي قبل إخفاء النخب فعليا''' (أي قبل وقوع الحدث <code>hidden.bs.toast</code>). عليك استدعاء هذا التابع يدويًا في حال عيّنت قيمة الخاصية <code>autohide</code> إلى <code>false</code>.<syntaxhighlight lang="javascript">
$('#element').toast('hide')

</syntaxhighlight>‎<code>.toast('dispose')‎</code>

إخفاء مكون النخب. سيبقى مكون النخب في شجرة DOM، بيد أنّه لن يظهر بعدها.<syntaxhighlight lang="javascript">
$('#element').toast('dispose')

</syntaxhighlight>الأحداث
{| class="wikitable"
!نوع الحدث
!الوصف
|-
|<code>show.bs.toast</code>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>show</code>.
|-
|<code>shown.bs.toast</code>
|يُطلَق هذا الحدث عندما يصبح مكون النخب ظاهرا للزائر.
|-
|<code>hide.bs.toast</code>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>hide</code> .
|-
|<code>hidden.bs.toast</code>
|يُطلَق هذا الحدث عندما يكتمل إخفاء مكون النخب عن الزائر .
|}<syntaxhighlight lang="javascript">
$('#myToast').on('hidden.bs.toast', function () {
  // افعل شيئا ما
})
</syntaxhighlight>

== مصادر ==
* [https://getbootstrap.com/docs/4.5/components/toasts/ صفحة toasts في توثيق Bootstrap].
[[تصنيف:Bootstrap|{{SUBPAGENAME}}]]
[[تصنيف:Bootstrap components|{{SUBPAGENAME}}]]