in English

下拉菜单

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

概述

下拉菜单是可切换的上下文覆盖,用于显示链接列表等。它们与包含的 Bootstrap 下拉 JavaScript 插件交互。它们是通过单击而不是悬停来切换的;这是一个有意的设计决定

下拉菜单基于第三方库Popper构建,该库提供动态定位和视口检测。请务必在 Bootstrap 的 JavaScript 之前包含popper.min.jsbootstrap.bundle.min.js或使用/bootstrap.bundle.js其中包含 Popper。尽管不需要动态定位,但 Popper 不用于在导航栏中定位下拉菜单。

如果您从源代码构建我们的 JavaScript,它需要util.js.

可访问性

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

另一方面,Bootstrap 的下拉菜单被设计为通用的,适用于各种情况和标记结构。例如,可以创建包含其他输入和表单控件的下拉菜单,例如搜索字段或登录表单。出于这个原因,Bootstrap 不期望(也不会自动添加)真正的ARIA菜单所需的任何role和属性。作者必须自己包含这些更具体的属性。aria-

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

例子

将下拉菜单的切换(您的按钮或链接)和下拉菜单包装在.dropdown或另一个声明position: relative;. 可以从<a><button>元素触发下拉菜单,以更好地满足您的潜在需求。

单键

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

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

并带有<a>元素:

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

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

最好的部分是您也可以使用任何按钮变体来执行此操作:

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" 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在下拉插入符号周围添加了适当的间距。

我们使用这个额外的类将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-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-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-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-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-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

方向

放弃

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

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" 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-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-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-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-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">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" 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>s。

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu">
    <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到下拉列表中的项目以将它们设置为 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到下拉列表中的项目以将它们设置为 disabled

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

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

小心!下拉菜单的位置要归功于 Popper(除非它们包含在导航栏中)。
<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" 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>

响应式对齐

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

要将下拉菜单与给定断点或更大的断点对齐,添加.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-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>

要将下拉菜单与给定断点或更大的断点对齐,请添加.dropdown-menu-right.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-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>

请注意,您不需要为data-display="static"导航栏中的下拉按钮添加属性,因为在导航栏中不使用 Popper。

标头

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

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

形式

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

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

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

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false" data-offset="10,20">
      Offset
    </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>
  </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" data-toggle="dropdown" aria-expanded="false" data-reference="parent">
      <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>
</div>

用法

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

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

通过数据属性

添加data-toggle="dropdown"到链接或按钮以切换下拉菜单。

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

通过 JavaScript

通过 JavaScript 调用下拉菜单:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown"仍然需要

无论您是通过 JavaScript 调用下拉菜单还是使用 data-api,data-toggle="dropdown"都必须始终出现在下拉菜单的触发元素上。

选项

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

姓名 类型 默认 描述
抵消 号码 | 字符串 | 功能 0

下拉菜单相对于其目标的偏移量。

当使用函数确定偏移量时,会使用包含偏移量数据的对象作为其第一个参数来调用它。该函数必须返回具有相同结构的对象。触发元素 DOM 节点作为第二个参数传递。

有关更多信息,请参阅 Popper 的偏移量文档

翻动 布尔值 真的 允许下拉菜单在参考元素重叠的情况下翻转。有关更多信息,请参阅 Popper 的翻转文档
边界 字符串 | 元素 '滚动父' 下拉菜单的溢出约束边界。接受 、 、 或 HTMLElement 引用的值'viewport''window'仅限'scrollParent'JavaScript)。有关更多信息,请参阅 Popper 的preventOverflow 文档
参考 字符串 | 元素 '切换' 下拉菜单的引用元素。接受 、 或 HTMLElement 引用的'toggle''parent'。有关详细信息,请参阅 Popper 的referenceObject 文档
展示 细绳 '动态的' 默认情况下,我们使用 Popper 进行动态定位。用 禁用它static
popperConfig 空 | 目的 无效的 要更改 Bootstrap 的默认 Popper 配置,请参阅Popper 的配置

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

方法

方法 描述
$().dropdown('toggle') 切换给定导航栏或选项卡式导航的下拉菜单。
$().dropdown('show') 显示给定导航栏或选项卡式导航的下拉菜单。
$().dropdown('hide') 隐藏给定导航栏或选项卡式导航的下拉菜单。
$().dropdown('update') 更新元素下拉列表的位置。
$().dropdown('dispose') 销毁元素的下拉列表。

活动

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

事件 描述
show.bs.dropdown 此事件在调用 show 实例方法时立即触发。
shown.bs.dropdown 当下拉菜单对用户可见时触发此事件(将等待 CSS 转换完成)​​。
hide.bs.dropdown 当调用 hide 实例方法时,会立即触发此事件。
hidden.bs.dropdown 当下拉菜单完成对用户隐藏时触发此事件(将等待 CSS 转换完成)​​。
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something...
})