下拉菜单 (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菜单所需要的 rolearia- 属性,如果有必要请用户自行定义这类属性。

然而,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>
  5. <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
  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>

还可以自由引用.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>
  21. <!-- Small button groups (default and split) -->
  22. <div class="btn-group">
  23. <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  24. Small button
  25. </button>
  26. <div class="dropdown-menu">
  27. ...
  28. </div>
  29. </div>
  30. <div class="btn-group">
  31. <button class="btn btn-secondary btn-sm" type="button">
  32. Small button
  33. </button>
  34. <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  35. <span class="sr-only">Toggle Dropdown</span>
  36. </button>
  37. <div class="dropdown-menu">
  38. ...
  39. </div>
  40. </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>
  10. <!-- Split dropright button -->
  11. <div class="btn-group dropright">
  12. <button type="button" class="btn btn-secondary">
  13. Split dropright
  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 Dropright</span>
  17. </button>
  18. <div class="dropdown-menu">
  19. <!-- Dropdown menu links -->
  20. </div>
  21. </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>
  10. <!-- Split dropleft button -->
  11. <div class="btn-group">
  12. <div class="btn-group dropleft" role="group">
  13. <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
  14. <span class="sr-only">Toggle Dropleft</span>
  15. </button>
  16. <div class="dropdown-menu">
  17. <!-- Dropdown menu links -->
  18. </div>
  19. </div>
  20. <button type="button" class="btn btn-secondary">
  21. Split dropleft
  22. </button>
  23. </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-offsetdata-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. })