下拉菜单 (Dropdowns)

使用Bootstrap下拉插件用于显示切换你要展示的链接列表和更多内容的，或触发其它内容显示(覆盖）。

概览

弹出菜单是可触发的、上下文叠加显示链接列表和别的内容。它们可以与Bootstrap内置的弹出菜单JavaScript插件交互。通过点击触发，而不是通过鼠标悬停悬浮，这是一种设计思维。

下拉菜单控件依赖于第三方 Popper.js插件实现，Popper.js插件提供了动态定痊和viewport浏览器窗口大小监测，使用时请确保popper.min.js 文件放在Bootstrap JS之前，或者使用 bootstrap.bundle.min.js / bootstrap.bundle.js这两个文件，因为这两个文件中已经包含了Popper.js。

如果你要自行编译JS，记得 包含 util.js。

无障碍浏览提示(易用性)

WAIARIA标准定义了 role="menu" 插件, 但這是專門用於應用程式的功能表，它們觸發動作或功能。 ARIA菜单只能包含菜单列表、复选框、单选框、单选按钮组和子菜单。

Bootstrap的下拉菜单则是设计为通用的，适用于各种情形和标记结构，如可以创建包含其它输入和表单控制项（如搜索栏位或登录表单）的下拉菜单，因此，Bootstrap 不希望（也不能自動添加）与 ARIA菜单所需要的 role 和 aria- 属性，如果有必要请用户自行定义这类属性。

然而，BootStrap为大多数标准键盘功能操作加入了支持，如.dropdown-item 支持光标移动选择单个子项、并使用关闭菜单的 ESC 快捷键功能。

示例

将下拉列表的切换（按钮或链接）和下拉菜单包含在.dropdown中，或者另外声明position: relative;元素;可以从<a> 或 <button>触发下拉菜单，以适应你的使用的需求。

单一按钮的下拉菜单

任何一个 .btn块都可以定义变更为下拉菜单，下面是两个使用<button> 元素做下拉菜单的示例。

下拉菜单(Dropdown) - 图1

  1. <div class="dropdown">
  2.   <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  3.     Dropdown button
  4.   </button>
  5.   <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
  6.     <a class="dropdown-item" href="#">Action</a>
  7.     <a class="dropdown-item" href="#">Another action</a>
  8.     <a class="dropdown-item" href="#">Something else here</a>
  9.   </div>
  10. </div>

使用 <a> 标签的下拉菜单：

下拉菜单(Dropdown) - 图2

  1. <div class="dropdown show">
  2.   <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  3.     Dropdown link
  4.   </a>
  6.   <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
  7.     <a class="dropdown-item" href="#">Action</a>
  8.     <a class="dropdown-item" href="#">Another action</a>
  9.     <a class="dropdown-item" href="#">Something else here</a>
  10.   </div>
  11. </div>

还可以自由引用.btn-prima等颜色及样式类来定义下拉菜单的外在表现：

下拉菜单(Dropdown) - 图3

  1. <!-- Example single danger button -->
  2. <div class="btn-group">
  3.   <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  4.     Action
  5.   </button>
  6.   <div class="dropdown-menu">
  7.     <a class="dropdown-item" href="#">Action</a>
  8.     <a class="dropdown-item" href="#">Another action</a>
  9.     <a class="dropdown-item" href="#">Something else here</a>
  10.     <div class="dropdown-divider"></div>
  11.     <a class="dropdown-item" href="#">Separated link</a>
  12.   </div>
  13. </div>

分裂式按钮下拉菜单

同样，可用与单个按钮下拉菜单近似的标记创建分裂式下拉菜单，注意添加了.dropdown-toggle-split -插入此符号为下拉选项作适当的间隔（距）处理。

我们使用这个额外的Class样式，将插入符号两边水平padding减少了25%，并移除了为默认下拉菜单添加的 margin-left 属性，这些额外的更改将插入符号集中在分裂式按钮中，并在主按钮旁边提供了适合的点击空间。

下拉菜单(Dropdown) - 图4

  1. <!-- Example split danger button -->
  2. <div class="btn-group">
  3.   <button type="button" class="btn btn-danger">Action</button>
  4.   <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  5.     <span class="sr-only">Toggle Dropdown</span>
  6.   </button>
  7.   <div class="dropdown-menu">
  8.     <a class="dropdown-item" href="#">Action</a>
  9.     <a class="dropdown-item" href="#">Another action</a>
  10.     <a class="dropdown-item" href="#">Something else here</a>
  11.     <div class="dropdown-divider"></div>
  12.     <a class="dropdown-item" href="#">Separated link</a>
  13.   </div>
  14. </div>

尺寸大小定义

下拉菜单有各种大小规格可以选用，包括预设及分裂式按钮下拉菜单。

下拉菜单(Dropdown) - 图5

  1. <!-- Large button groups (default and split) -->
  2. <div class="btn-group">
  3.   <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  4.     Large button
  5.   </button>
  6.   <div class="dropdown-menu">
  7.     ...
  8.   </div>
  9. </div>
  10. <div class="btn-group">
  11.   <button class="btn btn-secondary btn-lg" type="button">
  12.     Large button
  13.   </button>
  14.   <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  15.     <span class="sr-only">Toggle Dropdown</span>
  16.   </button>
  17.   <div class="dropdown-menu">
  18.     ...
  19.   </div>
  20. </div>
  22. <!-- Small button groups (default and split) -->
  23. <div class="btn-group">
  24.   <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  25.     Small button
  26.   </button>
  27.   <div class="dropdown-menu">
  28.     ...
  29.   </div>
  30. </div>
  31. <div class="btn-group">
  32.   <button class="btn btn-secondary btn-sm" type="button">
  33.     Small button
  34.   </button>
  35.   <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  36.     <span class="sr-only">Toggle Dropdown</span>
  37.   </button>
  38.   <div class="dropdown-menu">
  39.     ...
  40.   </div>
  41. </div>

方向

方向向上

增加.dropup 样式，使下拉菜单向上展开。

下拉菜单(Dropdown) - 图6

  1. <!-- Default dropup button -->
  2. <div class="btn-group dropup">
  3.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  4.     Dropup
  5.   </button>
  6.   <div class="dropdown-menu">
  7.     <!-- Dropdown menu links -->
  8.   </div>
  9. </div>
  10. <!-- Split dropup button -->
  11. <div class="btn-group dropup">
  12.   <button type="button" class="btn btn-secondary">
  13.     Split dropup
  14.   </button>
  15.   <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  16.     <span class="sr-only">Toggle Dropdown</span>
  17.   </button>
  18.   <div class="dropdown-menu">
  19.     <!-- Dropdown menu links -->
  20.   </div>
  21. </div>

方向向右

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

下拉菜单(Dropdown) - 图7

  1. <!-- Default dropright button -->
  2. <div class="btn-group dropright">
  3.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  4.     Dropright
  5.   </button>
  6.   <div class="dropdown-menu">
  7.     <!-- Dropdown menu links -->
  8.   </div>
  9. </div>
  11. <!-- Split dropright button -->
  12. <div class="btn-group dropright">
  13.   <button type="button" class="btn btn-secondary">
  14.     Split dropright
  15.   </button>
  16.   <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  17.     <span class="sr-only">Toggle Dropright</span>
  18.   </button>
  19.   <div class="dropdown-menu">
  20.     <!-- Dropdown menu links -->
  21.   </div>
  22. </div>

方向向左

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

下拉菜单(Dropdown) - 图8

  1. <!-- Default dropleft button -->
  2. <div class="btn-group dropleft">
  3.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  4.     Dropleft
  5.   </button>
  6.   <div class="dropdown-menu">
  7.     <!-- Dropdown menu links -->
  8.   </div>
  9. </div>
  11. <!-- Split dropleft button -->
  12. <div class="btn-group">
  13.   <div class="btn-group dropleft" role="group">
  14.     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  15.       <span class="sr-only">Toggle Dropleft</span>
  16.     </button>
  17.     <div class="dropdown-menu">
  18.       <!-- Dropdown menu links -->
  19.     </div>
  20.   </div>
  21.   <button type="button" class="btn btn-secondary">
  22.     Split dropleft
  23.   </button>
  24. </div>

菜单项

旧版Boostrap(v3)下拉菜单中的子菜单项必须是链接，但v4不再是这种情况，现在你可选择使用<button>下拉列表中的元素，而不是仅仅 <a>标签。

下拉菜单(Dropdown) - 图9

  1. <div class="dropdown">
  2.   <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  3.     Dropdown
  4.   </button>
  5.   <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
  6.     <button class="dropdown-item" type="button">Action</button>
  7.     <button class="dropdown-item" type="button">Another action</button>
  8.     <button class="dropdown-item" type="button">Something else here</button>
  9.   </div>
  10. </div>

你可以创建非交互式下拉菜单项 .dropdown-item-text. 还可以随意使用定制的CSS或文本实用程序进一步设计样式.

下拉菜单(Dropdown) - 图10

  1. <div class="dropdown-menu">
  2.   <span class="dropdown-item-text">Dropdown item text</span>
  3.   <a class="dropdown-item" href="#">Action</a>
  4.   <a class="dropdown-item" href="#">Another action</a>
  5.   <a class="dropdown-item" href="#">Something else here</a>
  6. </div>

有效菜单

加上 .active 让下拉列表中的项 样式为active.

下拉菜单(Dropdown) - 图11

  1. <div class="dropdown-menu">
  2.   <a class="dropdown-item" href="#">Regular link</a>
  3.   <a class="dropdown-item active" href="#">Active link</a>
  4.   <a class="dropdown-item" href="#">Another link</a>
  5. </div>

不可用菜单

加上.disabled 让下拉列表中的项 样式为不可用.

下拉菜单(Dropdown) - 图12

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

菜单对齐

默认情况下，一个下拉菜单自动从顶部和左侧的父级100％定位。添加.dropdown-menu-right 到.dropdown-menu右侧轻松对齐下拉菜单。

Heads up! Dropdowns are positioned thanks to Popper.js (except when they are contained in a navbar).

下拉菜单(Dropdown) - 图13

  1. <div class="btn-group">
  2.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  3.     Right-aligned menu
  4.   </button>
  5.   <div class="dropdown-menu dropdown-menu-right">
  6.     <button class="dropdown-item" type="button">Action</button>
  7.     <button class="dropdown-item" type="button">Another action</button>
  8.     <button class="dropdown-item" type="button">Something else here</button>
  9.   </div>
  10. </div>

响应式对齐

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

为了下拉菜单 右对齐和给定断点或更大的断点, 加上.dropdown-menu{-sm|-md|-lg|-xl}-right.

下拉菜单(Dropdown) - 图14

  1. <div class="btn-group">
  2.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
  3.     Left-aligned but right aligned when large screen
  4.   </button>
  5.   <div class="dropdown-menu dropdown-menu-lg-right">
  6.     <button class="dropdown-item" type="button">Action</button>
  7.     <button class="dropdown-item" type="button">Another action</button>
  8.     <button class="dropdown-item" type="button">Something else here</button>
  9.   </div>
  10. </div>

为了下拉菜单 左对齐和给定断点或更大的断点,加上.dropdown-menu-right 和 .dropdown-menu{-sm|-md|-lg|-xl}-left.

下拉菜单(Dropdown) - 图15

  1. <div class="btn-group">
  2.   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
  3.     Right-aligned but left aligned when large screen
  4.   </button>
  5.   <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
  6.     <button class="dropdown-item" type="button">Action</button>
  7.     <button class="dropdown-item" type="button">Another action</button>
  8.     <button class="dropdown-item" type="button">Something else here</button>
  9.   </div>
  10. </div>

注意，你不需要添加 data-display="static"属性设置为导航栏中的下拉按钮，因为导航条中不使用Popper.js.

菜单内容

头部

添加标题来标记任何下拉菜单中的操作部分。

下拉菜单(Dropdown) - 图16

  1. <div class="dropdown-menu">
  2.   <h6 class="dropdown-header">Dropdown header</h6>
  3.   <a class="dropdown-item" href="#">Action</a>
  4.   <a class="dropdown-item" href="#">Another action</a>
  5. </div>

菜单分隔与分割线

使用分隔符分割相关菜单子项，呈现出分组和分割线效果。

下拉菜单(Dropdown) - 图17

  1. <div class="dropdown-menu">
  2.   <a class="dropdown-item" href="#">Action</a>
  3.   <a class="dropdown-item" href="#">Another action</a>
  4.   <a class="dropdown-item" href="#">Something else here</a>
  5.   <div class="dropdown-divider"></div>
  6.   <a class="dropdown-item" href="#">Separated link</a>
  7. </div>

文本

在文本下拉菜单中放置任何自由格式的文本并使用间隔工具。请注意，您可能需要额外的大小调整样式来限制菜单宽度。

下拉菜单(Dropdown) - 图18

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

菜单表单

将表单放在下拉菜单中，或将其放入下拉菜单中，并使用margin 或 padding 通用CSS样式调整空间和位置。

下拉菜单(Dropdown) - 图19

  1. <div class="dropdown-menu">
  2.   <form class="px-4 py-3">
  3.     <div class="form-group">
  4.       <label for="exampleDropdownFormEmail1">Email address</label>
  5.       <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
  6.     </div>
  7.     <div class="form-group">
  8.       <label for="exampleDropdownFormPassword1">Password</label>
  9.       <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
  10.     </div>
  11.     <div class="form-check">
  12.       <input type="checkbox" class="form-check-input" id="dropdownCheck" >
  13.       <label class="form-check-label"  for="dropdownCheck" >
  14.         Remember me
  15.       </label>
  16.     </div>
  17.     <button type="submit" class="btn btn-primary">Sign in</button>
  18.   </form>
  19.   <div class="dropdown-divider"></div>
  20.   <a class="dropdown-item" href="#">New around here? Sign up</a>
  21.   <a class="dropdown-item" href="#">Forgot password?</a>
  22. </div>

下拉菜单(Dropdown) - 图20

  1. <form class="dropdown-menu p-4">
  2.   <div class="form-group">
  3.     <label for="exampleDropdownFormEmail2">Email address</label>
  4.     <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
  5.   </div>
  6.   <div class="form-group">
  7.     <label for="exampleDropdownFormPassword2">Password</label>
  8.     <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  9.   </div>
  10.   <div class="form-check">
  11.     <input type="checkbox" class="form-check-input" id="dropdownCheck2" >
  12.     <label class="form-check-label" for="dropdownCheck2" >
  13.       Remember me
  14.     </label>
  15.   </div>
  16.   <button type="submit" class="btn btn-primary">Sign in</button>
  17. </form>

下拉选项

使用data-offset或data-reference更改下拉菜单的位置。

下拉菜单(Dropdown) - 图21

  1. <div class="d-flex">
  2.   <div class="dropdown mr-1">
  3.     <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-offset="10,20">
  4.       Offset
  5.     </button>
  6.     <div class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
  7.       <a class="dropdown-item" href="#">Action</a>
  8.       <a class="dropdown-item" href="#">Another action</a>
  9.       <a class="dropdown-item" href="#">Something else here</a>
  10.     </div>
  11.   </div>
  12.   <div class="btn-group">
  13.     <button type="button" class="btn btn-secondary">Reference</button>
  14.     <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">
  15.       <span class="sr-only">Toggle Dropdown</span>
  16.     </button>
  17.     <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
  18.       <a class="dropdown-item" href="#">Action</a>
  19.       <a class="dropdown-item" href="#">Another action</a>
  20.       <a class="dropdown-item" href="#">Something else here</a>
  21.       <div class="dropdown-divider"></div>
  22.       <a class="dropdown-item" href="#">Separated link</a>
  23.     </div>
  24.   </div>
  25. </div>

用例

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

在可触摸设备上，打开一个下拉菜单会将($.noop) mouseover事件传递给 <body>，这是移动浏览器针对触屏的特殊处理方法（可见 quirk in iOS’ event delegation），否则在下拉菜单之外的任何地方点击会无法触发关闭下拉菜单事件。一旦关闭下拉菜单，这些额外的事件会被立即移除。

通过事件属性

添加 data-toggle="dropdown" 在A链接或按钮上，以启用下拉菜单组件。

  1. <div class="dropdown">
  2.   <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  3.     Dropdown trigger
  4.   </button>
  5.   <div class="dropdown-menu" aria-labelledby="dLabel">
  6.     ...
  7.   </div>
  8. </div>

通过JavaScript

通过JavaScript调用下菜菜单:

  1. $('.dropdown-toggle').dropdown()
data-toggle="dropdown" 需要保留

无论你是采用JavaScript 或者 data-api调用下拉菜单， data-toggle="dropdown" 总要保留在下拉列表的触发器元素中。

选项

可以通过数据属性或JavaScript传递选项。对于数据属性，选项名称追加到 data-，如： data-offset="".

名称Type类型Default默认值描述说明
offsetnumber | string | function0下拉菜单相对于目标的偏移，参考Popper.js偏移文档。
flipbooleantrue允许下拉菜单重叠到其相关元素上，参考 Popper.js触发文档。

方法

MethodDescription
$().dropdown('toggle')给导航栏或分页启用下拉菜单功能。
$().dropdown('update')更新下拉列表的位置。
$().dropdown('dispose')销毁一个元素的下拉菜单。

事件

All dropdown events are fired at the .dropdown-menu’s parent element and have a relatedTarget property, whose value is the toggling anchor element.

Event事件描述说明
show.bs.dropdown当调用show显示方法时，此事件会立即触发。
shown.bs.dropdown当下拉菜单对用户可见时，会触发此事件（将等待CSS转换完成）​​。
hide.bs.dropdown当调用隐藏实例方法时，会立即触发此事件。
hidden.bs.dropdown当下拉菜单从用户隐藏完毕时，会触发此事件（将等待CSS转换完成）​​。
  1. $('#myDropdown').on('show.bs.dropdown', function () {
  2.   // do something…
  3. })