Skip to main content Skip to docs navigation
View on GitHub

下拉菜单（Dropdowns）

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

On this page

概述

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

下拉菜单基于第三方库 Popper，该库提供动态定位和视口检测功能。请确保在 Bootstrap 的 JavaScript 之前包含 popper.min.js，或者使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js。由于不需要动态定位，Popper 不用于定位导航栏中的下拉内容。

辅助功能

WAI ARIA 标准定义了一个实际的role="menu" widget，但这是针对触发操作或功能的应用程序类菜单而言的。ARIA 菜单只能包含菜单项、复选框菜单项、单选按钮菜单项、单选按钮组和子菜单。

.另一方面，Bootstrap 下拉菜单的设计是通用的，适用于各种情况和标记结构。例如，可以创建包含附加输入和表单控件（如搜索字段或登录表单）的下拉菜单。因此，Bootstrap 不需要（也不会自动添加）真正的 ARIA 菜单所需的任何 role 和 aria- 属性。作者必须自行添加这些更具体的属性。

不过，Bootstrap 确实添加了对大多数标准键盘菜单交互的内置支持，例如使用光标键在单 “.dropdown-item” 元素中移动，以及使用 Esc 键关闭菜单。

示例

将下拉菜单的切换按钮（按钮或链接）和下拉菜单包裹在 .dropdown或其他声明position: relative;的元素中。理想情况下，您应该使用 <button> 元素作为下拉触发器，但该插件也可以使用 <a> 元素。此处显示的示例在适当的地方使用了语义 <ul> 元素，但也支持自定义标记。

单个按钮

只需修改一些标记，任何一个 .btn 都可以变成下拉切换器。下面介绍如何使用 <button> 元素来使用它们：

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

虽然 <button> 是下拉切换的推荐控件，但在某些情况下您可能不得不使用 <a> 元素。如果需要，我们建议添加 role="button" 属性，以便向屏幕阅读器等辅助技术适当传达控件的用途。

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

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

深色下拉菜单

Deprecated in v5.3.0

通过在现有的 .dropdown-menu中添加 .dropdown-menu-dark，选择更深的下拉菜单，以匹配深色导航栏或自定义样式。无需更改下拉项目。

Heads up! Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding .dropdown-menu-dark, set data-bs-theme="dark" on the root element, a parent wrapper, or the component itself.

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

并将其用于导航栏：

html 
<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">
          <button class="btn btn-dark dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
            Dropdown
          </button>
          <ul class="dropdown-menu dropdown-menu-dark">
            <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 模式下， 方向是翻转的。 因此，.dropstart 将出现在右侧。

居中

在父元素上使用 .dropdown-center，使下拉菜单居中，位于切换按钮下方。

html 
<div class="dropdown-center">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Centered dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Action two</a></li>
    <li><a class="dropdown-item" href="#">Action three</a></li>
  </ul>
</div>

向上

通过在父元素中添加 .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>

向上居中

在父元素上使用 .dropup-center，使下拉菜单位于切换上方的中心位置。

html 
<div class="dropup-center dropup">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Centered dropup
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Action two</a></li>
    <li><a class="dropdown-item" href="#">Action three</a></li>
  </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">
    Dropend
  </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 Dropend</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 dropstart">
  <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>
  <button type="button" class="btn btn-secondary">
    Split dropstart
  </button>
</div>

菜单项

您可以使用 <a> 或 <button> 元素作为下拉项目。

html 
<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu">
    <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 或文本工具进一步调整样式。

html 
<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，将其 为活动 样式。要向辅助技术传达活动状态，请使用 aria-current 属性–使用 page 值表示当前页面，或使用 true 表示集合中的当前项目。

html 
<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，将其 为禁用 样式。

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

菜单对齐

默认情况下，下拉菜单会自动从顶部并沿着父菜单的左侧 100% 定位。您可以使用方向.drop*类来更改，也可以使用其他修改器类来控制。

在.dropdown-menu中添加.dropdown-menu-end 可使下拉菜单右对齐。在 RTL 中使用 Bootstrap 时，方向是镜像的，这意味着 .dropdown-menu-end 将显示在左侧。

注意！ 除了包含在导航栏中的下拉菜单，其他下拉菜单都是通过 Popper 定位的。
html 
<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 。

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

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

对齐选项

通过上面展示的大部分选项，下面是一个综合演示，将各种下拉对齐选项集于一身。

html 
<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Right-aligned menu
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<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, right-aligned lg
  </button>
  <ul class="dropdown-menu dropdown-menu-lg-end">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<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, left-aligned lg
  </button>
  <ul class="dropdown-menu dropdown-menu-end dropdown-menu-lg-start">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<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">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false">
    Dropend
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<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">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

菜单内容

标题

在任何下拉菜单中添加标题，以标注操作部分。

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

分隔

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

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

文本

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

Some example text that's free-flowing within the dropdown menu.

And this is more example text.

html 
<div class="dropdown-menu p-4 text-body-secondary" 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 或 padding 实用程序 为其提供所需的负空间。

New around here? Sign up Forgot password?
html 
<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>
html 
<div class="dropdown">
  <button type="button" class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown" aria-expanded="false" data-bs-auto-close="outside">
    Dropdown form
  </button>
  <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>
</div>

下拉选项

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

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

自动关闭行为

默认情况下，点击下拉菜单内部或外部时，下拉菜单会关闭。您可以使用 autoClose 选项来更改下拉菜单的这种行为。

html 
<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="true" aria-expanded="false">
    Default dropdown
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="inside" aria-expanded="false">
    Clickable inside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="outside" aria-expanded="false">
    Clickable outside
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

<div class="btn-group">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" data-bs-auto-close="false" aria-expanded="false">
    Manual close
  </button>
  <ul class="dropdown-menu">
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
    <li><a class="dropdown-item" href="#">Menu item</a></li>
  </ul>
</div>

CSS

变量

Added in v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，下拉菜单现在使用 .dropdown-menu上的本地 CSS 变量来增强实时自定义功能。CSS 变量的值通过 Sass 设置，因此仍支持 Sass 自定义。

scss/_dropdown.scss 
--#{$prefix}dropdown-zindex: #{$zindex-dropdown};
--#{$prefix}dropdown-min-width: #{$dropdown-min-width};
--#{$prefix}dropdown-padding-x: #{$dropdown-padding-x};
--#{$prefix}dropdown-padding-y: #{$dropdown-padding-y};
--#{$prefix}dropdown-spacer: #{$dropdown-spacer};
@include rfs($dropdown-font-size, --#{$prefix}dropdown-font-size);
--#{$prefix}dropdown-color: #{$dropdown-color};
--#{$prefix}dropdown-bg: #{$dropdown-bg};
--#{$prefix}dropdown-border-color: #{$dropdown-border-color};
--#{$prefix}dropdown-border-radius: #{$dropdown-border-radius};
--#{$prefix}dropdown-border-width: #{$dropdown-border-width};
--#{$prefix}dropdown-inner-border-radius: #{$dropdown-inner-border-radius};
--#{$prefix}dropdown-divider-bg: #{$dropdown-divider-bg};
--#{$prefix}dropdown-divider-margin-y: #{$dropdown-divider-margin-y};
--#{$prefix}dropdown-box-shadow: #{$dropdown-box-shadow};
--#{$prefix}dropdown-link-color: #{$dropdown-link-color};
--#{$prefix}dropdown-link-hover-color: #{$dropdown-link-hover-color};
--#{$prefix}dropdown-link-hover-bg: #{$dropdown-link-hover-bg};
--#{$prefix}dropdown-link-active-color: #{$dropdown-link-active-color};
--#{$prefix}dropdown-link-active-bg: #{$dropdown-link-active-bg};
--#{$prefix}dropdown-link-disabled-color: #{$dropdown-link-disabled-color};
--#{$prefix}dropdown-item-padding-x: #{$dropdown-item-padding-x};
--#{$prefix}dropdown-item-padding-y: #{$dropdown-item-padding-y};
--#{$prefix}dropdown-header-color: #{$dropdown-header-color};
--#{$prefix}dropdown-header-padding-x: #{$dropdown-header-padding-x};
--#{$prefix}dropdown-header-padding-y: #{$dropdown-header-padding-y};

下拉项目至少包含一个未在 .dropdown上设置的变量。这样，当 Bootstrap 默认使用回退值时，您就可以提供一个新值。

  • --bs-dropdown-item-border-radius

通过 CSS 变量进行自定义可以在.dropdown-menu-dark类中看到，我们可以覆盖特定值，而无需添加重复的 CSS 选择器。

scss/_dropdown.scss 
--#{$prefix}dropdown-color: #{$dropdown-dark-color};
--#{$prefix}dropdown-bg: #{$dropdown-dark-bg};
--#{$prefix}dropdown-border-color: #{$dropdown-dark-border-color};
--#{$prefix}dropdown-box-shadow: #{$dropdown-dark-box-shadow};
--#{$prefix}dropdown-link-color: #{$dropdown-dark-link-color};
--#{$prefix}dropdown-link-hover-color: #{$dropdown-dark-link-hover-color};
--#{$prefix}dropdown-divider-bg: #{$dropdown-dark-divider-bg};
--#{$prefix}dropdown-link-hover-bg: #{$dropdown-dark-link-hover-bg};
--#{$prefix}dropdown-link-active-color: #{$dropdown-dark-link-active-color};
--#{$prefix}dropdown-link-active-bg: #{$dropdown-dark-link-active-bg};
--#{$prefix}dropdown-link-disabled-color: #{$dropdown-dark-link-disabled-color};
--#{$prefix}dropdown-header-color: #{$dropdown-dark-header-color};

Sass 变量

所有下拉菜单的变量：

scss/_variables.scss 
$dropdown-min-width:                10rem;
$dropdown-padding-x:                0;
$dropdown-padding-y:                .5rem;
$dropdown-spacer:                   .125rem;
$dropdown-font-size:                $font-size-base;
$dropdown-color:                    var(--#{$prefix}body-color);
$dropdown-bg:                       var(--#{$prefix}body-bg);
$dropdown-border-color:             var(--#{$prefix}border-color-translucent);
$dropdown-border-radius:            var(--#{$prefix}border-radius);
$dropdown-border-width:             var(--#{$prefix}border-width);
$dropdown-inner-border-radius:      calc(#{$dropdown-border-radius} - #{$dropdown-border-width}); // stylelint-disable-line function-disallowed-list
$dropdown-divider-bg:               $dropdown-border-color;
$dropdown-divider-margin-y:         $spacer * .5;
$dropdown-box-shadow:               var(--#{$prefix}box-shadow);

$dropdown-link-color:               var(--#{$prefix}body-color);
$dropdown-link-hover-color:         $dropdown-link-color;
$dropdown-link-hover-bg:            var(--#{$prefix}tertiary-bg);

$dropdown-link-active-color:        $component-active-color;
$dropdown-link-active-bg:           $component-active-bg;

$dropdown-link-disabled-color:      var(--#{$prefix}tertiary-color);

$dropdown-item-padding-y:           $spacer * .25;
$dropdown-item-padding-x:           $spacer;

$dropdown-header-color:             $gray-600;
$dropdown-header-padding-x:         $dropdown-item-padding-x;
$dropdown-header-padding-y:         $dropdown-padding-y;
// fusv-disable
$dropdown-header-padding:           $dropdown-header-padding-y $dropdown-header-padding-x; // Deprecated in v5.2.0
// fusv-enable

深色下拉菜单的变量:

scss/_variables.scss 
$dropdown-dark-color:               $gray-300;
$dropdown-dark-bg:                  $gray-800;
$dropdown-dark-border-color:        $dropdown-border-color;
$dropdown-dark-divider-bg:          $dropdown-divider-bg;
$dropdown-dark-box-shadow:          null;
$dropdown-dark-link-color:          $dropdown-dark-color;
$dropdown-dark-link-hover-color:    $white;
$dropdown-dark-link-hover-bg:       rgba($white, .15);
$dropdown-dark-link-active-color:   $dropdown-link-active-color;
$dropdown-dark-link-active-bg:      $dropdown-link-active-bg;
$dropdown-dark-link-disabled-color: $gray-500;
$dropdown-dark-header-color:        $gray-500;

用于表示下拉菜单交互性的 CSS 符号的变量：

scss/_variables.scss 
$caret-width:                 .3em;
$caret-vertical-align:        $caret-width * .85;
$caret-spacing:               $caret-width * .85;

Sass mixins

Mixins 用于生成基于 CSS 的插入符号，可以在 ‘scss/mixins/_caret.scss’ 中找到。

scss/mixins/_caret.scss 
@mixin caret-down($width: $caret-width) {
  border-top: $width solid;
  border-right: $width solid transparent;
  border-bottom: 0;
  border-left: $width solid transparent;
}

@mixin caret-up($width: $caret-width) {
  border-top: 0;
  border-right: $width solid transparent;
  border-bottom: $width solid;
  border-left: $width solid transparent;
}

@mixin caret-end($width: $caret-width) {
  border-top: $width solid transparent;
  border-right: 0;
  border-bottom: $width solid transparent;
  border-left: $width solid;
}

@mixin caret-start($width: $caret-width) {
  border-top: $width solid transparent;
  border-right: $width solid;
  border-bottom: $width solid transparent;
}

@mixin caret(
  $direction: down,
  $width: $caret-width,
  $spacing: $caret-spacing,
  $vertical-align: $caret-vertical-align
) {
  @if $enable-caret {
    &::after {
      display: inline-block;
      margin-left: $spacing;
      vertical-align: $vertical-align;
      content: "";
      @if $direction == down {
        @include caret-down($width);
      } @else if $direction == up {
        @include caret-up($width);
      } @else if $direction == end {
        @include caret-end($width);
      }
    }

    @if $direction == start {
      &::after {
        display: none;
      }

      &::before {
        display: inline-block;
        margin-right: $spacing;
        vertical-align: $vertical-align;
        content: "";
        @include caret-start($width);
      }
    }

    &:empty::after {
      margin-left: 0;
    }
  }
}

用法

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

在支持触摸的设备上，打开下拉菜单时，会向<body> 的直接子元素添加空的 mouseover 处理程序。为了避免iOS 事件委托中的怪异之处，我们必须使用这一丑陋的黑客手段，否则在下拉菜单之外的任何地方点击鼠标都无法触发关闭下拉菜单的代码。一旦关闭下拉菜单，这些额外的空 mouseover 处理程序就会被移除。

通过数据属性

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

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

通过 JavaScript

无论您是通过 JavaScript 调用下拉菜单还是使用 data-api，下拉菜单的触发元素上都必须有 data-bs-toggle="dropdown" 。

通过 JavaScript 调用下拉菜单：

const dropdownElementList = document.querySelectorAll('.dropdown-toggle')
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl))

选项

由于可以通过 data 属性或 JavaScript 传递选项，因此可以在 data-bs- 中附加选项名称，如 data-bs-animation=“{value}”。通过data 属性传递选项时，请确保将选项名称的大小写类型从“camelCase”改为“kebab-case”。例如，使用 data-bs-custom-class=“beautifier” 而不是 data-bs-customClass=“beautifier”。

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

Name Type Default Description
autoClose boolean, string true 配置下拉菜单的自动关闭行为：
  • true - 点击下拉菜单外部或内部，下拉菜单就会关闭。
  • false - 点击切换按钮并手动调用 hide 或 toggle 方法，下拉菜单就会关闭。 （按Esc键也不会关闭）。
  • 'inside' - 单击下拉菜单内侧即可关闭下拉菜单。
  • 'outside' - 单击下拉菜单外侧将（仅）关闭下拉菜单。
注意：可以使用 Esc 键关闭下拉菜单。
boundary string, element 'clippingParents' 下拉菜单的溢出约束边界（仅适用于 Popper 的 preventOverflow 修改器）。默认情况下，它是 clippingParents 并且可以接受 HTMLElement 引用（仅通过 JavaScript）。更多信息请参阅 Popper 的 detectOverflow docs。
display string 'dynamic' 默认情况下，我们使用 Popper 进行动态定位。请使用 static禁用此功能。
offset array, string, function [0, 2] 下拉菜单相对于目标的偏移量。您可以在数据属性中传递一个以逗号分隔的字符串，例如 ：data-bs-offset="10,20"。当使用函数来确定偏移量时，它的第一个参数是一个包含弹出窗口位置、引用和弹出窗口矩形的对象。触发元素 DOM 节点作为第二个参数传递。函数必须返回一个包含两个数字的数组： 滑动、距离。更多信息请参阅 Popper 的 offset docs。
popperConfig null, object, function null 要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper’s configuration。当使用函数创建 Popper 配置时，会调用一个包含 Bootstrap 默认 Popper 配置的对象。它可以帮助您使用默认配置并将其与自己的配置合并。函数必须返回一个 Popper 配置对象。
reference string, element, object 'toggle' 下拉菜单的引用元素。接受'toggle'、 'parent'、HTMLElement 引用或提供 getBoundingClientRect 的对象的值。更多信息请参阅 Popper 的 构造函数文档 和 虚拟元素文档。

使用 popperConfig 函数 

const dropdown = new bootstrap.Dropdown(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

Method Description
dispose 销毁元素的下拉菜单。(删除 DOM 元素上存储的数据）
getInstance 静态方法，用于获取与 DOM 元素相关联的下拉实例： bootstrap.Dropdown.getInstance(element)。
getOrCreateInstance 静态方法，用于返回与 DOM 元素相关联的下拉实例，或在未初始化的情况下创建一个新的下拉实例。您可以这样使用它 bootstrap.Dropdown.getOrCreateInstance(element)。
hide 隐藏给定导航条或标签导航的下拉菜单。
show 显示给定导航条或标签导航的下拉菜单。
toggle 切换给定导航栏或标签导航的下拉菜单。
update 更新元素下拉菜单的位置。

事件

所有下拉菜单事件都会在切换元素上触发，然后冒泡上升。因此，您也可以在 .dropdown-menu的父元素上添加事件监听器。hide.bs.dropdown 和 hidden.bs.dropdown 事件有一个 clickEvent 属性（仅当原始事件类型为 click 时），其中包含一个用于单击事件的事件对象。

Event type Description
hide.bs.dropdown 当调用 hide 实例方法时立即触发。
hidden.bs.dropdown 当用户完成下拉菜单的隐藏且 CSS 过渡完成后触发。
show.bs.dropdown 调用 show 实例方法时立即触发。
shown.bs.dropdown 当用户看到下拉菜单且 CSS 过渡已完成时触发。 
const myDropdown = document.getElementById('myDropdown')
myDropdown.addEventListener('show.bs.dropdown', event => {
  // do something...
})