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

Use o complemento modal de JavaScript de Bootstrap para engadir diálogos ao seu sitio para caixas de luz, notificacións de usuarios ou contido completamente personalizado.

Cómo funciona

Antes de comezar co compoñente modal de Bootstrap, asegúrate de ler o seguinte xa que as nosas opcións de menú cambiaron recentemente.

  • Os modais constrúense con HTML, CSS e JavaScript. Colócanse sobre todo o resto do documento e eliminan o desprazamento <body>para que o contido modal se desprace no seu lugar.
  • Facendo clic no "fondo" modal pecharase automaticamente o modal.
  • Bootstrap só admite unha ventá modal á vez. Os modais anidados non son compatibles, xa que cremos que son experiencias de usuario deficientes.
  • Os modais usan position: fixed, que ás veces pode ser un pouco particular sobre a súa representación. Sempre que sexa posible, coloque o seu HTML modal nunha posición de nivel superior para evitar posibles interferencias doutros elementos. É probable que teñas problemas ao aniñar un .modaldentro doutro elemento fixo.
  • Unha vez máis, debido a position: fixed, hai algunhas advertencias co uso de modais en dispositivos móbiles. Consulte os nosos documentos de soporte do navegador para obter máis información.
  • Debido a como HTML5 define a súa semántica, o autofocusatributo HTML non ten ningún efecto nos modais de Bootstrap. Para conseguir o mesmo efecto, use algún JavaScript personalizado:
const myModal = document.getElementById('myModal')
const myInput = document.getElementById('myInput')

myModal.addEventListener('shown.bs.modal', () => {
  myInput.focus()
})
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 .

Continúa lendo para ver demostracións e pautas de uso.

Exemplos

A continuación móstrase un exemplo modal estáticoposition (que significa que os seus e displayforon anulados). Inclúense a cabeceira modal, o corpo modal (obrigatorio para padding) e o pé de páxina modal (opcional). Pedimos que inclúas cabeceiras modais con accións de exclusión sempre que sexa posible ou proporciones outra acción de exclusión explícita.

<div class="modal" tabindex="-1">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">Modal title</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <p>Modal body text goes here.</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Demo en directo

Alterna unha demostración modal de traballo facendo clic no botón de abaixo. Deslizarase cara abaixo e desaparecerá dende a parte superior da páxina.

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Fondo estático

Cando o fondo está configurado como estático, o modal non se pechará ao facer clic fóra del. Fai clic no botón de abaixo para probalo.

<!-- Button trigger modal -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#staticBackdrop">
  Launch static backdrop modal
</button>

<!-- Modal -->
<div class="modal fade" id="staticBackdrop" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="staticBackdropLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="staticBackdropLabel">Modal title</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Understood</button>
      </div>
    </div>
  </div>
</div>

Desprazando contido longo

Cando os modais se fan demasiado longos para a vista ou o dispositivo do usuario, desprázanse independentemente da propia páxina. Proba a demo a continuación para ver o que queremos dicir.

Tamén podes crear un modal desprazable que permita desprazar o corpo modal engadindo .modal-dialog-scrollablea .modal-dialog.

<!-- Scrollable modal -->
<div class="modal-dialog modal-dialog-scrollable">
  ...
</div>

Centrado verticalmente

Engadir .modal-dialog-centereda .modal-dialogpara centrar verticalmente o modal.

<!-- Vertically centered modal -->
<div class="modal-dialog modal-dialog-centered">
  ...
</div>

<!-- Vertically centered scrollable modal -->
<div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
  ...
</div>

Suxestións e popovers

As informacións sobre ferramentas e popovers pódense colocar dentro dos modais segundo sexa necesario. Cando se pechan os modais, todas as suxestións sobre ferramentas e os menús emerxentes tamén se descartan automaticamente.

<div class="modal-body">
  <h5>Popover in a modal</h5>
  <p>This <a href="#" role="button" class="btn btn-secondary" data-bs-toggle="popover" title="Popover title" data-bs-content="Popover body content is set in this attribute.">button</a> triggers a popover on click.</p>
  <hr>
  <h5>Tooltips in a modal</h5>
  <p><a href="#" data-bs-toggle="tooltip" title="Tooltip">This link</a> and <a href="#" data-bs-toggle="tooltip" title="Tooltip">that link</a> have tooltips on hover.</p>
</div>

Usando a reixa

Utiliza o sistema de cuadrícula Bootstrap nun modal anidando .container-fluiddentro do .modal-body. Despois, use as clases normais do sistema de reixa como faría en calquera outro lugar.

<div class="modal-body">
  <div class="container-fluid">
    <div class="row">
      <div class="col-md-4">.col-md-4</div>
      <div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div>
      <div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-sm-9">
        Level 1: .col-sm-9
        <div class="row">
          <div class="col-8 col-sm-6">
            Level 2: .col-8 .col-sm-6
          </div>
          <div class="col-4 col-sm-6">
            Level 2: .col-4 .col-sm-6
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

Contido modal variable

Tes un montón de botóns que activan o mesmo modal con contidos lixeiramente diferentes? Use event.relatedTargete atributos HTMLdata-bs-* para variar o contido do modal dependendo do botón no que se premeu.

A continuación móstrase unha demostración en directo seguida de exemplos de HTML e JavaScript. Para obter máis información, lea os documentos sobre eventos modais para obter máis información sobre relatedTarget.

html
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@mdo">Open modal for @mdo</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@fat">Open modal for @fat</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal" data-bs-whatever="@getbootstrap">Open modal for @getbootstrap</button>

<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">New message</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <form>
          <div class="mb-3">
            <label for="recipient-name" class="col-form-label">Recipient:</label>
            <input type="text" class="form-control" id="recipient-name">
          </div>
          <div class="mb-3">
            <label for="message-text" class="col-form-label">Message:</label>
            <textarea class="form-control" id="message-text"></textarea>
          </div>
        </form>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Send message</button>
      </div>
    </div>
  </div>
</div>
const exampleModal = document.getElementById('exampleModal')
exampleModal.addEventListener('show.bs.modal', event => {
  // Button that triggered the modal
  const button = event.relatedTarget
  // Extract info from data-bs-* attributes
  const recipient = button.getAttribute('data-bs-whatever')
  // If necessary, you could initiate an AJAX request here
  // and then do the updating in a callback.
  //
  // Update the modal's content.
  const modalTitle = exampleModal.querySelector('.modal-title')
  const modalBodyInput = exampleModal.querySelector('.modal-body input')

  modalTitle.textContent = `New message to ${recipient}`
  modalBodyInput.value = recipient
})

Alterna entre modais

Alterna entre varios modais cunha colocación intelixente dos atributos data-bs-targete . data-bs-togglePor exemplo, podes cambiar un modal de restablecemento de contrasinal desde un modal de inicio de sesión xa aberto. Teña en conta que non se poden abrir varios modais ao mesmo tempo ; este método simplemente alterna entre dous modais separados.

Abrir primeiro modal
html
<div class="modal fade" id="exampleModalToggle" aria-hidden="true" aria-labelledby="exampleModalToggleLabel" tabindex="-1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalToggleLabel">Modal 1</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        Show a second modal and hide this one with the button below.
      </div>
      <div class="modal-footer">
        <button class="btn btn-primary" data-bs-target="#exampleModalToggle2" data-bs-toggle="modal">Open second modal</button>
      </div>
    </div>
  </div>
</div>
<div class="modal fade" id="exampleModalToggle2" aria-hidden="true" aria-labelledby="exampleModalToggleLabel2" tabindex="-1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalToggleLabel2">Modal 2</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        Hide this modal and show the first with the button below.
      </div>
      <div class="modal-footer">
        <button class="btn btn-primary" data-bs-target="#exampleModalToggle" data-bs-toggle="modal">Back to first</button>
      </div>
    </div>
  </div>
</div>
<a class="btn btn-primary" data-bs-toggle="modal" href="#exampleModalToggle" role="button">Open first modal</a>

Cambiar animación

A $modal-fade-transformvariable determina o estado de transformación de .modal-dialogantes da animación de fundido modal, a $modal-show-transformvariable determina a transformación de .modal-dialogao final da animación de fundido modal.

Se queres, por exemplo, unha animación de zoom, podes configurar $modal-fade-transform: scale(.8).

Eliminar animación

Para os modais que simplemente aparecen en lugar de desaparecer para ver, elimina a .fadeclase do teu marcado modal.

<div class="modal" tabindex="-1" aria-labelledby="..." aria-hidden="true">
  ...
</div>

Alturas dinámicas

Se a altura dun modal cambia mentres está aberto, debes chamar myModal.handleUpdate()para reaxustar a posición do modal no caso de que apareza unha barra de desprazamento.

Accesibilidade

Asegúrese de engadir aria-labelledby="...", facendo referencia ao título modal, a .modal. Ademais, pode dar unha descrición do seu diálogo modal con aria-describedbyon .modal. Teña en conta que non precisa engadir role="dialog"xa que xa o engadimos mediante JavaScript.

Incorporando vídeos de YouTube

Incorporar vídeos de YouTube en modais require JavaScript adicional que non está en Bootstrap para deter automaticamente a reprodución e moito máis. Consulta esta útil publicación de Stack Overflow para obter máis información.

Tamaños opcionais

Os modais teñen tres tamaños opcionais, dispoñibles mediante clases de modificadores para colocalos nun .modal-dialog. Estes tamaños aparecen en certos puntos de interrupción para evitar barras de desprazamento horizontais nas vistas máis estreitas.

Tamaño Clase Ancho máximo modal
Pequena .modal-sm 300px
Por defecto Ningún 500px
Grande .modal-lg 800px
Extra grande .modal-xl 1140px

A nosa clase modal predeterminada sen modificador constitúe o modal de tamaño "medio".

<div class="modal-dialog modal-xl">...</div>
<div class="modal-dialog modal-lg">...</div>
<div class="modal-dialog modal-sm">...</div>

Modal de pantalla completa

Outra substitución é a opción de mostrar un modal que cobre a vista do usuario, dispoñible a través de clases modificadoras que se colocan nun .modal-dialog.

Clase Dispoñibilidade
.modal-fullscreen Sempre
.modal-fullscreen-sm-down 576px
.modal-fullscreen-md-down 768px
.modal-fullscreen-lg-down 992px
.modal-fullscreen-xl-down 1200px
.modal-fullscreen-xxl-down 1400px
<!-- Full screen modal -->
<div class="modal-dialog modal-fullscreen-sm-down">
  ...
</div>

CSS

Variables

Engadido na v5.2.0

Como parte do enfoque de variables CSS en evolución de Bootstrap, agora os modais usan variables CSS locais en .modale .modal-backdroppara unha personalización mellorada 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}modal-zindex: #{$zindex-modal};
  --#{$prefix}modal-width: #{$modal-md};
  --#{$prefix}modal-padding: #{$modal-inner-padding};
  --#{$prefix}modal-margin: #{$modal-dialog-margin};
  --#{$prefix}modal-color: #{$modal-content-color};
  --#{$prefix}modal-bg: #{$modal-content-bg};
  --#{$prefix}modal-border-color: #{$modal-content-border-color};
  --#{$prefix}modal-border-width: #{$modal-content-border-width};
  --#{$prefix}modal-border-radius: #{$modal-content-border-radius};
  --#{$prefix}modal-box-shadow: #{$modal-content-box-shadow-xs};
  --#{$prefix}modal-inner-border-radius: #{$modal-content-inner-border-radius};
  --#{$prefix}modal-header-padding-x: #{$modal-header-padding-x};
  --#{$prefix}modal-header-padding-y: #{$modal-header-padding-y};
  --#{$prefix}modal-header-padding: #{$modal-header-padding}; // Todo in v6: Split this padding into x and y
  --#{$prefix}modal-header-border-color: #{$modal-header-border-color};
  --#{$prefix}modal-header-border-width: #{$modal-header-border-width};
  --#{$prefix}modal-title-line-height: #{$modal-title-line-height};
  --#{$prefix}modal-footer-gap: #{$modal-footer-margin-between};
  --#{$prefix}modal-footer-bg: #{$modal-footer-bg};
  --#{$prefix}modal-footer-border-color: #{$modal-footer-border-color};
  --#{$prefix}modal-footer-border-width: #{$modal-footer-border-width};
  
  --#{$prefix}backdrop-zindex: #{$zindex-modal-backdrop};
  --#{$prefix}backdrop-bg: #{$modal-backdrop-bg};
  --#{$prefix}backdrop-opacity: #{$modal-backdrop-opacity};
  

Variables Sass

$modal-inner-padding:               $spacer;

$modal-footer-margin-between:       .5rem;

$modal-dialog-margin:               .5rem;
$modal-dialog-margin-y-sm-up:       1.75rem;

$modal-title-line-height:           $line-height-base;

$modal-content-color:               null;
$modal-content-bg:                  $white;
$modal-content-border-color:        var(--#{$prefix}border-color-translucent);
$modal-content-border-width:        $border-width;
$modal-content-border-radius:       $border-radius-lg;
$modal-content-inner-border-radius: subtract($modal-content-border-radius, $modal-content-border-width);
$modal-content-box-shadow-xs:       $box-shadow-sm;
$modal-content-box-shadow-sm-up:    $box-shadow;

$modal-backdrop-bg:                 $black;
$modal-backdrop-opacity:            .5;

$modal-header-border-color:         var(--#{$prefix}border-color);
$modal-header-border-width:         $modal-content-border-width;
$modal-header-padding-y:            $modal-inner-padding;
$modal-header-padding-x:            $modal-inner-padding;
$modal-header-padding:              $modal-header-padding-y $modal-header-padding-x; // Keep this for backwards compatibility

$modal-footer-bg:                   null;
$modal-footer-border-color:         $modal-header-border-color;
$modal-footer-border-width:         $modal-header-border-width;

$modal-sm:                          300px;
$modal-md:                          500px;
$modal-lg:                          800px;
$modal-xl:                          1140px;

$modal-fade-transform:              translate(0, -50px);
$modal-show-transform:              none;
$modal-transition:                  transform .3s ease-out;
$modal-scale-transform:             scale(1.02);

Bucle

Os modais de pantalla completa sensibles xéranse a través do $breakpointsmapa e dun bucle en scss/_modal.scss.

@each $breakpoint in map-keys($grid-breakpoints) {
  $infix: breakpoint-infix($breakpoint, $grid-breakpoints);
  $postfix: if($infix != "", $infix + "-down", "");

  @include media-breakpoint-down($breakpoint) {
    .modal-fullscreen#{$postfix} {
      width: 100vw;
      max-width: none;
      height: 100%;
      margin: 0;

      .modal-content {
        height: 100%;
        border: 0;
        @include border-radius(0);
      }

      .modal-header,
      .modal-footer {
        @include border-radius(0);
      }

      .modal-body {
        overflow-y: auto;
      }
    }
  }
}

Uso

O complemento modal alterna o teu contido oculto baixo demanda, mediante atributos de datos ou JavaScript. Tamén anula o comportamento de desprazamento predeterminado e xera un .modal-backdroppara proporcionar unha área de clic para descartar os modais mostrados cando se fai clic fóra do modal.

A través de atributos de datos

Alterna

Activa un modal sen escribir JavaScript. Establécese data-bs-toggle="modal"nun elemento do controlador, como un botón, xunto cun data-bs-target="#foo"ou href="#foo"para seleccionar un modal específico para alternar.

<button type="button" data-bs-toggle="modal" data-bs-target="#myModal">Launch modal</button>

Descartar

O despedimento pódese conseguir co dataatributo nun botón dentro do modal como se demostra a continuación:

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

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

<button type="button" class="btn-close" data-bs-dismiss="modal" data-bs-target="#my-modal" aria-label="Close"></button>
Aínda que se admiten ambas as dúas formas de descartar un modal, teña en conta que o descartar desde fóra dun modal 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

Crea un modal cunha única liña de JavaScript:

const myModal = new bootstrap.Modal(document.getElementById('myModal'), options)
// or
const myModalAlternative = new bootstrap.Modal('#myModal', options)

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"no canto 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,'static' true Inclúe un elemento de fondo modal. Alternativamente, especifica staticun fondo que non pecha o modal cando se fai clic.
focus booleano true Pon o foco no modal cando se inicializa.
keyboard booleano true Pecha o modal cando se preme a tecla Esc.

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 .

Opcións de paso

Activa o teu contido como modal. Acepta opcións opcionais object.

const myModal = new bootstrap.Modal('#myModal', {
  keyboard: false
})
Método Descrición
dispose Destrúe o modal dun elemento. (Elimina os datos almacenados no elemento DOM)
getInstance Método estático que permite obter a instancia modal asociada a un elemento DOM.
getOrCreateInstance Método estático que permite obter a instancia modal asociada a un elemento DOM ou crear unha nova no caso de que non se inicializou.
handleUpdate Reaxusta manualmente a posición do modal se a altura dun modal cambia mentres está aberto (é dicir, no caso de que apareza unha barra de desprazamento).
hide Oculta manualmente un modal. Volve ao interlocutor antes de que se ocultase o modal (é dicir, antes de hidden.bs.modalque se produza o evento).
show Abre manualmente un modal. Volve ao interlocutor antes de que se mostrara o modal (é dicir, antes de shown.bs.modalque se produza o evento). Ademais, pode pasar un elemento DOM como argumento que se pode recibir nos eventos modais (como relatedTargetpropiedade). (é dicir const modalToggle = document.getElementById('toggleMyModal'); myModal.show(modalToggle).
toggle Alterna manualmente un modal. Volve ao interlocutor antes de que o modal se mostrase ou ocultase (é dicir, antes de que se produza o evento shown.bs.modalou ).hidden.bs.modal

Eventos

A clase modal de Bootstrap expón algúns eventos para conectarse á funcionalidade modal. Todos os eventos modais desenvólvense no propio modal (é dicir, no <div class="modal">).

Evento Descrición
hide.bs.modal Este evento desenvólvese inmediatamente cando hidese chamou ao método de instancia.
hidden.bs.modal Este evento desenvólvese cando o modal rematou de ocultarse ao usuario (esperará a que se completen as transicións CSS).
hidePrevented.bs.modal Este evento desenvólvese cando se mostra o modal, o seu fondo está statice realízase un clic fóra do modal. O evento tamén se dispara cando se preme a tecla de escape e a keyboardopción está configurada como false.
show.bs.modal Este evento desenvólvese inmediatamente cando showse chama ao método de instancia. Se é causado por un clic, o elemento no que se fai clic está dispoñible como relatedTargetpropiedade do evento.
shown.bs.modal Este evento desenvólvese cando o modal se fixo visible para o usuario (esperará a que se completen as transicións CSS). Se é causado por un clic, o elemento no que se fai clic está dispoñible como relatedTargetpropiedade do evento.
const myModalEl = document.getElementById('myModal')
myModalEl.addEventListener('hidden.bs.modal', event => {
  // do something...
})