Ir ao contido principal Ir á navegación de documentos
Check
in English

Off lenzo

Crea barras laterais ocultas no teu proxecto para navegar, carros da compra e moito máis con algunhas clases e o noso complemento de JavaScript.

Nesta páxina

Cómo funciona

Offcanvas é un compoñente da barra lateral que se pode alternar mediante JavaScript para que apareza dende o bordo esquerdo, dereito, superior ou inferior da ventana gráfica. Os botóns ou áncoras utilízanse como disparadores que se anexan a elementos específicos que alternas, e dataos atributos úsanse para invocar o noso JavaScript.

  • Offcanvas comparte parte do mesmo código JavaScript que os modais. Conceptualmente, son bastante similares, pero son complementos separados.
  • Do mesmo xeito, algunhas variables de orixe Sass para os estilos e dimensións de offcanvas herdanse das variables do modal.
  • Cando se mostra, offcanvas inclúe un fondo predeterminado no que se pode facer clic para ocultar o offcanvas.
  • Do mesmo xeito que os modais, só se pode mostrar un offcanvas á vez.

Aviso! Dado como CSS manexa as animacións, non pode usar marginnin translatenun .offcanvaselemento. En vez diso, use a clase como un elemento de envoltura independente.

O efecto de animación deste compoñente depende da prefers-reduced-motionconsulta multimedia. Consulta a sección de movemento reducido da nosa documentación de accesibilidade .

Exemplos

Compoñentes offcanvas

A continuación móstrase un exemplo fóra do lenzo que se mostra por defecto (a través .showde on .offcanvas). Offcanvas inclúe soporte para un encabezado cun botón de peche e unha clase de corpo opcional para algúns padding. Suxerímoslle que inclúas cabeceiras fóra do lenzo con accións de exclusión sempre que sexa posible ou proporciones unha acción de exclusión explícita.

Off lenzo
O contido para o offcanvas vai aquí. Podes colocar case calquera compoñente Bootstrap ou elementos personalizados aquí.
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>

Demo en directo

Use os botóns de abaixo para mostrar e ocultar un elemento fóra do lenzo mediante JavaScript que alterna a .showclase a un elemento coa .offcanvasclase.

  • .offcanvasoculta o contido (predeterminado)
  • .offcanvas.showmostra o contido

Podes usar unha ligazón co hrefatributo ou un botón co data-bs-targetatributo. En ambos os casos, data-bs-toggle="offcanvas"é necesario.

Enlace con href
Off lenzo
Algún texto como marcador de posición. Na vida real podes ter os elementos que escolleches. Gústame, texto, imaxes, listas, 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>

Desprazamento corporal

O desprazamento do <body>elemento está desactivado cando un fóra do lenzo e o seu fondo son visibles. Use o data-bs-scrollatributo para activar o <body>desprazamento.

Off lenzo con desprazamento corporal

Proba a desprazarte polo resto da páxina para ver esta opción en acción.

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>

Desprazamento corporal e pano de fondo

Tamén podes activar <body>o desprazamento cun fondo visible.

Fondo con desprazamento

Proba a desprazarte polo resto da páxina para ver esta opción en acción.

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>

Fondo estático

Cando o fondo está configurado como estático, o offcanvas non se pechará ao facer clic fóra del.

Off lenzo
Non pecharei se fai clic fóra de min.
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>

Off lenzo escuro

Engadido na v5.2.0

Cambia a aparencia dos lenzos con utilidades para adaptalos mellor a diferentes contextos, como as barras de navegación escuras. Aquí engadimos .text-bg-darkao .offcanvase .btn-close-whiteao .btn-closepara un estilo axeitado cun lenzo escuro. Se tes menús despregables dentro, considera engadir tamén .dropdown-menu-darka .dropdown-menu.

Off lenzo

Coloca aquí contido fóra do lenzo.

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

Engadido na v5.2.0

As clases sensibles offcanvas ocultan contido fóra da ventana gráfica desde un punto de interrupción especificado e cara abaixo. Por riba dese punto de interrupción, os contidos dentro comportaranse como de costume. Por exemplo, .offcanvas-lgoculta o contido nun lenzo debaixo do lgpunto de interrupción, pero mostra o contido enriba do punto de lginterrupción.

Cambia o tamaño do teu navegador para mostrar a opción offcanvas de resposta.
Offcanvas sensible

Este é contido dentro dun .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>

Están dispoñibles clases offcanvas responsivas para cada punto de interrupción.

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

Colocación

Non hai unha colocación predeterminada para os compoñentes offcanvas, polo que debes engadir unha das clases de modificadores a continuación.

  • .offcanvas-startcoloca fóra do lenzo á esquerda da ventana gráfica (mostrada arriba)
  • .offcanvas-endcoloca fóra do lenzo á dereita da ventana gráfica
  • .offcanvas-topcoloca fóra do lenzo na parte superior da ventana gráfica
  • .offcanvas-bottomcoloca fóra do lenzo na parte inferior da ventana gráfica

Proba os exemplos superior, dereito e inferior que aparecen a continuación.

Parte superior de lona
...
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>
Off canvas dereita
...
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>
Fondo fóra de lona
...
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>

Accesibilidade

Dado que o panel offcanvas é conceptualmente un diálogo modal, asegúrate de engadir aria-labelledby="...", facendo referencia ao título offcanvas, a .offcanvas. Teña en conta que non precisa engadir role="dialog"xa que xa o engadimos mediante JavaScript.

CSS

Variables

Engadido na v5.2.0

Como parte do enfoque de variables CSS en evolución de Bootstrap, offcanvas agora usa variables CSS locais activadas .offcanvaspara mellorar a personalización en tempo real. Os valores para as variables CSS establécense a través de Sass, polo que a personalización de Sass tamén se admite.

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

Uso

O complemento offcanvas utiliza algunhas clases e atributos para xestionar o traballo pesado:

  • .offcanvasoculta o contido
  • .offcanvas.showmostra o contido
  • .offcanvas-startesconde o off lenzo da esquerda
  • .offcanvas-endesconde o off lenzo á dereita
  • .offcanvas-topesconde o off lenzo na parte superior
  • .offcanvas-bottomesconde o off lenzo na parte inferior

Engade un botón de exclusión co data-bs-dismiss="offcanvas"atributo, que activa a funcionalidade de JavaScript. Asegúrate de usar o <button>elemento con el para un comportamento correcto en todos os dispositivos.

A través de atributos de datos

Alterna

Engade data-bs-toggle="offcanvas"e a data-bs-targetou hrefao elemento para asignar automaticamente o control dun elemento fóra do lenzo. O data-bs-targetatributo acepta un selector CSS para aplicar o offcanvas. Asegúrate de engadir a clase offcanvasao elemento offcanvas. Se queres que se abra por defecto, engade a clase adicional show.

Descartar

A destitución pódese conseguir co dataatributo nun botón dentro do offcanvas como se demostra a continuación:

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

ou nun botón fóra do lenzo usando o data-bs-targetcomo se mostra a continuación:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
Aínda que se admiten ambas as dúas formas de descartar un offcanvas, ten en conta que excluír desde fóra dun offcanvas non coincide co patrón (modal) de diálogo da Guía de prácticas de creación de ARIA . Fai isto baixo o teu propio risco.

Vía JavaScript

Habilitar manualmente con:

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

Opcións

Como as opcións se poden pasar a través de atributos de datos ou JavaScript, pode engadir un nome de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar o tipo de maiúsculas e minúsculas do nome da opción de " camelCase " a " kebab-case " ao pasar as opcións a través dos atributos de datos. Por exemplo, use data-bs-custom-class="beautifier"en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos os compoñentes admiten un atributo de datos reservados experimentaisdata-bs-config que pode albergar unha configuración sinxela de compoñentes como cadea JSON. Cando un elemento ten data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"atributos, o titlevalor final será 456e os atributos de datos separados anularán os valores indicados en data-bs-config. Ademais, os atributos de datos existentes poden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome Tipo Por defecto Descrición
backdrop booleano ou a cadeastatic true Aplique un fondo ao corpo mentres está aberto o offcanvas. Alternativamente, especifica staticun fondo que non pecha o lenzo cando se fai clic.
keyboard booleano true Pecha o offcanvas cando se preme a tecla Esc.
scroll booleano false Permitir o desprazamento do corpo mentres está aberto fóra do lenzo.

Métodos

Métodos asíncronos e transicións

Todos os métodos da API son asíncronos e inician unha transición . Volven ao interlocutor en canto se inicia a transición pero antes de que remate . Ademais, ignorarase unha chamada de método nun compoñente en transición .

Consulte a nosa documentación de JavaScript para obter máis información .

Activa o teu contido como elemento fóra do lenzo. Acepta opcións opcionais object.

Podes crear unha instancia offcanvas co construtor, por exemplo:

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
Método Descrición
getInstance Método estático que che permite obter a instancia offcanvas asociada a un elemento DOM.
getOrCreateInstance Método estático que che permite obter a instancia offcanvas asociada a un elemento DOM ou crear unha nova no caso de que non se inicializou.
hide Oculta un elemento fóra do lenzo. Volve ao interlocutor antes de que o elemento offcanvas fose realmente oculto (é dicir, antes de hidden.bs.offcanvasque ocorra o evento).
show Mostra un elemento fóra do lenzo. Volve á persoa que chama antes de que se amosara realmente o elemento offcanvas (é dicir, antes de shown.bs.offcanvasque ocorra o evento).
toggle Alterna un elemento fóra do lenzo para mostrar ou ocultar. Regresa ao interlocutor antes de que o elemento offcanvas fose realmente mostrado ou escondido (é dicir, antes de que se produza o evento shown.bs.offcanvasou ).hidden.bs.offcanvas

Eventos

A clase offcanvas de Bootstrap expón algúns eventos para conectarse á funcionalidade offcanvas.

Tipo de evento Descrición
hide.bs.offcanvas Este evento desenvólvese inmediatamente cando hidese chamou ao método.
hidden.bs.offcanvas Este evento desenvólvese cando se ocultou ao usuario un elemento offcanvas (esperará a que se completen as transicións CSS).
hidePrevented.bs.offcanvas Este evento desenvólvese cando se mostra o offcanvas, o seu telón de fondo statice faise un clic fóra do offcanvas. O evento tamén se dispara cando se preme a tecla de escape e a keyboardopción está configurada como false.
show.bs.offcanvas Este evento desenvólvese inmediatamente cando showse chama ao método de instancia.
shown.bs.offcanvas Este evento desenvólvese cando un elemento fóra do lenzo se fixo visible para o usuario (esperará a que se completen as transicións CSS). 
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})