下拉菜单

使用 Bootstrap 下拉菜单插件通过链接来切换内文框显示

概述

下拉选单是可切换的,内文框用于显示链接列表或其他。这些交互功能于 Bootstrap JavaScript 下拉选单插件提供。通过点击切换,而不是滑入的方式,这是一个策划好了的 设计决定。

下拉选单是通过第三方插件, Popper.js 所建构的,这提供了动态位置及 viewport 的监控。使用前请确认 popper.min.js在 Bootstrap’s JavaScript 之前,或者使用 bootstrap.bundle.min.js / bootstrap.bundle.js 这已经包含 Popper.js。Popper.js 没有使用在导览列的下拉选单,所以该动态位置并不适用。

如果你要自行编译 JS,记得引入util.js

可视性

WAI ARIA 该标准定义了role="menu" 小部件,但这是专门用于应用程式的功能表,它们触发动作或功能。 ARIA 选单只能包含功能表项目,核取方块功能表项目,选项按钮功能表项目,选项按钮组和子功能表。ARIA 菜单只能包含菜单项,复选框菜单项,单选按钮菜单项,单选按钮组和子菜单。

Bootstrap 的下拉选单是设计为通用的,适用于各种情况和标记结构。 例如,可以创建包含其他输入和表单控制项(如搜索栏位或登录表单)的下拉选单。 因此,Bootstrap 不希望(也不能自动添加)true ARIA 功能表所需的任何 rolearia- 属性。 作者必须自己加入这些具体属性。

然而,Bootstrap 为大多数标准键盘功能表操作加入内置支援,例如使用游标键移动单个 。 .dropdown-item 元素并使用ESC 键关闭功能表的功能。

实例

.dropdown中包含下拉选单的切换(你的按钮或链接)和下拉式功能表,或者另外一个声明 position: relative; 的元素。 可以从 <a><button> 元素裡触发下拉选单,以适应你的潜在需求。

单一按钮

任何一个 .btn 可以变成带有一些标记的下拉式切换。以下是你如何使用 <button> 元素:

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

通过 <a> 元素:

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

最好的部分是你可以使用任何按钮变化做到这一点:

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

分离按钮

同样的,用与单个按钮下拉选单几乎相同的标记创建分割按钮下拉选单,但是添加了 .dropdown-toggle-split 以在下拉插入符号做适当间隔。

我们使用这个额外的 class 将插入符号的两边水平 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-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>

尺寸

按钮下拉选单可以使用所有尺寸的按钮,包括默认及分割下拉按钮。

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

指向

Dropup

通过添加到父元素,在元素上方的装配下拉菜单 .dropup

<!-- 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 到父元素上来切换向右侧的选单。

<!-- 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 到父元素上来切换向左侧的选单。

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

在过去下拉选单内容必须是个连接,但 v4 不再是这样。现在你可以选择在下拉选单中使用 <button> 元素,而不是仅使用 <a>

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

你还可以使用 .dropdown-item-text 创建非交互式下拉选单。你可以使用自定义 CSS 或通用类别调整。

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

添加

增加 .active 到项目上使 样式如同添加。

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

禁用

增加 .disabled 到下拉列表中的项目 将它们设为禁用。

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

默认情况下,下拉菜单会自动从其父级的顶部和左侧100%定位。 添加 .dropdown-menu-right.dropdown-menu 中可右键对齐下拉菜单。

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

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

表头

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

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

分隔线

使用分隔符号来分隔选单中的群组。

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

表单

在下拉式选单中加入表单,并且使用 margin or padding utilities 调整所需要的空间。

<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@example.com">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck">
      <label class="form-check-label" for="dropdownCheck">
        Remember me
      </label>
    </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@example.com">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input" id="dropdownCheck2">
    <label class="form-check-label" for="dropdownCheck2">
      Remember me
    </label>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

使用 data-offsetdata-reference 来改变下拉选单的位置。

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

用法

通过 data 属性或 JavaScript,下拉选单插件通过切换父级按钮上 .show 来切换隐藏内容(下拉选单)。 data-toggle="dropdown" 依赖于属性来关闭应用程序级别的下拉菜单,因此始终使用它是个好主意。

在带有触屏的设备上,打开下拉列表会将空($.noop)鼠标悬停处理程序添加到 <body> 元素的直接子项。 为了解决 iOS 平台上事件响应的一些奇怪表现(外部资料:英文内容),需要进行额外的处理,否则会阻止在下拉列表之外的任何位置触发关闭下拉列表的代码。 关闭下拉列表后,将删除这些额外的空鼠标悬停处理程序。

通过 data 属性

加入 data-toggle="dropdown" 至链接或按钮来启用切换下拉选单。

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

通过 JavaScript

通过 JavaScript 来调用下拉选单:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown" still required

无论是通过 JavaScript 调用你的下拉清单或使用 data-api, data-toggle="dropdown" 都需要在下拉选单的触发器元素中显示。

选项

可以通过 data 属性或 JavaScript 插件传递选项。对于 data 属性,将选项名称加到data- 上,如 data-offset=""

名称 类型 默认值 描述
offset number | string | function 0 下拉选单相对于其目标的偏移参考 Popper.js 的位移文件。
flip boolean true 允许下拉选单重叠到其相关的元素上,更多资讯可参考 Popper.js 的触发文件。
boundary string | element 'scrollParent' 下拉菜单的溢出约束边界。 接受 'viewport', 'window', 'scrollParent', HTMLElement引用的值(仅限JavaScript)。 有关更多信息,请参阅 Popper.js 的 preventOverflow 文档。
reference string | element 'toggle' Reference element of the dropdown menu. Accepts the values of 'toggle', 'parent', or an HTMLElement reference. For more information refer to Popper.js's referenceObject docs.
display string 'dynamic' By default, we use Popper.js for dynamic positioning. Disable this with static.

方法

请注意,当boundary被设置为 'scrollParent',之外的任何值时 position: static 样式应用于 .dropdown 容器。

方法 描述
$().dropdown('toggle') 切换给定导航栏或选项卡式导航的下拉菜单
$().dropdown('update') 更新下拉选单元素的定位。
$().dropdown('dispose') 销毁一个元素的下拉选单。

事件

所有下拉选单事件在 .dropdown-menu 的父元素下触发,并具有一个 relatedTarget 属性,其值是切换的锚元素。 hide.bs.dropdownhidden.bs.dropdown 事件具有 clickEvent 属性(仅当单击原始事件类型时),该属性包含 click 事件的事件对象。

事件 描述
show.bs.dropdown 这个事件在调用显示时被立即触发。
shown.bs.dropdown 当这个物件可被看见时会触发此事件(当完成 CSS 转换后)。
hide.bs.dropdown 这个事件在调用隐藏时被立即触发。
hidden.bs.dropdown 当这个物件隐藏后会触发此事件(当完成 CSS 转换后)。
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})