Source

Desplegables

Commuteu les superposicions contextuals per mostrar llistes d'enllaços i més amb el connector desplegable Bootstrap.

Visió general

Els menús desplegables són superposicions contextuals alternables per mostrar llistes d'enllaços i molt més. Es fan interactius amb el connector de JavaScript desplegable Bootstrap inclòs. S'activen fent clic, no passant el cursor; aquesta és una decisió de disseny intencionada .

Els desplegables es basen en una biblioteca de tercers, Popper.js , que proporciona un posicionament dinàmic i detecció de finestres. Assegureu-vos d'incloure popper.min.js abans del JavaScript de Bootstrap o utilitzeu bootstrap.bundle.min.js/ bootstrap.bundle.jsque conté Popper.js. Popper.js no s'utilitza per col·locar menús desplegables a les barres de navegació, tot i que no es requereix un posicionament dinàmic.

Si esteu creant el nostre JavaScript des de la font, requereixutil.js .

Accessibilitat

L' estàndard WAI ARIA defineix un role="menu"estris real , però això és específic dels menús semblants a aplicacions que desencadenen accions o funcions. Els menús ARIA només poden contenir elements de menú, elements de menú de caselles de selecció, elements de menú de botons d'opció, grups de botons d'opció i submenús.

Els menús desplegables de Bootstrap, d'altra banda, estan dissenyats per ser genèrics i aplicables a una varietat de situacions i estructures de marcatge. Per exemple, és possible crear menús desplegables que continguin entrades addicionals i controls de formulari, com ara camps de cerca o formularis d'inici de sessió. Per aquest motiu, Bootstrap no espera (ni afegeix automàticament) cap dels atributs rolei necessaris per als menús ARIA reals. Els autors hauran d'incloure ells mateixos aquests atributs més específics.aria-

Tanmateix, Bootstrap afegeix suport integrat per a la majoria de les interaccions estàndard del menú del teclat, com ara la possibilitat de moure's per .dropdown-itemelements individuals mitjançant les tecles del cursor i tancar el menú amb la ESCtecla.

Exemples

Emboliqui el commutador del menú desplegable (el teu botó o enllaç) i el menú desplegable dins .dropdown, o un altre element que declari position: relative;. Els desplegables es poden activar a partir d' <a>elements <button>que s'ajustin millor a les vostres necessitats potencials.

Botó únic

Qualsevol sol .btnes pot convertir en un menú desplegable amb alguns canvis de marcatge. A continuació s'explica com podeu posar-los en funcionament amb qualsevol dels <button>elements:

<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>

I amb <a>elements:

<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>

La millor part és que també podeu fer-ho amb qualsevol variant de botó:

<!-- 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ó dividit

De la mateixa manera, creeu menús desplegables de botons dividits amb pràcticament el mateix marcatge que els menús desplegables d'un sol botó, però amb l'addició d' .dropdown-toggle-splitun espai adequat al voltant del cursor desplegable.

Utilitzem aquesta classe addicional per reduir paddingun 25% l'horitzontal a banda i banda del cursor i eliminar el margin-leftque s'afegeix als menús desplegables de botons habituals. Aquests canvis addicionals mantenen el cursor centrat al botó dividit i proporcionen una àrea de mida més adequada al costat del botó 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

Els menús desplegables de botons funcionen amb botons de totes les mides, inclosos els botons desplegables predeterminats i dividits.

<!-- 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>

Indicacions

Dropup

Activa els menús desplegables a sobre dels elements afegint -los .dropupa l'element 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 els menús desplegables a la dreta dels elements afegint -los .droprighta l'element 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 els menús desplegables a l'esquerra dels elements afegint -los .droplefta l'element 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òricament, els continguts del menú desplegable havien de ser enllaços, però això ja no és el cas de la v4. Ara podeu utilitzar, opcionalment, <button>elements als vostres menús desplegables en lloc de nomé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>

També podeu crear elements desplegables no interactius amb .dropdown-item-text. No dubteu a crear més estil amb CSS o utilitats de text personalitzades.

<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>

Actiu

Afegeix .activeals elements del menú desplegable per dissenyar-los com a actius .

<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>

Inhabilitat

Afegeix .disabledals elements del menú desplegable per dissenyar-los com a desactivats .

<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>

Per defecte, un menú desplegable es col·loca automàticament al 100% des de la part superior i al costat esquerre del seu pare. Afegeix .dropdown-menu-righta una .dropdown-menualineació a la dreta del menú desplegable.

Caps amunt! Els desplegables es col·loquen gràcies a Popper.js (excepte quan estan continguts en una barra de navegació).

<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>

Alineació sensible

Si voleu utilitzar l'alineació sensible, desactiveu el posicionament dinàmic afegint l' data-display="static"atribut i utilitzeu les classes de variació sensible.

Per alinear a la dreta el menú desplegable amb el punt d'interrupció donat o més gran, afegiu .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>

Per alinear el menú desplegable a l' esquerra.dropdown-menu-right amb el punt d'interrupció donat o més gran, afegiu i .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>

Tingueu en compte que no cal que afegiu un data-display="static"atribut als botons desplegables de les barres de navegació, ja que Popper.js no s'utilitza a les barres de navegació.

Capçaleres

Afegiu una capçalera per etiquetar seccions d'accions a qualsevol menú desplegable.

<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>

Divisors

Separeu els grups d'elements de menú relacionats amb un 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>

Text

Col·loqueu qualsevol text de forma lliure dins d'un menú desplegable amb text i utilitzeu les utilitats d'espaiat . Tingueu en compte que probablement necessitareu estils de mida addicionals per limitar l'amplada del 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>

Formes

Col·loqueu un formulari dins d'un menú desplegable o feu-lo en un menú desplegable i utilitzeu les utilitats de marge o farciment per donar-li l'espai negatiu que necessiteu.

<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>

Utilitzeu data-offseto data-referenceper canviar la ubicació del menú desplegable.

<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>

Ús

Mitjançant atributs de dades o JavaScript, el connector desplegable alterna el contingut ocult (menús desplegables) canviant la .showclasse a l'element de la llista principal. Es data-toggle="dropdown"confia en l'atribut per tancar menús desplegables a nivell d'aplicació, així que és una bona idea utilitzar-lo sempre.

En dispositius tàctils, l'obertura d'un menú desplegable afegeix controladors buits ( $.noop) mouseoverals fills immediats de l' <body>element. Aquest hack, certament lleig, és necessari per evitar una peculiaritat en la delegació d'esdeveniments d'iOS , que d'altra manera evitaria que un toc en qualsevol lloc fora del menú desplegable desencadenés el codi que tanca el menú desplegable. Un cop tancat el menú desplegable, mouseovers'eliminen aquests controladors buits addicionals.

Mitjançant atributs de dades

Afegeix data-toggle="dropdown"a un enllaç o un botó per canviar un menú desplegable.

<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>

Mitjançant JavaScript

Truqueu als menús desplegables mitjançant JavaScript:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown"encara requerit

Independentment de si truqueu al vostre menú desplegable mitjançant JavaScript o utilitzeu l'api de dades, data-toggle="dropdown"sempre cal que estigui present a l'element activador del menú desplegable.

Opcions

Les opcions es poden passar mitjançant atributs de dades o JavaScript. Per als atributs de dades, afegiu el nom de l'opció a data-, com a data-offset="".

Nom Tipus Per defecte Descripció
compensació nombre | cadena | funció 0 Desplaçament del menú desplegable en relació al seu objectiu. Per obtenir més informació, consulteu els documents d' offset de Popper.js .
voltejar booleà veritat Permet que el desplegable giri en cas de superposició a l'element de referència. Per obtenir més informació, consulteu els documents flip de Popper.js .
límit cadena | element 'scrollParent' Límit de restricció de desbordament del menú desplegable. Accepta els valors de 'viewport', 'window', 'scrollParent', o una referència HTMLElement (només JavaScript). Per obtenir més informació, consulteu els documents preventOverflow de Popper.js .
referència cadena | element 'canviar' Element de referència del menú desplegable. Accepta els valors de 'toggle', 'parent', o una referència HTMLElement. Per obtenir més informació, consulteu els documents referenceObject de Popper.js .
visualització corda 'dinàmic' Per defecte, utilitzem Popper.js per al posicionament dinàmic. Desactiveu-ho amb static.

Tingueu en compte que quan boundarys'estableix un valor diferent de 'scrollParent', l'estil position: statics'aplica al .dropdowncontenidor.

Mètodes

Mètode Descripció
$().dropdown('toggle') Activa o desactiva el menú desplegable d'una barra de navegació determinada o de la navegació per pestanyes.
$().dropdown('show') Mostra el menú desplegable d'una barra de navegació determinada o una navegació per pestanyes.
$().dropdown('hide') Oculta el menú desplegable d'una barra de navegació o navegació per pestanyes determinada.
$().dropdown('update') Actualitza la posició del menú desplegable d'un element.
$().dropdown('dispose') Destrueix el menú desplegable d'un element.

Esdeveniments

Tots els esdeveniments desplegables es desencadenen a l' .dropdown-menuelement pare de ' i tenen una relatedTargetpropietat, el valor de la qual és l'element d'ancoratge alternatiu. hide.bs.dropdowni hidden.bs.dropdownels esdeveniments tenen una clickEventpropietat (només quan el tipus d'esdeveniment original és click) que conté un objecte d'esdeveniment per a l'esdeveniment de clic.

Esdeveniment Descripció
show.bs.dropdown Aquest esdeveniment s'activa immediatament quan es crida al mètode d'instància de mostra.
shown.bs.dropdown Aquest esdeveniment s'activa quan el desplegable s'ha fet visible per a l'usuari (esperarà que finalitzin les transicions CSS).
hide.bs.dropdown Aquest esdeveniment s'activa immediatament quan s'ha cridat el mètode d'instància oculta.
hidden.bs.dropdown Aquest esdeveniment s'activa quan el menú desplegable s'ha acabat d'ocultar a l'usuari (esperarà que finalitzin les transicions CSS).
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})