الفرق بين المراجعتين لصفحة: «Bootstrap/carousel»

مراجعة 04:59، 11 أبريل 2018

الدوّار (carousel) هو مكوِّن عرض شرائح في إطار العمل Bootstrap لتدوير العناصر - صوّر أو شرائح نصيّة - كما يفعل حزام نقل الأمتعة في المطارات.

آليّة العمل

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

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

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

انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة إلى أنّ الدوّار مبنيّ على مكتبة util.js.

مثال

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

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

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

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

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

إضافة أزرار تحكّم

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

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

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

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

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

تنبيه بخصوص العنصُر النشط في البدء

يجب أن يكون الصنف ‎.active مُطبَّقًا على واحدة من الشرائح؛ وإلّا فلن يكون الدوّار مرئيًّا.

إضافة لافتات للشرائح

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

<div class="carousel-item">
  <img src="..." alt="...">
  <div class="carousel-caption d-none d-md-block">
    <h5>...</h5>
    <p>...</p>
  </div>
</div>

استخدام مُلحَق JavaScript

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

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

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

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

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

$('.carousel').carousel()

الخيّارات

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

الاسم	النوع	القيمة المبدئيّة	الوصف
`interval` (مجال)	عدد	`5000`	المقدار الزمنيّ للمدّة الفاصلة بين تدوير عنصُر تلقائيًا. لا يتبدّل الدوّار تلقائيَّا إنْ كانت هذه القيمة مساويّةً للقيمة `false`.
`keyboard` (لوحة مفاتيح)	منطقيّة	`true`	إن كان الدوّار يتفاعل مع أحداث لوحة المفاتيح
`pause` (توقّف)	قيمة منطقية	`"hover"`	يوقف التدوير إن كانت القيمة تساوي `"hover"`, عند الحدث `mouseenter` (مرور المؤشّر على الدوّار) ويعود إلى التدوير عند وقوع الحدث `mouseleave` (تراجع المؤشّر عن الدوّار). إنْ كانت القيمة `false` فإن حومان المؤشّر على الدوّار لن يجعله يتوقّف. بالنسبة للأجهزة التي تعمل باللمس فإن القيمة `"hover"` ينتُج عنها توقّف الدوّار عند الحدث `touchend` (انتهاء المستخدم التفاعل مع الدوّار) لمجاليْن، ثم يواصل. يُرجى ملاحظة أنّ هذا السلوك يعمل إضافةً إلى سلوك المؤشّر المذكور أعلاه.
`ride` (تدوير)	سلسلة محارف	`false`	يشغّل الدوّار تلقائيًّل بعد أن يمرّر المستخدم يدويًّا العنصُر الأوّل. إنْ كانت القيمة تساوي `"carousel"` فهذا يدلّ على تشغيل الدوّار تلقائيًّا مع تحميل الصفحة.
`wrap` (التفاف)	قيمة منطقيّة	`true`	إن كان يتوجّب تشغيل الدوّار باستمرار أم لا.

التوابع

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

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

راجع توثيق JavaScript في Bootstrap للمزيد من المعلومات.

`‎.carousel(options)‎‎`

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

$('.carousel').carousel({
  interval: 2000
})

`‎.carousel('cycle')‎‎`

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

`‎.carousel('pause')‎‎`

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

`‎.carousel(number)‎‎`

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

`‎.carousel('prev')‎‎`

يننقل إلى الشريحة السابقة. يعود إلى المستدعِي قبل أن يُعرَض العنصُر المستهدَف (أي قبل وقوع الحدث slid.bs.carousel).

`‎.carousel('next')‎‎`

يننقل إلى الشريحة المواليّة. يعود إلى المستدعِي قبل أن يُعرَض العنصُر المستهدَف (أي قبل وقوع الحدث slid.bs.carousel).

`‎.carousel('dispose')‎‎`

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

الأحداث

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

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

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

نوع الحدَث	الوصف
`slide.bs.carousel`	يُطلَق هذا الحدَث مباشرة استدعاء التابع `slide` .
`slid.bs.carousel`	يُطلَق هذا الحدث عندما يكمل الدوّار الانتقال إلى الشريحة

$('#myCarousel').on('slide.bs.carousel', function () {
  // افعل شيئا هنا
})

مصادر

صفحة Carousel في توثيق Bootstrap.

@@ سطر 159: / سطر 159: @@
 |-
 |<code>wrap</code> (التفاف)
-<td>قيمة منطقيّة</td>
+|قيمة منطقيّة
 |<code>true</code>
 |إن كان يتوجّب تشغيل الدوّار باستمرار أم لا.
 |}
 === التوابع ===