عرض مصدر Bootstrap/carousel

<noinclude>{{DISPLAYTITLE:عرض الشرائح في إطار العمل Bootstrap}}</noinclude>
الدوّار Carousel هو مكوِّن عرض شرائح في إطار العمل Bootstrap لتدوير العناصر - صوّر أو شرائح نصيّة - كما يفعل حزام نقل الأمتعة في المطارات.

== آليّة العمل ==
ينتقل الدوّار بين سلسلة من المحتوى الموجود ضمن شرائح عرض دوريًّا. يُبنَى الدوّار بالانتقالات ثلاثيّة الأبعاد في CSS، وبضعة شفرات JavaScript. يعمل الدوّار مع سلسلة من الصوّر، أو النصوص أو الوسوم المُخصَّصة؛ كما يحتوي على إمكانيّة التحكّم في الانتقال (تقديم أو تأخير المعروض) ومؤشّرات.

يتفادى مكوِّن الدوّار في Bootstrap، في المتصفّحات التي تدعم واجهة التطبيقات [https://www.w3.org/TR/page-visibility "Page visibility"]، يتفادى تفعيل الانتقال بين الشرائح عندما تكون صفحة الويب مخفيّة عن الزائر (مثلًا إذا كانت تبويب المتصفّح غير نشط أو إذا كانت نافذة المتصفّح مُصغَّرة على شريط الأدوات في نظام التشغيل).

يُرجى الانتباه إلى أنّ تداخل الدوّارات غير مدعوم، كما أنّ الدوّارات عمومًا ليست متوافقة مع معايير سهولة الوصول.

انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة إلى أنّ الدوّار مبنيّ على مكتبة [https://wiki.hsoub.com/Bootstrap/javascript#Util util.js].


== مثال ==

لا تنظّم الدوّارات في إطار العمل Bootstrap أبعاد الشرائح تلقائيًّا، لذا قد تحتاج إلى استخدام أدوات إضافيّة أو تنسيقات مُخصَّصة لتحديد أبعاد المحتوى لتأخذ شكلًا صحيحا. رغم أنّ الدوّارات تدعم التحكّم في الانتقال (تقديم أو تأخير المعروض) والمؤشِّرات إلّا أنّها ليست من المتطلّبات التي لا بدّ منها.

تأكّد من تعيين معرِّف فريد على الدوّار (الصنف <code>‎.carousel</code>) لأزرار التحكّم الاختياريّة، خصوصًا إنْ كانت لديك دوّارات عدّة في صفحة واحدة.

=== دوّار يحتوي على شرائح فقط ===

في ما يلي دوّار يقتصر محتواه على شرائح عرض. لاحظ وجود الصنفيْن <code>‎.d-block</code> و <code>‎.img-fluid</code> على صوّر الدوّار لمنع المتصفّح من استخدام المحاذاة المبدئيّة للصوّر.

<syntaxhighlight lang="html">
<div id="carouselExampleSlidesOnly" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src="..." alt="الشريحة الأولى">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثانيّة">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثالثة">
    </div>
  </div>
</div>
</syntaxhighlight>
=== إضافة أزرار تحكّم ===

يضيف المثال التالي زرّيْن للتحكّم في الانتقال بين الشرائح.

<syntaxhighlight lang="html">
<div id="carouselExampleControls" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src="..." alt="الشريحة الأولى">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثانيّة">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثالثة">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleControls" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">السابق</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleControls" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">التالي</span>
  </a>
</div>
</syntaxhighlight>

=== إضافة مؤشّرات إلى الدوّار ===

يضيف المثال التالي مؤشّرات إلى الدوّار السابق للإشارة إلى ترتيب الشريحة ضمن الشرائح.

<syntaxhighlight lang="html">
<div id="carouselExampleIndicators" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleIndicators" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="1"></li>
    <li data-target="#carouselExampleIndicators" data-slide-to="2"></li>
  </ol>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="d-block w-100" src="..." alt="الشريحة الأولى">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثانيّة">
    </div>
    <div class="carousel-item">
      <img class="d-block w-100" src="..." alt="الشريحة الثالثة">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleIndicators" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">السابق</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleIndicators" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">التالي</span>
  </a>
</div>
</syntaxhighlight>

==== تنبيه بخصوص العنصُر النشط في البدء =====
يجب أن يكون الصنف <code>‎.active</code> مُطبَّقًا على واحدة من الشرائح؛ وإلّا فإنّ الدوّار لن يكون مرئيّا.

=== إضافة لافتات للشرائح ===
استخدم الصنف <code>‎.carousel-caption</code> ضمن أي شريحة عرض (<code>‎.carousel-item</code>) لإضافة لافتات بسهولة إلى شرائح العرض. يمكن إخفاء اللافتات في إطارات العرض Viewports الصغيرة - كما في المثال أدناه - باستخدام أدوات العرض. نخفي اللافتات في المثال التالي أوّلًا باستخدام الصنف <code>‎.d-none</code> ثم نعاود إظهارها بدءًا من الأجهزة ذات شاشات العرض المتوسّطة بالصنف <code>‎.d-md-block</code>.

<syntaxhighlight lang="html">
<div class="carousel-item">
  <img src="..." alt="...">
  <div class="carousel-caption d-none d-md-block">
    <h5>...</h5>
    <p>...</p>
  </div>
</div>
</syntaxhighlight>
== استخدام مُلحَق JavaScript ==

=== استخدام الدوّار بواسطة خاصيّات البيانات Data attributes ===

استخدم خاصيّات البيانات للتحكّم في وضعيّة الدوّار بسهولة. تقبل الخاصيّة <code>data-slide</code> القيمتيْن <code>prev</code> (السابق) أو <code>next</code> (اللّاحق) اللتين تغيّران وضعيّة الشرائح انطلاقًا من وضعيّتها الحاليّة. كما يمكن استخدام الخاصيّة <code>data-slide-to</code> وتمرير قيمة عدديّة إليها تمثّل ترتيب شريحة في معرض الشرائح؛ مثلًا تنقل القيمة <code>data-slide-to="2"‎</code> معرض الشرائح إلى الشريحة ذات الترتيب <code>2</code>، علمًا أنّ الترتيب يبدأ من <code>0</code>.

تُستخدَم الخاصيّة <code>data-ride="carousel"‎</code> للدلالة على أنّ تحريك الدوّار يبدأ مباشرةً عند بدء تحميل الصفحة. **لا يمكن استخدام هذه الخاصيّة عند تمهيد Initialization نفس الدوّار يدويًّا باستخدام JavaScript (تكرار غير ضروريّ)**.

=== كتابة شفرة JavaScript مُخصَّصة ===

يمكن استدعاء الدوّار يدويًّا على النحو التالي:

<syntaxhighlight lang="javascript">
$('.carousel').carousel()
</syntaxhighlight>
=== الخيّارات ===

يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-‎</code> (مثلًا <code>data-interval=""‎</code> للخيّار <code>interval</code>) عند التمرير عبر خاصيّات البيانات.
=== التوابع ===

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

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


[[Bootstrap/javascript|راجع توثيق JavaScript في Bootstrap للمزيد من المعلومات]].

==== <code>‎.carousel(options)</code> ====

يستهلّ الدوّار بكائن خيّارات اختيّاري ويبدأ الانتقال بين العناصر.

<syntaxhighlight lang="javascript">
$('.carousel').carousel({
  interval: 2000
})
</syntaxhighlight>

==== <code>‎.carousel('cycle')</code> ====

الانتقال بين عناصر الدوّار من اليسار إلى اليمين.

==== <code>‎.carousel('pause')</code> ====

يوقِف الدوّار عن الانتقال بين العناصر.

==== <code>‎.carousel(number)</code> ====

ينقُل الدوّار إلى شريحة معيَّنة (حيث <code>number</code> يمثّل ترتيبها، الشريحة الأولى ذات ترتيب <code>0</code>). **يعود إلى المستدعِي قبل أن يُعرَض العنصُر المستهدَف** (أي قبل وقوع الحدث <code>slid.bs.carousel</code>).

==== <code>‎.carousel('prev')</code> ====
يننقل إلى الشريحة السابقة. **يعود إلى المستدعِي قبل أن يُعرَض العنصُر المستهدَف** (أي قبل وقوع الحدث <code>slid.bs.carousel</code>).

==== <code>‎.carousel('next')</code> ====
يننقل إلى الشريحة المواليّة. **يعود إلى المستدعِي قبل أن يُعرَض العنصُر المستهدَف** (أي قبل وقوع الحدث <code>slid.bs.carousel</code>).

==== <code>‎.carousel('dispose')</code> ====

يحذف عنصُر الدوّار.

=== الأحداث ===

يعرض الصنف carousel في إطار العمل Bootstrap حدَثيْن للتعامل مع وظيفة الدوّار. توجد الخاصيّات الإضافيّة التاليّة في كلٍّ من الحدثيْن:

- <code>direction</code>: اتجاه انتقال الدوّار (إما إلى اليسار <code>"left"</code>  أو اليمين <code>"right"</code>).
- <code>relatedTarget</code>: عنصُر كائن المستند DOM الذي ينتقل الدوّار إليه لجعله العنصُر النشط.
- <code>from</code>: ترتيب العنصُر الحالي.
- <code>to</code>: ترتيب العنصُر الموالي.

تُطلَق جميع أحداث الدوّار ضمن الدوّار نفسه (بمعنى أنّها من العنصُر <code><div class="carousel"‎></code>).

<syntaxhighlight lang="javascript">
$('#myCarousel').on('slide.bs.carousel', function () {
  // افعل شيئا هنا
})
</syntaxhighlight>

== مصادر ==
- [https://getbootstrap.com/docs/4.0/components/carousel) "صفحة Carousel في توثيق Bootstrap"].