下拉菜单

使用Bootstrap下拉插件切换上下文覆盖以显示链接列表等。

在本页面

概览

下拉列表是可切换的上下文覆盖，用于显示链接列表等。它们与附带的Bootstrap拉JavaScript插件进行了交互。它们是通过单击而不是悬停来切换的；这是一个有意的设计决策。

下拉列表建立在第三方库Popper上，它提供动态定位和视口检测。确保包含在Bootstrap的JavaScript之前包含popper.min.js 或使用 bootstrap.bundle.min.js / bootstrap.bundle.js包含Popper。 Popper不用于定位导航栏中的下拉列表，尽管不需要动态定位。

辅助功能

WAI ARIA标准定义了一个实际的role="menu"小部件，但是这是特定于应用的，如菜单，其触发动作或功能。ARIA菜单只能包含菜单项、复选框菜单项、单选按钮菜单项、单选按钮组和子菜单。

另一方面，Bootstrap的下拉列表被设计成通用的，并且适用于各种情况和标记结构。例如，可以创建包含其他输入和表单控件（如搜索字段或登录表单）的下拉列表。因此， Bootstrap并不期望（也不会自动添加）真正的ARIA菜单所需的任何 role 和 aria- 属性。作者将不得不包括这些更具体的属性本身。

但是，Bootstrap确实为大多数标准的键盘菜单交互添加了内置支持，例如使用光标键在各个.dropdown-item元素之间移动，并使用 ESC键关闭菜单的功能。

示例

将下拉菜单的切换（按钮或链接）和下拉菜单包装在.dropdown中，或其他声明 position: relative;的元素中。可以从<a> 或 <button>元素触发下拉列表，以更好地满足您的潜在需求。这里显示的示例在适当的地方使用语义<ul>元素，但是支持自定义标记。

单个按钮

任何一个.btn都可以通过一些标记更改变成下拉切换。下面是如何将它们与<button>元素一起使用：

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <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>

以及<a> 元素：

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

  <ul class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <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>

最好的部分是，您也可以使用任何按钮变体来实现这一点：

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Action
  </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>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

拆分按钮

类似地，创建拆分按钮下拉列表，其标记与单个按钮下拉列表几乎相同，但添加了.dropdown-toggle-split，以便在下拉插入符号并让周围保持适当的间距。

我们使用这个额外的类将插入符号两侧的水平 padding减少25%，并删除为常规按钮下拉添加的margin-left。这些额外的更改将插入符号保持在拆分按钮的中心位置，并在主按钮旁边提供一个大小更合适的命中区域。

<!-- 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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </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>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

尺寸

按钮下拉列表适用于所有大小的按钮，包括默认和拆分下拉按钮。

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Large button
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Small button
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    ...
  </ul>
</div>

深色下拉列表

选择较暗的下拉菜单以匹配深色导航栏或自定义样式，方法是将.dropdown-menu-dark添加到现有的.dropdown-menu。不需要更改下拉项。

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton2" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu dropdown-menu-dark" aria-labelledby="dropdownMenuButton2">
    <li><a class="dropdown-item active" 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>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Separated link</a></li>
  </ul>
</div>

把它放在导航栏里：

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDarkDropdown" aria-controls="navbarNavDarkDropdown" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarNavDarkDropdown">
      <ul class="navbar-nav">
        <li class="nav-item dropdown">
          <a class="nav-link dropdown-toggle" href="#" id="navbarDarkDropdownMenuLink" role="button" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </a>
          <ul class="dropdown-menu dropdown-menu-dark" aria-labelledby="navbarDarkDropdownMenuLink">
            <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>
        </li>
      </ul>
    </div>
  </div>
</nav>

方向

RTL

在RTL中使用Bootstrap时，方向是映射的，这意味着.dropstart将出现在右侧。

下拉向上

通过将.dropup添加到父元素，触发元素上方的下拉菜单。

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</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-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

下拉向右

通过将.dropend添加到父元素，触发元素右侧的下拉菜单。

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

<!-- Split dropend button -->
<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary">
    Split dropend
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
    <span class="visually-hidden">Toggle Dropright</span>
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

下拉向左

通过将.dropstart添加到父元素，触发元素左侧的下拉菜单。

<!-- Default dropstart button -->
<div class="btn-group dropstart">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropstart
  </button>
  <ul class="dropdown-menu">
    <!-- Dropdown menu links -->
  </ul>
</div>

<!-- Split dropstart button -->
<div class="btn-group">
  <div class="btn-group dropstart" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
      <span class="visually-hidden">Toggle Dropstart</span>
    </button>
    <ul class="dropdown-menu">
      <!-- Dropdown menu links -->
    </ul>
  </div>
  <button type="button" class="btn btn-secondary">
    Split dropstart
  </button>
</div>

历史上，下拉菜单的内容必须是链接，但v4不再是这种情况。现在，您可以选择在下拉列表中使用<button>元素，而不仅仅是<a>。

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

也可以使用.dropdown-item-text创建非交互式下拉项。您可以随意使用自定义CSS或文本工具进一步设计样式。

<ul class="dropdown-menu">
  <li><span class="dropdown-item-text">Dropdown item text</span></li>
  <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>

Active

将.active添加到下拉列表中的项以将其设置为活动样式。要将活动状态传递给辅助技术，请使用 aria-current属性-使用当前page的页面值，或使用集合中当前项的 true。

<ul class="dropdown-menu">
  <li><a class="dropdown-item" href="#">Regular link</a></li>
  <li><a class="dropdown-item active" href="#" aria-current="true">Active link</a></li>
  <li><a class="dropdown-item" href="#">Another link</a></li>
</ul>

禁用

将 .disabled添加到下拉列表中的项以将其样式设置为禁用。

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

默认情况下，下拉菜单自动定位在距父菜单顶部100%的位置，并沿父菜单的左侧。将.dropdown-menu-end 添加到 .dropdown-menu以右对齐下拉菜单。在RTL中使用Bootstrap时，方向是映射的，这意味着.dropdown-menu-end将出现在左侧。

抬头！ 下拉菜单的定位得益于Popper（除非它们包含在导航栏中）。

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Right-aligned menu example
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><button class="dropdown-item" type="button">Action</button></li>
    <li><button class="dropdown-item" type="button">Another action</button></li>
    <li><button class="dropdown-item" type="button">Something else here</button></li>
  </ul>
</div>

响应式对齐

如果要使用响应式对齐，请通过添加data-bs-display="static"属性禁用动态定位，并使用响应式变体类。

要将下拉菜单与给定断点或更大断点右对齐，请添加 .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end。

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

要将下拉菜单与给定断点或更大断点左对齐，请添加.dropdown-menu-end 和 .dropdown-menu{-sm|-md|-lg|-xl|-xxl}-start。

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

注意，您不需要向导航栏中的下拉按钮添加data-bs-display="static"属性，因为导航栏中没有使用Popper。

标头

在任何下拉菜单中添加header以标记操作的各个部分。

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

分隔线

用分隔符分隔相关菜单项组。

<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>
  <li><hr class="dropdown-divider"></li>
  <li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>

文本

将任意形式的文本放置在带有文本的下拉菜单中，并使用间距工具。请注意，您可能需要其他大小调整样式来约束菜单宽度。

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

表单

将表单放入下拉菜单中，或将其放入下拉菜单中，然后使用边距或填充实用程序为其提供所需的负空间。

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="mb-3">
      <label for="exampleDropdownFormEmail1" class="form-label">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
    </div>
    <div class="mb-3">
      <label for="exampleDropdownFormPassword1" class="form-label">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="mb-3">
      <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="mb-3">
    <label for="exampleDropdownFormEmail2" class="form-label">Email address</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
  </div>
  <div class="mb-3">
    <label for="exampleDropdownFormPassword2" class="form-label">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="mb-3">
    <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>

使用 data-bs-offset 或 data-bs-reference更改下拉列表的位置。

<div class="d-flex">
  <div class="dropdown me-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-bs-toggle="dropdown" aria-expanded="false" data-bs-offset="10,20">
      Offset
    </button>
    <ul class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
      <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 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-bs-toggle="dropdown" aria-expanded="false" data-bs-reference="parent">
      <span class="visually-hidden">Toggle Dropdown</span>
    </button>
    <ul class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <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>
      <li><hr class="dropdown-divider"></li>
      <li><a class="dropdown-item" href="#">Separated link</a></li>
    </ul>
  </div>
</div>

用法

通过数据属性或JavaScript，下拉插件通过切换父类.dropdown-menu上的.show类来切换隐藏内容（下拉菜单）。 data-bs-toggle="dropdown" 属性依赖于关闭应用程序级别的下拉菜单，因此最好始终使用它。

在支持触摸的设备上，打开下拉列表会将空mouseover处理程序添加到<body>元素的直接子级。这一公认的丑陋的黑客行为对于解决iOS事件委托中的一个怪癖是必要的，否则会阻止在下拉列表之外的任何地方点击触发关闭下拉列表的代码。关闭下拉列表后，这些额外的空mouseover处理程序将被删除。

通过数据属性

将data-bs-toggle="dropdown"添加到链接或按钮以切换下拉列表。

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

通过JavaScrip

通过JavaScript调用下拉列表：

var dropdownElementList = [].slice.call(document.querySelectorAll('.dropdown-toggle'))
var dropdownList = dropdownElementList.map(function (dropdownToggleEl) {
  return new bootstrap.Dropdown(dropdownToggleEl)
})

`data-bs-toggle="dropdown"` 仍然需要

无论您是通过JavaScript调用下拉列表还是使用data-api，都需要在下拉列表的触发器元素上显示data-bs-toggle="dropdown" 。

选项

选项可以通过数据属性或JavaScript传递。对于数据属性，将选项名称附加到 data-bs-，如data-bs-offset=""中所示。

名称	类型	默认值	描述
`flip`	boolean	`true`	如果参照元素重叠，允许下拉菜单翻转。有关更多信息，请参阅Popper的flip 文档。
`boundary`	string \| element	`'scrollParent'`	下拉菜单的溢出约束边界。默认情况下，它是`'clippingParents'`，可以接受HTMLElement引用（仅限于JavaScript）。有关更多信息，请参阅 Popper的 preventOverflow 文档。
`reference`	string \| element	`'toggle'`	下拉菜单的引用元素。接受`'toggle'`， `'parent'`，或HTMLElement引用的值。有关更多信息，请参阅Popper的构造函数文档。
`display`	string	`'dynamic'`	默认情况下，我们使用Popper进行动态定位。使用`static`禁用此功能。
`popperConfig`	null \| object	`null`	要更改Bootstrap的默认Popper配置，请参阅Popper的配置。

注意：当boundary设置为除 'scrollParent'以外的任何值时，样式position: static 将应用于 .dropdown 容器。

方法

方法	描述
`toggle`	切换给定导航栏或选项卡式导航的下拉菜单。
`show`	显示给定导航栏或选项卡式导航的下拉菜单。
`hide`	隐藏给定导航栏或选项卡式导航的下拉菜单。
`update`	更新元素下拉列表的位置。
`dispose`	销毁元素的下拉列表。（删除DOM元素上存储的数据）
`getInstance`	静态方法，它允许您获取与DOM元素关联的下拉实例。

事件

所有下拉事件都在.dropdown-menu的父元素上激发，并具有一个 relatedTarget属性，其值为 toggling anchor 元素。 hide.bs.dropdown 和 hidden.bs.dropdown 事件具有一个 clickEvent属性（仅当原始事件类型为click时），该属性包含click事件的事件对象。

方法	描述
`show.bs.dropdown`	调用show实例方法时立即触发。
`shown.bs.dropdown`	当下拉菜单对用户可见并且CSS转换完成时触发。
`hide.bs.dropdown`	调用hide实例方法后立即触发。
`hidden.bs.dropdown`	当下拉菜单完成向用户隐藏并且CSS转换完成时触发。

var myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.bs.dropdown', function () {
  // do something...
})

下拉菜单

概览

辅助功能

示例

单个按钮

拆分按钮

尺寸

深色下拉列表

方向

RTL

下拉向上

下拉向右

下拉向左

菜单项

Active

禁用

菜单对齐

响应式对齐

菜单内容

标头

分隔线

文本

表单

用法

通过数据属性

通过JavaScrip

`data-bs-toggle="dropdown"` 仍然需要

选项

方法

事件

下拉菜单

概览

辅助功能

示例

单个按钮

拆分按钮

尺寸

深色下拉列表

方向

RTL

下拉向上

下拉向右

下拉向左

菜单项

Active

禁用

菜单对齐

响应式对齐

菜单内容

标头

Dropdown header

分隔线

文本

表单

下拉选项

用法

通过数据属性

通过JavaScrip

data-bs-toggle="dropdown" 仍然需要

选项

方法

事件

`data-bs-toggle="dropdown"` 仍然需要