Passer au contenu principal Passer à la navigation dans les documents
Check
in English

Hors toile

Créez des barres latérales cachées dans votre projet pour la navigation, les paniers d'achat et plus encore avec quelques classes et notre plugin JavaScript.

Sur cette page

Comment ça fonctionne

Offcanvas est un composant de barre latérale qui peut être basculé via JavaScript pour apparaître à partir du bord gauche, droit, supérieur ou inférieur de la fenêtre d'affichage. Les boutons ou les ancres sont utilisés comme déclencheurs qui sont attachés à des éléments spécifiques que vous basculez, et datales attributs sont utilisés pour invoquer notre JavaScript.

  • Offcanvas partage une partie du même code JavaScript que les modaux. Conceptuellement, ils sont assez similaires, mais ce sont des plugins distincts.
  • De même, certaines variables source Sass pour les styles et les dimensions d'offcanvas sont héritées des variables du modal.
  • Lorsqu'il est affiché, offcanvas inclut une toile de fond par défaut sur laquelle vous pouvez cliquer pour masquer l'offcanvas.
  • Semblable aux modaux, un seul hors canevas peut être affiché à la fois.

La tête haute! Étant donné la façon dont CSS gère les animations, vous ne pouvez pas utiliser marginou translatesur un .offcanvasélément. Utilisez plutôt la classe comme élément d'habillage indépendant.

L'effet d'animation de ce composant dépend de la prefers-reduced-motionrequête multimédia. Voir la section mouvement réduit de notre documentation sur l'accessibilité .

Exemples

Composants hors canevas

Vous trouverez ci-dessous un exemple hors canevas affiché par défaut (via .showon .offcanvas). Offcanvas inclut la prise en charge d'un en-tête avec un bouton de fermeture et une classe de corps facultative pour certains fichiers padding. Nous vous suggérons d'inclure des en-têtes hors canevas avec des actions de rejet chaque fois que possible, ou de fournir une action de rejet explicite.

Hors toile
Le contenu de l'offcanvas va ici. Vous pouvez placer à peu près n'importe quel composant Bootstrap ou éléments personnalisés ici.
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>

Démo en direct

Utilisez les boutons ci-dessous pour afficher et masquer un élément hors canevas via JavaScript qui bascule la .showclasse sur un élément avec la .offcanvasclasse.

  • .offcanvasmasque le contenu (par défaut)
  • .offcanvas.showaffiche le contenu

Vous pouvez utiliser un lien avec l' hrefattribut, ou un bouton avec l' data-bs-targetattribut. Dans les deux cas, le data-bs-toggle="offcanvas"est obligatoire.

Lien avec href
Hors toile
Du texte comme espace réservé. Dans la vraie vie, vous pouvez avoir les éléments que vous avez choisis. Comme, texte, images, listes, 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>

Défilement du corps

Le défilement de l' <body>élément est désactivé lorsqu'un hors-canevas et son arrière-plan sont visibles. Utilisez l' data-bs-scrollattribut pour activer le <body>défilement.

Offcanvas avec défilement du corps

Essayez de faire défiler le reste de la page pour voir cette option en 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>

Défilement du corps et toile de fond

Vous pouvez également activer le <body>défilement avec un arrière-plan visible.

Toile de fond avec défilement

Essayez de faire défiler le reste de la page pour voir cette option en 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>

Toile de fond statique

Lorsque la toile de fond est définie sur statique, l'offcanvas ne se fermera pas lorsque vous cliquerez en dehors de celle-ci.

Hors toile
Je ne fermerai pas si vous cliquez en dehors de moi.
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>

Hors toile sombre

Ajouté dans v5.2.0

Modifiez l'apparence des offcanvas avec des utilitaires pour mieux les faire correspondre à différents contextes comme les barres de navigation sombres. Ici, nous ajoutons .text-bg-darkà .offcanvaset .btn-close-whiteà .btn-closepour un style approprié avec une toile sombre. Si vous avez des listes déroulantes à l'intérieur, envisagez également d'ajouter .dropdown-menu-darkà .dropdown-menu.

Hors toile

Placez le contenu hors canevas ici.

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>

Sensible

Ajouté dans v5.2.0

Les classes offcanvas réactives masquent le contenu en dehors de la fenêtre d'affichage à partir d'un point d'arrêt spécifié et vers le bas. Au-dessus de ce point d'arrêt, le contenu se comportera comme d'habitude. Par exemple, .offcanvas-lgmasque le contenu dans un hors canevas sous le point d' lgarrêt, mais affiche le contenu au-dessus du point d' lgarrêt.

Redimensionnez votre navigateur pour afficher la bascule réactive offcanvas.
Responsive offcanvas

Il s'agit du contenu d'un fichier .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>

Des classes responsive offcanvas sont disponibles pour chaque point d'arrêt.

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

Placement

Il n'y a pas de placement par défaut pour les composants hors canevas, vous devez donc ajouter l'une des classes de modificateurs ci-dessous.

  • .offcanvas-startplace offcanvas sur la gauche de la fenêtre (illustrée ci-dessus)
  • .offcanvas-endplace offcanvas sur la droite de la fenêtre
  • .offcanvas-topplace offcanvas en haut de la fenêtre
  • .offcanvas-bottomplace offcanvas au bas de la fenêtre

Essayez les exemples en haut, à droite et en bas ci-dessous.

Dessus en toile
...
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>
Hors toile à droite
...
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>
Bas hors toile
...
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>

Accessibilité

Étant donné que le panneau offcanvas est conceptuellement une boîte de dialogue modale, assurez-vous d'ajouter - en aria-labelledby="..."faisant référence au titre offcanvas - à .offcanvas. Notez que vous n'avez pas besoin d'ajouter role="dialog"puisque nous l'avons déjà ajouté via JavaScript.

CSS

variables

Ajouté dans v5.2.0

Dans le cadre de l'approche évolutive des variables CSS de Bootstrap, offcanvas utilise désormais des variables CSS locales .offcanvaspour une personnalisation améliorée en temps réel. Les valeurs des variables CSS sont définies via Sass, de sorte que la personnalisation de Sass est toujours prise en charge également.

  --#{$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};

Variables SSS

$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:                $modal-content-bg;
$offcanvas-color:                   $modal-content-color;
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

Usage

Le plugin offcanvas utilise quelques classes et attributs pour gérer le gros du travail :

  • .offcanvascache le contenu
  • .offcanvas.showaffiche le contenu
  • .offcanvas-startcache le hors canevas sur la gauche
  • .offcanvas-endcache le hors canevas à droite
  • .offcanvas-topcache l'offcanvas sur le dessus
  • .offcanvas-bottomcache l'offcanvas en bas

Ajoutez un bouton de rejet avec l' data-bs-dismiss="offcanvas"attribut, qui déclenche la fonctionnalité JavaScript. Assurez-vous d'utiliser l' <button>élément avec lui pour un comportement correct sur tous les appareils.

Via les attributs de données

Basculer

Ajoutez data-bs-toggle="offcanvas"et un data-bs-targetou hrefà l'élément pour attribuer automatiquement le contrôle d'un élément hors canevas. L' data-bs-targetattribut accepte un sélecteur CSS auquel appliquer l'offcanvas. Assurez-vous d'ajouter la classe offcanvasà l'élément offcanvas. Si vous souhaitez qu'il soit ouvert par défaut, ajoutez la classe supplémentaire show.

Rejeter

Le rejet peut être réalisé avec l' dataattribut sur un bouton dans l'offcanvas comme démontré ci-dessous :

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

ou sur un bouton en dehors de l'offcanvas en utilisant le data-bs-targetcomme illustré ci-dessous :

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
Bien que les deux méthodes de fermeture d'un hors-canvas soient prises en charge, gardez à l'esprit que le rejet depuis l'extérieur d'un hors-canvas ne correspond pas au modèle de dialogue (modal) ARIA Authoring Practices Guide . A vos risques et périls.

Via Javascript

Activer manuellement avec :

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

Choix

Comme les options peuvent être transmises via des attributs de données ou JavaScript, vous pouvez ajouter un nom d'option à data-bs-, comme dans data-bs-animation="{value}". Assurez-vous de changer le type de casse du nom de l'option de " camelCase " à " kebab-case " lors du passage des options via les attributs de données. Par exemple, utilisez à la data-bs-custom-class="beautifier"place de data-bs-customClass="beautifier".

Depuis Bootstrap 5.2.0, tous les composants prennent en charge un attribut de données expérimentaldata-bs-config réservé pouvant héberger une configuration de composant simple sous forme de chaîne JSON. Lorsqu'un élément a des attributs data-bs-config='{"delay":0, "title":123}'et , la valeur finale sera et les attributs de données séparés remplaceront les valeurs données sur . De plus, les attributs de données existants peuvent héberger des valeurs JSON telles que .data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Nom Taper Défaut La description
backdrop booléen ou la chaînestatic true Appliquez une toile de fond sur le corps pendant que l'offcanvas est ouvert. Vous pouvez également spécifier staticun arrière-plan qui ne ferme pas la toile lorsque vous cliquez dessus.
keyboard booléen true Ferme l'offcanvas lorsque la touche d'échappement est enfoncée.
scroll booléen false Autoriser le défilement du corps pendant que l'offcanvas est ouvert.

Méthodes

Méthodes et transitions asynchrones

Toutes les méthodes API sont asynchrones et démarrent une transition . Ils reviennent à l'appelant dès que la transition est commencée mais avant qu'elle ne se termine . De plus, un appel de méthode sur un composant en transition sera ignoré .

Consultez notre documentation JavaScript pour plus d'informations .

Active votre contenu en tant qu'élément hors toile. Accepte une option facultative object.

Vous pouvez créer une instance offcanvas avec le constructeur, par exemple :

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
Méthode La description
getInstance Méthode statique qui permet d'obtenir l'instance offcanvas associée à un élément DOM.
getOrCreateInstance Méthode statique qui permet d'obtenir l'instance offcanvas associée à un élément DOM, ou d'en créer une nouvelle au cas où elle n'aurait pas été initialisée.
hide Masque un élément hors canevas. Renvoie à l'appelant avant que l'élément offcanvas ait été masqué (c'est-à-dire avant que l' hidden.bs.offcanvasévénement ne se produise).
show Affiche un élément hors canevas. Renvoie à l'appelant avant que l'élément offcanvas n'ait été réellement affiché (c'est-à-dire avant que l' shown.bs.offcanvasévénement ne se produise).
toggle Bascule un élément hors canevas sur affiché ou masqué. Renvoie à l'appelant avant que l'élément offcanvas ait été réellement affiché ou masqué (c'est-à-dire avant que l' événement shown.bs.offcanvasou ne hidden.bs.offcanvasse produise).

Événements

La classe offcanvas de Bootstrap expose quelques événements pour se connecter à la fonctionnalité offcanvas.

Type d'événement La description
hide.bs.offcanvas Cet événement est déclenché immédiatement lorsque la hideméthode a été appelée.
hidden.bs.offcanvas Cet événement est déclenché lorsqu'un élément offcanvas a été caché à l'utilisateur (il attendra que les transitions CSS soient terminées).
hidePrevented.bs.offcanvas Cet événement est déclenché lorsque l'offcanvas est affiché, sa toile de fond l'est staticet un clic à l'extérieur de l'offcanvas est effectué. L'événement est également déclenché lorsque la touche d'échappement est enfoncée et que l' keyboardoption est définie sur false.
show.bs.offcanvas Cet événement se déclenche immédiatement lorsque la showméthode d'instance est appelée.
shown.bs.offcanvas Cet événement est déclenché lorsqu'un élément offcanvas a été rendu visible à l'utilisateur (il attendra que les transitions CSS soient terminées). 
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})