الفرق بين المراجعتين ل"Bootstrap/toasts"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:مكوِّن النخب Toasts في إطار العمل Bootstrap}}</noinclude> استفد من رسائل التنبيه المرنة التي...')
 
سطر 1: سطر 1:
 
<noinclude>{{DISPLAYTITLE:مكوِّن النخب Toasts في إطار العمل Bootstrap}}</noinclude>
 
<noinclude>{{DISPLAYTITLE:مكوِّن النخب Toasts في إطار العمل Bootstrap}}</noinclude>
−
استفد من رسائل التنبيه المرنة التي يوفّرها إطار العمل Bootstrap لإظهار رسائل تغذيّة راجعة للإجراءات النمطيّة التي يقوم بها الزوّار.
+
أظهر إشعارات لزوارك عبر مكونات النخب (toast‎s)، وهي رسائل تنبيه قابلة للتخصيص بسهولة.
 +
 
 +
النخب هي إشعارات مُصمّمة لمحاكاة الإشعارات الفورية التي انتشرت في أنظمة تشغيل الجوالات وسطح المكتب. وقد بُنِيت باستخدام [[Bootstrap/flex|flexbox]]، لذا يسهُل محاذاتها وضبطها.
 +
 
 +
== نظرة عامة ==
 +
هذه أشياء ينبغي أن تعرفها عند استخدام مكونات النخب:
 +
* إن أردت بناء [[JavaScript]] من المصدر، فاعلم أنّ ذلك يتطلب [[Bootstrap/javascript#Util|util.js]].
 +
* النخب اختيارية لأسباب تتعلق بالأداء، لذا '''يجب عليك تهيئتها بنفسك'''.
 +
* '''يرجى ملاحظة أنك مسؤول عن تحديد مواضع النخب'''
 +
* إن لم تعيّن الخاصية <code>autohide: false</code>، فستُخفى النخب تلقائيًا.
 +
'''ملحوظة''': تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط <code>prefers-reduced-motion</code>، راجع [[Bootstrap/accessibility|صفحة سهولة الوصول]] لمزيد من المعلومات
  
 
== أمثلة ==
 
== أمثلة ==
−
تتوفّر التنبيهات Alerts بصيغة نصوص غير محدودة الطول، كما تتوفّر بصيغة أزرار تجاهل اختياريّة. استخدم واحدًا من أصناف السيّاق الثمانيّة '''الإجباريّة''' من أجل الحصول على تنسيق صحيح للتنبيهات (مثلًا للتنبيه على نجاح إجراء <code>‎.alert-success</code>). استخدم مُلحَق تنبيهات jQuery إنْ أردت توفير أزرار تجاهل سطريّة Inline.<syntaxhighlight lang="html">
+
 
−
<div class="alert alert-primary" role="alert">
+
=== أمثلة قاعدية ===
−
  هذا تنبيه أوّليّّ —تحقّق منه!
+
ننصح باستخدام ترويسة ومتن في مكونات النخب لجعلها واضحة ومتوقعة. تستخدم ترويسات النخب <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>
 
</div>
−
<div class="alert alert-secondary" role="alert">
+
</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>
 
</div>
−
<div class="alert alert-success" role="alert">
+
 
−
   هذا تنبيه على نجاح إجراء —تحقّق منه!
+
</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>
−
<div class="alert alert-danger" role="alert">
+
 
−
   هذا تنبيه على خطر —تحقّق منه!
+
<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 class="alert alert-warning" role="alert">
+
</syntaxhighlight>
−
  هذا تنبيه للاحتياط —تحقّق منه!
+
 
−
</div>
+
== التموضع ==
−
<div class="alert alert-info" role="alert">
+
حدد مواضع مكونات النخب عبر أنماط CSS مخصصة. غالبًا ما يُستخدم الجزء العلوي الأيمن والجزء العلوي الأوسط للإشعارات. إذا كنت ستكتفي بعرض نخب واحد فقط في كل مرة، فضع أنماط تحديد الموضع مباشرة على النخب <code>‎.toast</code>‎.<syntaxhighlight lang="html">
−
  هذا تنبيه لإعطاء معلومات —تحقّق منه!
+
<div aria-live="polite" aria-atomic="true" style="position: relative; min-height: 200px;">
−
</div>
+
  <div class="toast" style="position: absolute; top: 0; right: 0;">
−
<div class="alert alert-light" role="alert">
+
    <div class="toast-header">
−
  هذا تنبيه خفيف —تحقّق منه!
+
      <img src="..." class="rounded mr-2" alt="...">
−
</div>
+
      <strong class="mr-auto">Bootstrap</strong>
−
<div class="alert alert-dark" role="alert">
+
      <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>
 
</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>
 
</syntaxhighlight>
  
−
==== توصيل المعنى إلى التقنيّات المساعدة ====
+
يمكنك أيضًا التوسع في تصميم النخب باستخدام [[Bootstrap/flex|أدوات Flexbox]] لمحاذاة النخب أفقيًا و / أو عموديًا.<syntaxhighlight lang="html">
−
يقتصر المعنى - عند الاقتصار على استخدام اللّون لنقله – على الدّلالة البصريّة، وبالتالي لن يصل  المعنى المطلوب إلى التقنيّات المساعدة للزوّار (مثل قارئات الشاشة). تأكّد من أنّ المعلومة التي يشير إليها اللّون إمّا بديهيّة من المحتوى نفسِه (أيّ النصّ المرئي) أو أنّها أُضيفت بوسائل بديلة مثل نصّ  مخفيّ بالصّنف <code>‎.sr-only</code>.
+
<!-- حاوية مرنة لمحاذاة مكونات النخب -->
 +
<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center" style="min-height: 200px;">
  
−
=== لون الرابط ===
+
  <!-- ضع النخب هنا -->
−
استخدم الصّنف الخدمي<code>‎.alert-link</code> لتوفير روابط متماشية مع التنسيقات ضمن التنبيهات.<syntaxhighlight lang="html">
+
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
−
<div class="alert alert-primary" role="alert"> هذا تنبيه أوّليّ يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
+
    <div class="toast-header">
−
</div>
+
      <img src="..." class="rounded mr-2" alt="...">
−
<div class="alert alert-secondary" role="alert">
+
      <strong class="mr-auto">Bootstrap</strong>
−
  هذا تنبيه ثانويّ يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
+
      <small>قبل 11 دقيقة</small>
−
</div>
+
      <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
−
<div class="alert alert-success" role="alert">
+
        <span aria-hidden="true">&times;</span>
−
  هذا تنبيه على نجاح إجراء يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
+
      </button>
−
</div>
+
    </div>
−
<div class="alert alert-danger" role="alert">
+
    <div class="toast-body">
−
  هذا تنبيه على خطر يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
+
    مرحبا بالعالم، هذه رسالة نخب
−
</div>
+
    </div>
−
<div class="alert alert-warning" role="alert">
+
   </div>
−
  هذا تنبيه للاحتيّاط يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
 
−
</div>
 
−
<div class="alert alert-info" role="alert">
 
−
  هذا تنبيه لإعطاء ملعومات يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
 
−
</div>
 
−
<div class="alert alert-light" role="alert">
 
−
  هذا تنبيه خفيف يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
 
−
</div>
 
−
<div class="alert alert-dark" role="alert">
 
−
   هذا تنبيه غامق يوجد به <a href="#" class="alert-link">مثال على رابط</a>. جرّب النقر عليه.
 
 
</div>
 
</div>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== عناصر HTML داخل التنبيهات ===
+
== سهولة الوصول ==
−
يمكن أن تحتوي التنبيهات على عناصر HTML مثل الترويسات، والفقرات والخطوط الفاصلة (<code>[[HTML/hr|<nowiki><hr></nowiki>]]</code>).<syntaxhighlight lang="html">
+
صُمِّمت مكونات النخب لتقاطع المستخدم مقاطعة سريعة، إن أردت مساعدة الزوار الذين يستخدمون قارئات شاشة والتقنيات المساعدة المماثلة، يجب عليك تغليف مكونات النخب في [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions منطقة حية <code>aria-live</code>]. يتم الإعلان تلقائيًا عن التغييرات التي تطرأ على المناطق الحية (مثل عمليات إدخال / تحديث مكونات النخب) من قبل برامج قراءة الشاشة دون الحاجة إلى تشتيت تركيز المستخدم أو مقاطعته. احرص - علاوة على ذلك - على تضمين <code>aria-atomic = "true"</code>‎ لتتأكد من الإعلان عن مكونات النخب دائمًا كوحدة (ذرية) واحدة، بدلاً من الاكتفاء بالإعلان عما تمّ تغييره (والذي قد يؤدّي إلى مشاكل في حال اكتفيت بتحديث جزء فقط من محتوى النخب، أو في حال عرض محتوى النخب نفسه في وقت لاحق). إذا كانت المعلومات المعروضة مهمة للعملية، كأن تعرض قائمة بالأخطاء في استمارة يملؤها الزائر، حينئذ قد يكون الأفضل أن تستخدم [[Bootstrap/alerts|مكوّنات التنبيه]] بدلاً من النخب.
−
<div class="alert alert-success" role="alert">
+
 
−
  <h4 class="alert-heading">جيّد جدّا!</h4>
+
تذكر أنّ المنطقة الحية يجب أن تكون موجودة في الترميز قبل إنشاء مكونات النخب أو تحديثها. إذا أنشأتهما ديناميكيًا في الوقت نفسه ثمّ أدرجتهما في الصفحة، فلن تعلن عنهما  التقنيات المساعدة عموما.
−
  <p>لقد فعلتها، لقد قرأت هذه الرسالة التنبيهيّة المهمّة، هذه. النصّ في هذا المثال طويل نوعًا مّا لترى كيف يعمل التباعد مع هذا النوع من المحتوى داخل التنبيهات</p>
 
−
  <hr>
 
−
  <p class="mb-0">استخدم أدوات الهوامش كلّ ما دعت الحاجة، حتى تبقى الأمور رائعةً ومُرتّبة</p>
 
−
</div>
 
  
 +
تحتاج أيضًا إلى تعديل الدور <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>
 
</syntaxhighlight>
  
−
=== تجاهل التنبيهات ===
+
في حال استخدام <code>autohide: false</code>، سيكون عليك إضافة زر إغلاق للسماح للمستخدمين بإغلاق النخب.<syntaxhighlight lang="html">
−
يمكن باستخدام مُلحَق JavaScript الخاصّ بالتنبيهات إضافة أزرار تجاهل على نفس السّطر:
+
<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-autohide="false">
−
* تأكّد من تحميل مُلحَق التنبيهات، أو النسخة المُجمَّعة من JavaScript الخاصّة بإطار العمل Bootstrap.
+
  <div class="toast-header">
−
* إن كنت تُجمِّع JavaScript بنفسك من المصدر فانتبه إلى أنّ المُلحَق يحتاج إلى [[Bootstrap/javascript#Util|الملفّ Util]]. هذا الملفّ مُضمَّن في النسخة المُجمَّعة.
+
    <img src="..." class="rounded mr-2" alt="...">
−
* أضف زرّ تجاهل والصّنف ‎<code>.alert-dismissible</code> الذي يضيف حاشية إضافيّة إلى اليمين ويحدّد موضع الزرّ <code>‎.close</code> .
+
    <strong class="mr-auto">Bootstrap</strong>
−
* أضف الخاصيّة <code>‎data-dismiss="alert"‎</code> إلى زرّ التجاهل الذي يفعّل الوظيفة في JavaScript. تأكّد من استخدام العنصُر <code>[[HTML/button|<button>]]</code> لتطبيق زرّ التجاهل من أجل الحصول على سلوك مناسب على جميع الأجهزة.
+
    <small>قبل 11 دقيقة</small>
−
* تأكّد من إضافة الصّنفيْن  <code>‎.fade</code> و <code>‎.show</code> إلى التنبيه لإضافة تأثيرات عليه بعد النقر على زرّ التجاهل.
+
    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
−
جرّب المثال التالي:<syntaxhighlight lang="html">
+
      <span aria-hidden="true">&times;</span>
−
<div class="alert alert-warning alert-dismissible fade show" role="alert">
+
    </button>
−
  <strong>انتبه!</strong> يجب أن تتحقّق من بعضٍ من الحقول الموجودة في الأسفل.
+
   </div>
−
  <button type="button" class="close" data-dismiss="alert" aria-label="Close">
+
  <div class="toast-body">
−
    <span aria-hidden="true">&times;</span>
+
    مركبا بالعالم، هذه رسالة نخب
−
   </button>
+
  </div>
 
</div>
 
</div>
 +
</syntaxhighlight>
  
 +
== سلوك JavaScript ==
 +
 +
=== طريقة الاستخدام ===
 +
يمكنك تهيئة النخب عبر  JavaScript:<syntaxhighlight lang="javascript">
 +
$('.toast').toast(option)
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== سلوك JavaScript ==
+
=== خيارات ===
 +
يمكن تمرير الخيارات عبر خاصيات البيانات أو جافا سكربت. فيم بخص خاصيات البيانات، ألحق اسم الخيار بـ <code>data-</code>‎، كما في <code>data-animation = ""</code>‎.
  
−
=== المُنشِّطات Triggers ===
 
−
يمكن تفعيل إمكانيّة تجاهل تنبيه بواسطة JavaScript:<syntaxhighlight lang="javascript">
 
−
$('.alert').alert()
 
−
</syntaxhighlight>كما يمكن استخدام خاصيّات <code>data</code> على زرّ '''داخل التنبيه''' كما في المثال الأخير ضمن فقرة التجاهل:<syntaxhighlight lang="html">
 
−
<button type="button" class="close" data-dismiss="alert" aria-label="Close">
 
−
  <span aria-hidden="true">&times;</span>
 
−
</button>
 
−
</syntaxhighlight>انتبه إلى أنّ إغلاق تنبيه يحذفه من كائن المستند DOM.
 
−
 
−
=== التوابع ===
 
 
{| class="wikitable"
 
{| class="wikitable"
−
!التابع
+
!الاسم
 +
!النوع
 +
!القيمة المبدئيّة
 
!الوصف
 
!الوصف
 
|-
 
|-
−
|<code>‎$().alert()‎</code>
+
|<code>animation</code> (التحريك)
−
|يجعل التنبيه يُنصِت لأحداث النقر على العناصر الأبناء التي لديها الخاصيّة <code>data-dismiss="alert"</code> . (ليس ضروريًّا عند استخدام التمهيد التلقائي Auto-initialization في واجهة التطبيقات data-api.)
+
|قيمة منطقيّة
 +
|<code>true</code>
 +
|تطبيق تأثير الخفوت في CSS على مكزن النخب.
 
|-
 
|-
−
|<code>‎$().alert('close')</code>
+
|<code>autohide</code> (الإخفاء التلقائي)
−
|يغلق تنبيهًا بحذف من كائن المستنَد DOM. إن كان الصّنفان ‎<code>.fade</code> و <code>‎.show</code> موجوديْن فإن التنبيه سيخبو قبل أن يختفي.
+
| سلسلة محارف |قيمة منطقيّة
 +
|<code>true</code>
 +
|الإخفاء التلقائي للنخب
 
|-
 
|-
−
|<code>‎$().alert('dispose')</code>
+
|<code>delay</code> (تأخير)
−
|يحذف التنبيه من العنصُر.
+
| سلسلة محارف |عدد
 +
|<code>500</code>
 +
|تأخير إخفاء النخب (ملي ثانية)
 
|}
 
|}
−
<syntaxhighlight lang="javascript">
 
−
$(".alert").alert('close')
 
−
</syntaxhighlight>
 
  
−
=== الأحداث Events ===
+
=== توابع ===
−
يعرض مُلحَق التنبيهات في Bootstrap بضعة أحداث للتعامل مع وظيفة التنبيه.
+
'''تنبيه: التوابع غير المتزامنة والانتقالات'''
 +
 
 +
توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال. راجع صفحة [[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"
 
{| class="wikitable"
−
!الحدث
+
!نوع الحدث
 
!الوصف
 
!الوصف
 
|-
 
|-
−
|<code>close.bs.alert</code>
+
|<code>show.bs.toast</code>
−
|ينطلق هذا الحدث مباشرةً بعد استدعاء التابع <code>close</code> .
+
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>show</code>.
 
|-
 
|-
−
|<code>closed.bs.alert</code>
+
|<code>shown.bs.toast</code>
−
|ينطلق هذا الحدث مباشرةً بعد استدعاء التابع <code>close</code> .
+
|يُطلَق هذا الحدث عندما تُصبح مكونة النخب ظاهرةً للزائر.
−
|}
+
|-
−
<syntaxhighlight lang="javascript">
+
|<code>hide.bs.toast</code>
−
$('#myAlert').on('closed.bs.alert', function () {
+
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>hide</code> .
−
   // افعل شيئًا هنا …
+
|-
 +
|<code>hidden.bs.toast</code>
 +
|يُطلَق هذا الحدث عندما يكتمل إخفاء مكون النخب عن الزائر .
 +
|}<syntaxhighlight lang="javascript">
 +
$('#myToast').on('hidden.bs.toast', function () {
 +
   // افعل شيئا ما
 
})
 
})
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== مصادر ==
 
== مصادر ==
−
* [https://getbootstrap.com/docs/4.5/components/alerts/ صفحة Alerts في توثيق Bootstrap].
+
* [https://getbootstrap.com/docs/4.5/components/toasts/ صفحة toasts في توثيق Bootstrap].
 
[[تصنيف:Bootstrap|{{SUBPAGENAME}}]]
 
[[تصنيف:Bootstrap|{{SUBPAGENAME}}]]

مراجعة 11:12، 19 يوليو 2020

أظهر إشعارات لزوارك عبر مكونات النخب (toast‎s)، وهي رسائل تنبيه قابلة للتخصيص بسهولة.

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

نظرة عامة

هذه أشياء ينبغي أن تعرفها عند استخدام مكونات النخب:

  • إن أردت بناء JavaScript من المصدر، فاعلم أنّ ذلك يتطلب util.js.
  • النخب اختيارية لأسباب تتعلق بالأداء، لذا يجب عليك تهيئتها بنفسك.
  • يرجى ملاحظة أنك مسؤول عن تحديد مواضع النخب
  • إن لم تعيّن الخاصية autohide: false، فستُخفى النخب تلقائيًا.

ملحوظة: تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط prefers-reduced-motion، راجع صفحة سهولة الوصول لمزيد من المعلومات

أمثلة

أمثلة قاعدية

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

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

<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>

الشفافية

مكونات النخب شبه شفافة، لذلك تمتزج مع المكونات التي تظهر فوقها. بالنسبة للمتصفحات التي تدعم خاصية filter-backdrop، ستحاول أيضًا طمس العناصر الموجودة تحت مكون النخب.

<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>

تكديس مكونات النخب

إن عُرِضت عدّة مكونات نخب في الوقت نفسه، فإنّ Bootstrap ستكدسها رأسيًا لتجعلها قابلة للقراءة.

<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>

التموضع

حدد مواضع مكونات النخب عبر أنماط CSS مخصصة. غالبًا ما يُستخدم الجزء العلوي الأيمن والجزء العلوي الأوسط للإشعارات. إذا كنت ستكتفي بعرض نخب واحد فقط في كل مرة، فضع أنماط تحديد الموضع مباشرة على النخب ‎.toast‎.

<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>

إن كنت تتوقع أن تستخدم عدة إشعارات، فضعها في غلاف حتى يسهُل تكديسها.

<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>

يمكنك أيضًا التوسع في تصميم النخب باستخدام أدوات Flexbox لمحاذاة النخب أفقيًا و / أو عموديًا.

<!-- حاوية مرنة لمحاذاة مكونات النخب -->
<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>

سهولة الوصول

صُمِّمت مكونات النخب لتقاطع المستخدم مقاطعة سريعة، إن أردت مساعدة الزوار الذين يستخدمون قارئات شاشة والتقنيات المساعدة المماثلة، يجب عليك تغليف مكونات النخب في منطقة حية aria-live. يتم الإعلان تلقائيًا عن التغييرات التي تطرأ على المناطق الحية (مثل عمليات إدخال / تحديث مكونات النخب) من قبل برامج قراءة الشاشة دون الحاجة إلى تشتيت تركيز المستخدم أو مقاطعته. احرص - علاوة على ذلك - على تضمين aria-atomic = "true"‎ لتتأكد من الإعلان عن مكونات النخب دائمًا كوحدة (ذرية) واحدة، بدلاً من الاكتفاء بالإعلان عما تمّ تغييره (والذي قد يؤدّي إلى مشاكل في حال اكتفيت بتحديث جزء فقط من محتوى النخب، أو في حال عرض محتوى النخب نفسه في وقت لاحق). إذا كانت المعلومات المعروضة مهمة للعملية، كأن تعرض قائمة بالأخطاء في استمارة يملؤها الزائر، حينئذ قد يكون الأفضل أن تستخدم مكوّنات التنبيه بدلاً من النخب.

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

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

في أثناء تغير المحتوى المعروض، تأكد من تحديث مهلة التأخير حتى يتسنّى للناس الوقت الكافي لقراءة محتوى النخب.

<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>

في حال استخدام autohide: false، سيكون عليك إضافة زر إغلاق للسماح للمستخدمين بإغلاق النخب.

<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>

سلوك JavaScript

طريقة الاستخدام

يمكنك تهيئة النخب عبر JavaScript:

$('.toast').toast(option)

خيارات

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

الاسم النوع القيمة المبدئيّة الوصف
animation (التحريك) قيمة منطقيّة true تطبيق تأثير الخفوت في CSS على مكزن النخب.
autohide (الإخفاء التلقائي) قيمة منطقيّة true الإخفاء التلقائي للنخب
delay (تأخير) عدد 500 تأخير إخفاء النخب (ملي ثانية)

توابع

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

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

‎$().toast(options)‎

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

‎.toast('show')‎

كشف مكوّن النخب والعودة إلى المُستدعي قبل إظهار النخب فعليا (أي قبل وقوع الحدث shown.bs.toast). عليك استدعاء هذا التابع يدويًا وإلا فلن يظهر النخب.

$('#element').toast('show')

‎.toast('hide')‎ إخفاء مكون النخب والعودة إلى المُستدعي قبل إخفاء النخب فعليا (أي قبل وقوع الحدث hidden.bs.toast). عليك استدعاء هذا التابع يدويًا في حال عيّنت قيمة الخاصية autohide إلى false.

$('#element').toast('hide')

‎.toast('dispose')‎ إخفاء مكون النخب. سيبقى مكون النخب في شجرة DOM، بيد أنّه لن يظهر بعدها.

$('#element').toast('dispose')

الأحداث

نوع الحدث الوصف
show.bs.toast يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع show.
shown.bs.toast يُطلَق هذا الحدث عندما تُصبح مكونة النخب ظاهرةً للزائر.
hide.bs.toast يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع hide .
hidden.bs.toast يُطلَق هذا الحدث عندما يكتمل إخفاء مكون النخب عن الزائر . 
$('#myToast').on('hidden.bs.toast', function () {
  // افعل شيئا ما
})

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Bootstrap/toasts&oldid=29759"