Source

Despregables

Alterna as superposicións contextuais para mostrar listas de ligazóns e moito máis co complemento despregable Bootstrap.

Visión xeral

Os menús despregables son superposicións contextuais alternables para mostrar listas de ligazóns e moito máis. Fanse interactivos co complemento de JavaScript Bootstrap incluído. Alternanse facendo clic, non pasando o rato; esta é unha decisión de deseño intencionada .

Os menús despregable están construídos nunha biblioteca de terceiros, Popper.js , que proporciona un posicionamento dinámico e detección de vistas. Asegúrate de incluír popper.min.js antes do JavaScript de Bootstrap ou usa bootstrap.bundle.min.js/ bootstrap.bundle.jsque contén Popper.js. Popper.js non se usa para colocar menús despregables nas barras de navegación, aínda que non é necesario o posicionamento dinámico.

Se estás construíndo o noso JavaScript desde a orixe, requireutil.js .

Accesibilidade

O estándar WAI ARIA role="menu" define un widget real , pero este é específico para menús tipo aplicación que activan accións ou funcións. Os menús de ARIA só poden conter elementos de menú, elementos de menú de caixa de verificación, elementos de menú de botóns de opción, grupos de botóns de opción e submenús.

Os menús despregables de Bootstrap, por outra banda, están deseñados para ser xenéricos e aplicables a unha variedade de situacións e estruturas de marcado. Por exemplo, é posible crear menús despregables que conteñan entradas adicionais e controis de formulario, como campos de busca ou formularios de inicio de sesión. Por este motivo, Bootstrap non espera (nin engade automaticamente) ningún dos atributos rolee aria-necesarios para os verdadeiros menús ARIA . Os autores terán que incluír estes atributos máis específicos.

Non obstante, Bootstrap engade soporte integrado para a maioría das interaccións estándar do menú do teclado, como a posibilidade de moverse por .dropdown-itemelementos individuais usando as teclas do cursor e pechar o menú coa ESCtecla.

Exemplos

Envolve o selector do menú despregable (o teu botón ou ligazón) e o menú despregable dentro .dropdownde , ou noutro elemento que declare position: relative;. Os menús desplegables pódense activar desde <a>ou <button>elementos que se axusten mellor ás túas necesidades potenciais.

Botón único

Calquera .btnelemento pode converterse nun menú despregable con algúns cambios de marcado. Vexa como pode facelos funcionar con calquera dos <button>elementos:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

E con <a>elementos:

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown link
  </a>

  <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

A mellor parte é que tamén podes facelo con calquera variante de botón:

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Action
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

Botón de división

Do mesmo xeito, cree menús despregables de botóns divididos practicamente co mesmo marcado que os menús despregábeis de botóns únicos, pero coa adición de .dropdown-toggle-splitpara un espazo adecuado ao redor do cursor do menú despregable.

Usamos esta clase adicional para reducir a horizontal paddinga cada lado do cursor nun 25 % e eliminar o margin-leftque se engade para os menús despregables de botóns habituais. Eses cambios adicionais manteñen o cursor centrado no botón dividido e proporcionan unha área de golpe de tamaño máis axeitado xunto ao botón principal.

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Action</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

Talla

Os menús despregables de botóns funcionan con botóns de todos os tamaños, incluídos os botóns predeterminados e divididos.

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Large button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Large split button
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- Small button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Small button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Small split button
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

Direccións

Dropup

Activa os menús despregables enriba dos elementos engadindo .dropupao elemento principal.

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropup
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Split dropup
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Dropright

Activa os menús despregables á dereita dos elementos engadindo .droprightao elemento principal.

<!-- Default dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropright
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Split dropright
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropright</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Dropleft

Activa os menús despregables á esquerda dos elementos engadindo .dropleftao elemento principal.

<!-- Default dropleft button -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropleft
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropleft button -->
<div class="btn-group">
  <div class="btn-group dropleft" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
      <span class="sr-only">Toggle Dropleft</span>
    </button>
    <div class="dropdown-menu">
      <!-- Dropdown menu links -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Split dropleft
  </button>
</div>

Históricamente, os contidos do menú despregable tiñan que ser ligazóns, pero ese xa non é o caso da versión 4. Agora podes usar opcionalmente <button>elementos nos teus menús despregables en lugar de só <a>s.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Tamén podes crear elementos do menú despregable non interactivos con .dropdown-item-text. Non dubides en facer máis estilo con CSS personalizados ou utilidades de texto.

<div class="dropdown-menu">
  <span class="dropdown-item-text">Dropdown item text</span>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
</div>

Activo

Engade .activeaos elementos no menú despregable para darlles un estilo como activos .

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item active" href="#">Active link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

Desactivado

Engadir .disabledaos elementos no menú despregable para darlles un estilo desactivado .

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled" href="#" tabindex="-1" aria-disabled="true">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

De xeito predeterminado, un menú despregable sitúase automaticamente ao 100 % desde a parte superior e ao lado esquerdo do seu pai. Engadir .dropdown-menu-rightao .dropdown-menualiñar á dereita o menú despregable.

Aviso! Os menús despregables sitúanse grazas a Popper.js (excepto cando están contidos nunha barra de navegación).

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Right-aligned menu
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Aliñación sensible

Se queres usar o aliñamento receptivo, desactiva o posicionamento dinámico engadindo o data-display="static"atributo e utiliza as clases de variación sensible.

Para aliñar á dereita o menú despregable co punto de interrupción indicado ou máis grande, engade .dropdown-menu{-sm|-md|-lg|-xl}-right.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
    Left-aligned but right aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-lg-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Para aliñar o menú despregable á esquerda co punto de interrupción indicado ou máis grande, engade .dropdown-menu-righte .dropdown-menu{-sm|-md|-lg|-xl}-left.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
    Right-aligned but left aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

Teña en conta que non é necesario engadir un data-display="static"atributo aos botóns despregables nas barras de navegación, xa que Popper.js non se usa nas barras de navegación.

Cabeceiras

Engade unha cabeceira para etiquetar seccións de accións en calquera menú despregable.

<div class="dropdown-menu">
  <h6 class="dropdown-header">Dropdown header</h6>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
</div>

Separadores

Separe os grupos de elementos de menú relacionados cun divisor.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Separated link</a>
</div>

Texto

Coloque calquera texto de forma libre nun menú despregable con texto e use as utilidades de espazado . Teña en conta que probablemente necesitará estilos de tamaño adicionais para limitar o ancho do menú.

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Some example text that's free-flowing within the dropdown menu.
  </p>
  <p class="mb-0">
    And this is more example text.
  </p>
</div>

Formularios

Coloca un formulario nun menú despregable ou convérteo nun menú despregable e usa as utilidades de marxe ou de recheo para darlle o espazo negativo que necesitas.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="[email protected]">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="form-group">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck">
        <label class="form-check-label" for="dropdownCheck">
          Remember me
        </label>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Sign in</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">New around here? Sign up</a>
  <a class="dropdown-item" href="#">Forgot password?</a>
</div>

<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Email address</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="[email protected]">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="form-group">
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck2">
      <label class="form-check-label" for="dropdownCheck2">
        Remember me
      </label>
    </div>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

Use data-offsetou data-referencepara cambiar a localización do menú despregable.

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-offset="10,20">
      Offset
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
    </div>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Reference</button>
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" id="dropdownMenuReference" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
      <div class="dropdown-divider"></div>
      <a class="dropdown-item" href="#">Separated link</a>
    </div>
  </div>
</div>

Uso

A través de atributos de datos ou JavaScript, o complemento despregable alterna o contido oculto (menús despregables) alternando a .showclase no elemento da lista principal. Confíase data-toggle="dropdown"no atributo para pechar os menús despregables a nivel de aplicación, polo que é unha boa idea usalo sempre.

Nos dispositivos táctiles, ao abrir un menú despregable engádense controladores ( $.noop) baleiros mouseoveraos fillos inmediatos do <body>elemento. Este truco feo é necesario para evitar unha peculiaridade na delegación de eventos de iOS , que doutro xeito evitaría que un toque en calquera lugar fóra do menú despregable active o código que pecha o menú despregable. mouseoverUnha vez que se pecha o menú despregable, elimínanse estes controladores baleiros adicionais .

A través de atributos de datos

Engadir data-toggle="dropdown"a unha ligazón ou botón para alternar un menú despregable.

<div class="dropdown">
  <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown trigger
  </button>
  <div class="dropdown-menu" aria-labelledby="dLabel">
    ...
  </div>
</div>

Vía JavaScript

Chame aos menús despregables mediante JavaScript:

$('.dropdown-toggle').dropdown()

`data-toggle="dropdown"`aínda necesario

Independentemente de se chamas ao teu menú despregable mediante JavaScript ou usas a API de datos, data-toggle="dropdown"sempre é necesario que estea presente no elemento de activación do menú despregable.

Opcións

As opcións pódense pasar a través de atributos de datos ou JavaScript. Para os atributos de datos, engada o nome da opción a data-, como en data-offset="".

Nome	Tipo	Por defecto	Descrición
compensar	número \| cadea \| función	0	Compensación do menú despregable en relación ao seu obxectivo. Cando se usa unha función para determinar a compensación, chámase cun obxecto que contén os datos de compensación como primeiro argumento. A función debe devolver un obxecto coa mesma estrutura. O nodo DOM do elemento desencadeante pásase como segundo argumento. Para obter máis información, consulte os documentos de offset de Popper.js .
voltear	booleano	verdade	Permitir que o menú despregable se voltee no caso de que se solape o elemento de referencia. Para obter máis información, consulte os flip docs de Popper.js .
límite	cadea \| elemento	'scrollParent'	Límite de restricción de desbordamento do menú despregable. Acepta os valores de `'viewport'`, `'window'`, `'scrollParent'`, ou unha referencia HTMLElement (só JavaScript). Para obter máis información, consulte os documentos preventOverflow de Popper.js .
referencia	cadea \| elemento	'alternar'	Elemento de referencia do menú despregable. Acepta os valores de `'toggle'`, `'parent'`, ou unha referencia HTMLElement. Para obter máis información, consulte os documentos referenceObject de Popper.js .
visualización	corda	'dinámico'	Por defecto, usamos Popper.js para o posicionamento dinámico. Desactiva isto con `static`.
popperConfig	nulo \| obxecto	nulo	Para cambiar a configuración predeterminada de Popper.js de Bootstrap, consulte a configuración de Popper.js

Teña en conta que cando boundaryse define en calquera valor que non sexa 'scrollParent', o estilo position: staticaplícase ao .dropdowncontedor.

Métodos

Método	Descrición
`$().dropdown('toggle')`	Alterna o menú despregable dunha determinada barra de navegación ou navegación por pestanas.
`$().dropdown('show')`	Mostra o menú despregable dunha determinada barra de navegación ou navegación por pestanas.
`$().dropdown('hide')`	Oculta o menú despregable dunha determinada barra de navegación ou navegación por pestanas.
`$().dropdown('update')`	Actualiza a posición do menú despregable dun elemento.
`$().dropdown('dispose')`	Destrúe o menú despregable dun elemento.

Eventos

Todos os eventos do menú despregable desenvólvense no .dropdown-menuelemento pai de ' e teñen unha relatedTargetpropiedade, cuxo valor é o elemento de áncora alternante. hide.bs.dropdowne hidden.bs.dropdownos eventos teñen unha clickEventpropiedade (só cando o tipo de evento orixinal é click) que contén un obxecto de evento para o evento de clic.

Evento	Descrición
`show.bs.dropdown`	Este evento desenvólvese inmediatamente cando se chama ao método show instance.
`shown.bs.dropdown`	Este evento desenvólvese cando o menú despregable se fixo visible para o usuario (esperará a que se completen as transicións CSS).
`hide.bs.dropdown`	Este evento desenvólvese inmediatamente cando se chamou ao método de ocultar instancia.
`hidden.bs.dropdown`	Este evento desenvólvese cando o menú despregable rematou de ocultarse ao usuario (esperará a que se completen as transicións CSS).

$('#myDropdown').on('show.bs.dropdown', function () {
  // do something...
})

Despregables

Visión xeral

Accesibilidade

Exemplos

Botón único

Botón de división

Talla

Direccións

Dropup

Dropright

Dropleft

Elementos do menú

Activo

Desactivado

Aliñación do menú

Aliñación sensible

Contido do menú

Cabeceiras

Separadores

Texto

Formularios

Uso

A través de atributos de datos

Vía JavaScript

`data-toggle="dropdown"`aínda necesario

Opcións

Métodos

Eventos

Despregables

Visión xeral

Accesibilidade

Exemplos

Botón único

Botón de división

Talla

Direccións

Dropup

Dropright

Dropleft

Elementos do menú

Activo

Desactivado

Aliñación do menú

Aliñación sensible

Contido do menú

Cabeceiras

Cabeceira despregable

Separadores

Texto

Formularios

Opcións desplegables

Uso

A través de atributos de datos

Vía JavaScript

data-toggle="dropdown"aínda necesario

Opcións

Métodos

Eventos

`data-toggle="dropdown"`aínda necesario