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

المراجعة الحالية بتاريخ 06:51، 14 يوليو 2020

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

آليّة العمل

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

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

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

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

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

مثال

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

يجب إضافة الصنف ‎.active إلى إحدى الشرائح وإلا لن يظهر الدوّار. تأكد أيضًا من تعيين معرّف فريد للدوّار لأجل عناصر التحكم الاختيارية، خاصة إذا كنت تستخدم عدة دوّارات في صفحة واحدة. يجب أن تحتوي عناصر التحكم والمؤشرات على سمة data-target (أو href للروابط) تتطابق مع معرف الدوّار.

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

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

<div id="carouselExampleSlidesOnly" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
        <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" 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 src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" 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>

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

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

<div id="carouselExampleCaptions" class="carousel slide" data-ride="carousel">
  <ol class="carousel-indicators">
    <li data-target="#carouselExampleCaptions" data-slide-to="0" class="active"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="1"></li>
    <li data-target="#carouselExampleCaptions" data-slide-to="2"></li>
  </ol>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>لافتة الشريحة الأولى</h5>
        <p>Nulla vitae elit libero, a pharetra augue mollis interdum.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>لافتة الشريحة الثانية</h5>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>لافتة الشريحة الثالثة</h5>
        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p>
      </div>
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleCaptions" 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="#carouselExampleCaptions" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">لاحق</span>
  </a>
</div>

تأثير الخفوت

أضف الصنف ‎.carousel-fade إلى العنصر الدوار لتحريك الشرائح وإنشاء انتقال الخفوت.

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleFade" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleFade" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </a>
</div>

مجالات ‎`.carousel-item` الفردية

أضف data-interval=""‎ إلى‎ .carousel-item لتغيير الوقت اللازم للانتقال إلى العنصر التالية.

<div id="carouselExampleInterval" class="carousel slide" data-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <a class="carousel-control-prev" href="#carouselExampleInterval" role="button" data-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="sr-only">Previous</span>
  </a>
  <a class="carousel-control-next" href="#carouselExampleInterval" role="button" data-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="sr-only">Next</span>
  </a>
</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`	إن كان يتوجّب تشغيل الدوّار باستمرار أم لا.
touch	قيمة منطقيّة	`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.