Skip to main content Skip to docs navigation

اللوحة الجانبية (Offcanvas)

قم ببناء لوحات جانبية مخفية في مشروعك للتنقل، وعربات التسوق، وأكثر من ذلك باستخدام بعض الفئات (classes) وإضافة الـ JavaScript الخاصة بنا.

كيف يعمل ؟

الـ Offcanvas هي مكون لوحة جانبية يمكن تبديله عبر الـ JavaScript ليظهر من الحافة اليسرى أو اليمنى أو العلوية أو السفلية لمنطقة العرض. تُستخدم الأزرار أو الروابط كمشغلات (triggers) يتم ربطها بعناصر محددة تقوم بتبديلها، وتُستخدم سمات data لاستدعاء الـ JavaScript الخاصة بنا.

  • تشترك الـ Offcanvas في بعض من نفس كود الـ JavaScript الخاص بالـ modals. من الناحية المفاهيمية، هما متشابهان تماماً، لكنهما إضافات (plugins) منفصلة.
  • وبالمثل، فإن بعض متغيرات source Sass الخاصة بأنماط وأبعاد الـ offcanvas موروثة من متغيرات الـ modal.
  • عند إظهارها، تتضمن الـ offcanvas خلفية افتراضية يمكن النقر عليها لإخفاء الـ offcanvas.
  • على غرار الـ modals، يمكن إظهار لوحة جانبية (offcanvas) واحدة فقط في كل مرة.

تنبيه! نظراً لكيفية تعامل CSS مع الرسوم المتحركة، لا يمكنك استخدام margin أو translate على عنصر .offcanvas. بدلاً من ذلك، استخدم الفئة (class) كعنصر تغليف مستقل.

تعتمد تأثيرات الرسوم المتحركة لهذا المكوّن على استعلام الوسائط (media query) الخاص بـ prefers-reduced-motion. راجع قسم تقليل الحركة في مستندات إمكانية الوصول لدينا.

أمثلة

مكونات اللوحة الجانبية (Offcanvas)

فيما يلي مثال على لوحة جانبية (offcanvas) تظهر بشكل افتراضي (عبر الفئة .show على الفئة .offcanvas). تتضمن الـ offcanvas دعماً لرأس (header) مع زر إغلاق وفئة جسم (body class) اختيارية لبعض الـ padding الأولي. نقترح أن تقوم بتضمين رؤوس offcanvas مع إجراءات إغلاق كلما كان ذلك ممكناً، أو توفير إجراء إغلاق صريح.

Offcanvas
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
html
<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
  </div>
</div>

عرض توضيحي مباشر

استخدم الأزرار أدناه لإظهار وإخفاء عنصر لوحة جانبية (offcanvas) عبر الـ JavaScript التي تقوم بتبديل الفئة .show على عنصر يحتوي على الفئة .offcanvas.

  • .offcanvas تخفي المحتوى (افتراضي)
  • .offcanvas.show تظهر المحتوى

يمكنك استخدام رابط مع سمة href، أو زر مع سمة data-bs-target. في كلتا الحالتين، فإن data-bs-toggle="offcanvas" مطلوبة.

Link with href
Offcanvas
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
html
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Button with data-bs-target
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
    </div>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Another action</a></li>
        <li><a class="dropdown-item" href="#">Something else here</a></li>
      </ul>
    </div>
  </div>
</div>

تمرير محتوى الصفحة (Body scrolling)

يتم تعطيل التمرير لعنصر <body> عندما تكون اللوحة الجانبية (offcanvas) وخلفيتها مرئيتين. استخدم سمة data-bs-scroll لتمكين تمرير <body>.

Offcanvas with body scrolling

Try scrolling the rest of the page to see this option in action.

html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

تمرير محتوى الصفحة والخلفية

يمكنك أيضاً تمكين تمرير <body> مع وجود خلفية مرئية.

Backdrop with scrolling

Try scrolling the rest of the page to see this option in action.

html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

خلفية ثابتة (Static backdrop)

عندما يتم تعيين backdrop على static، لن يتم إغلاق الـ offcanvas عند النقر خارج نطاقه.

Offcanvas
I will not close if you click outside of me.
html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
  Toggle static offcanvas
</button>

<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      I will not close if you click outside of me.
    </div>
  </div>
</div>

لوحة جانبية داكنة

v5.3.0 مستبعد في الإصدار تمت الإضافة في الإصدار v5.2.0

قم بتغيير مظهر الـ offcanvases باستخدام الأدوات المساعدة (utilities) لتتناسب بشكل أفضل مع السياقات المختلفة مثل أشرطة التنقل (navbars) الداكنة. هنا نقوم بإضافة .text-bg-dark إلى .offcanvas و .btn-close-white إلى .btn-close للتنسيق الصحيح مع لوحة جانبية داكنة. إذا كان لديك قوائم منسدلة (dropdowns) بداخلها، فكر أيضاً في إضافة .dropdown-menu-dark إلى .dropdown-menu.

تنبيه! تم استبعاد البدائل الداكنة للمكونات في الإصدار 5.3.0 مع تقديم أنماط الألوان. بدلاً من إضافة الفئات (classes) المذكورة أعلاه يدوياً، قم بتعيين data-bs-theme="dark" على العنصر الجذر، أو غلاف أب، أو المكون نفسه.

Offcanvas

Place offcanvas content here.

html
<div class="offcanvas offcanvas-start show text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5>
    <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Place offcanvas content here.</p>
  </div>
</div>

المتوافق مع الشاشات (Responsive)

تمت الإضافة في الإصدار v5.2.0

تخفي الفئات (classes) الخاصة بالـ offcanvas المتوافقة مع الشاشات المحتوى خارج منطقة العرض من نقطة توقف (breakpoint) محددة وما دونها. وفوق نقطة التوقف هذه، ستتصرف المحتويات الموجودة بداخلها كالمعتاد. على سبيل المثال، تقوم الفئة .offcanvas-lg بإخفاء المحتوى في الـ offcanvas تحت نقطة التوقف lg ، ولكنها تظهر المحتوى فوق نقطة التوقف lg. تتوفر الفئات (classes) الخاصة بالـ offcanvas المتوافقة مع الشاشات لكل نقطة توقف.

  • .offcanvas
  • .offcanvas-sm
  • .offcanvas-md
  • .offcanvas-lg
  • .offcanvas-xl
  • .offcanvas-xxl

لجعل الـ offcanvas متوافقاً مع الشاشات، استبدل الفئة (class) الأساسية .offcanvas ببديل متوافق مع الشاشات وتأكد من أن زر الإغلاق لديه سمة data-bs-target صريحة.

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas

This is content within an .offcanvas-lg.

html
<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button>

<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div>

<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p>
  </div>
</div>

الموضع (Placement)

لا يوجد موضع افتراضي لمكونات الـ offcanvas، لذا يجب عليك إضافة واحدة من الفئات (classes) المعدلة أدناه.

  • .offcanvas-start تضع الـ offcanvas على يسار منطقة العرض (كما هو موضح أعلاه)
  • .offcanvas-end تضع الـ offcanvas على يمين منطقة العرض
  • .offcanvas-top تضع الـ offcanvas في أعلى منطقة العرض
  • .offcanvas-bottom تضع الـ offcanvas في أسفل منطقة العرض

جرب الأمثلة العلوية، واليمنى، والسفلية أدناه.

Offcanvas top
...
html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button>

<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Offcanvas right
...
html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Offcanvas bottom
...
html
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>

<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

إمكانية الوصول

بما أن لوحة الـ offcanvas هي من الناحية المفاهيمية عبارة عن حوار مشروط (modal dialog)، تأكد من إضافة aria-labelledby="..." —الذي يشير إلى عنوان الـ offcanvas— إلى .offcanvas. لاحظ أنك لست بحاجة إلى إضافة role="dialog" لأننا نقوم بإضافتها بالفعل عبر الـ JavaScript.

الـ (CSS)

المتغيرات (Variables)

تمت الإضافة في الإصدار v5.2.0

كجزء من نهج متغيرات CSS المتطور في Bootstrap، تستخدم الـ offcanvas الآن متغيرات CSS محلية على .offcanvas لتعزيز التخصيص في الوقت الفعلي. يتم تعيين قيم متغيرات CSS عبر الـ Sass، لذا فإن التخصيص عبر الـ Sass لا يزال مدعوماً أيضاً.

--#{$prefix}offcanvas-zindex: #{$zindex-offcanvas};
--#{$prefix}offcanvas-width: #{$offcanvas-horizontal-width};
--#{$prefix}offcanvas-height: #{$offcanvas-vertical-height};
--#{$prefix}offcanvas-padding-x: #{$offcanvas-padding-x};
--#{$prefix}offcanvas-padding-y: #{$offcanvas-padding-y};
--#{$prefix}offcanvas-color: #{$offcanvas-color};
--#{$prefix}offcanvas-bg: #{$offcanvas-bg-color};
--#{$prefix}offcanvas-border-width: #{$offcanvas-border-width};
--#{$prefix}offcanvas-border-color: #{$offcanvas-border-color};
--#{$prefix}offcanvas-box-shadow: #{$offcanvas-box-shadow};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};

متغيرات الـ (Sass)

$offcanvas-padding-y:               $modal-inner-padding;
$offcanvas-padding-x:               $modal-inner-padding;
$offcanvas-horizontal-width:        400px;
$offcanvas-vertical-height:         30vh;
$offcanvas-transition-duration:     .3s;
$offcanvas-border-color:            $modal-content-border-color;
$offcanvas-border-width:            $modal-content-border-width;
$offcanvas-title-line-height:       $modal-title-line-height;
$offcanvas-bg-color:                var(--#{$prefix}body-bg);
$offcanvas-color:                   var(--#{$prefix}body-color);
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

الإستخدام

تستخدم إضافة الـ offcanvas بعض الفئات (classes) والسمات للقيام بالمهام الأساسية:

  • .offcanvas تخفي المحتوى
  • .offcanvas.show تظهر المحتوى
  • .offcanvas-start تخفي الـ offcanvas على اليسار
  • .offcanvas-end تخفي الـ offcanvas على اليمين
  • .offcanvas-top تخفي الـ offcanvas في الأعلى
  • .offcanvas-bottom تخفي الـ offcanvas في الأسفل

أضف زر إغلاق باستخدام سمة data-bs-dismiss="offcanvas"، والتي تقوم بتفعيل وظائف الـ JavaScript. تأكد من استخدام عنصر <button> معه لضمان السلوك الصحيح عبر جميع الأجهزة.

عبر سمات البيانات (Via data attributes)

التبديل (Toggle)

أضف data-bs-toggle="offcanvas" و data-bs-target أو href إلى العنصر لتعيين التحكم تلقائياً في عنصر offcanvas واحد. تقبل سمة data-bs-target محدد CSS لتطبيق الـ offcanvas عليه. تأكد من إضافة الفئة (class) offcanvas إلى عنصر الـ offcanvas. إذا كنت تريده أن يكون مفتوحاً بشكل افتراضي، فأضف الفئة الإضافية show.

الإغلاق (Dismiss)

يمكن تحقيق الإغلاق باستخدام سمة data-bs-dismiss على زر داخل الـ offcanvas كما هو موضح أدناه:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

أو على زر خارج الـ offcanvas باستخدام data-bs-target الإضافية كما هو موضح أدناه:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>

بينما يتم دعم كلتا الطريقتين لإغلاق الـ offcanvas، ضع في اعتبارك أن الإغلاق من خارج الـ offcanvas لا يتطابق مع نمط حوار (modal) الخاص بدليل ممارسات تأليف ARIA. افعل ذلك على مسؤوليتك الخاصة.

عبر الـ (JavaScript)

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

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))

خيارات

بما أنه يمكن تمرير الخيارات عبر سمات البيانات (data attributes) أو الـ JavaScript، يمكنك إضافة اسم الخيار إلى -data-bs ، كما في "data-bs-animation="{value}. تأكد من تغيير نوع حالة اسم الخيار من “camelCase” إلى “kebab-case” عند تمرير الخيارات عبر سمات البيانات. على سبيل المثال، استخدم "data-bs-custom-class="beautifier بدلاً من "data-bs-customClass="beautifier.

بدءاً من Bootstrap 5.2.0، تدعم جميع المكونات سمة بيانات محجوزة تجريبية وهي data-bs-config والتي يمكن أن تحتوي على تكوين بسيط للمكون كسلسلة JSON. عندما يحتوي العنصر على سمات 'data-bs-config='{"delay":0, "title":123} و "data-bs-title="456، ستكون قيمة title النهائية هي 456 وستقوم سمات البيانات المنفصلة بتجاوز القيم المعطاة في data-bs-config. بالإضافة إلى ذلك، يمكن لسمات البيانات الموجودة أن تحتوي على قيم JSON مثل 'data-bs-delay='{"show":0,"hide":150}.

كائن التكوين النهائي هو النتيجة المدمجة لـ data-bs-config و -data-bs و js object حيث يقوم آخر مفتاح-قيمة مُعطى بتجاوز القيم الأخرى.

الاسمالنوعالإفتراضيالوصف
backdropboolean or the string statictrueتطبيق خلفية على الجسم أثناء فتح الـ offcanvas. بدلاً من ذلك، حدد static لخلفية لا تغلق الـ offcanvas عند النقر عليها.
keyboardbooleantrueإغلاق الـ offcanvas عند الضغط على مفتاح escape.
scrollbooleanfalseالسماح بتمرير الجسم أثناء فتح الـ offcanvas.

الطرق، الأساليب (Methods)

جميع دوال الـ API هي دوال غير متزامنة (asynchronous) وتبدأ عملية انتقال (transition). وهي تعود إلى المستدعي بمجرد بدء عملية الانتقال، ولكن قبل انتهائها. بالإضافة إلى ذلك، سيتم تجاهل أي استدعاء للدالة على مكوّن يمر حالياً بعملية انتقال. تعرف على المزيد في مستندات JavaScript الخاصة بنا.

تُفعل محتواك كعنصر لوحة جانبية (offcanvas). تقبل كائن object اختياري للخيارات.

يمكنك إنشاء مثيل (instance) للوحة الجانبية باستخدام المنشئ (constructor)، على سبيل المثال:

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
الأسلوبالوصف
disposeيقوم بإزالة الـ offcanvas الخاصة بالعنصر.
getInstanceطريقة ستاتيكية (Static) تسمح لك بالحصول على مثيل (instance) الـ offcanvas المرتبط بعنصر DOM.
getOrCreateInstanceطريقة ستاتيكية (Static) تسمح لك بالحصول على مثيل (instance) الـ offcanvas المرتبط بعنصر DOM، أو إنشاء مثيل جديد في حال لم يتم تهيئته.
hideيقوم بإخفاء عنصر الـ offcanvas. يعود إلى المستدعي قبل أن يتم إخفاء عنصر الـ offcanvas فعلياً (أي قبل وقوع حدث hidden.bs.offcanvas).
showيقوم بإظهار عنصر الـ offcanvas. يعود إلى المستدعي قبل أن يتم إظهار عنصر الـ offcanvas فعلياً (أي قبل وقوع حدث shown.bs.offcanvas).
toggleيقوم بتبديل حالة عنصر الـ offcanvas بين الظهور والإخفاء. يعود إلى المستدعي قبل أن يتم إظهار أو إخفاء عنصر الـ offcanvas فعلياً (أي قبل وقوع حدث shown.bs.offcanvas أو hidden.bs.offcanvas).

الأحداث (Events)

توفر الفئة (class) الخاصة بالـ offcanvas في Bootstrap بعض الأحداث للربط مع وظائف الـ offcanvas.

نوع الحدثالوصف
hide.bs.offcanvasيتم إطلاق هذا الحدث فوراً عند استدعاء طريقة hide.
hidden.bs.offcanvasيتم إطلاق هذا الحدث عندما يتم إخفاء عنصر الـ offcanvas عن المستخدم (سينتظر اكتمال انتقالات CSS).
hidePrevented.bs.offcanvasيتم إطلاق هذا الحدث عندما تكون الـ offcanvas ظاهرة، وتكون خلفيتها static ويتم النقر خارج الـ offcanvas. يتم إطلاق الحدث أيضاً عند الضغط على مفتاح escape وتعيين خيار keyboard على false.
show.bs.offcanvasيتم إطلاق هذا الحدث فوراً عند استدعاء طريقة المثيل show.
shown.bs.offcanvasيتم إطلاق هذا الحدث عندما يصبح عنصر الـ offcanvas مرئياً للمستخدم (سينتظر اكتمال انتقالات CSS).
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})