跳至主要内容 跳至文档导航
在 GitHub 上查看

下拉菜单

使用 Bootstrap 下拉插件切换上下文叠加层，以显示链接列表等内容。

本页内容

概述

下拉菜单是可切换的上下文叠加层，用于显示链接列表等内容。它们通过包含的 Bootstrap 下拉 JavaScript 插件实现交互性。它们通过单击而不是悬停来切换；这是一个 有意的设计决策。

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

辅助功能

WAI ARIA 标准定义了一个实际的 role="menu" 小部件，但这特定于触发动作或功能的应用程序式菜单。 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>

深色下拉菜单

在 v5.3.0 中已弃用

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

注意！在 v5.3.0 中，随着色彩模式的引入，组件的深色变体已弃用。不要添加 .dropdown-menu-dark，而是在根元素、父包装器或组件本身上设置 data-bs-theme="dark"。

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-end 添加到 .dropdown-menu，以便将下拉菜单右对齐。在 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>

文本

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

在下拉菜单中自由流动的示例文本。

这是更多示例文本。

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>

表单

在下拉菜单中放置一个表单，或将其制作成下拉菜单，并使用 边距或内边距实用程序 为其提供所需的负空间。

新用户？注册 忘记密码？
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 protected]">
    </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 protected]">
    </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

变量

在 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

可以通过 .dropdown-menu-dark 类看到通过 CSS 变量进行的自定义，我们在此类中覆盖特定值，而无需添加重复的 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 mixin

Mixin 用于生成基于 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 处理程序。不可否认，这个很丑陋的 hack 是为了解决 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))

选项

由于可以通过数据属性或 JavaScript 传递选项，因此您可以将选项名称附加到 data-bs-，例如 data-bs-animation="{value}"。通过数据属性传递选项时，请务必将选项名称的类型从“camelCase”更改为“kebab-case”。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

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

最终的配置对象是 data-bs-config、data-bs- 和 js object 合并的结果，其中最新给出的键值对会覆盖其他键值对。

名称 类型 默认值 描述
autoClose 布尔值、字符串 true 配置下拉菜单的自动关闭行为
  • true - 单击下拉菜单外部或内部将关闭下拉菜单。
  • false - 单击切换按钮并手动调用 hide 或 toggle 方法将关闭下拉菜单。（也不会通过按 Esc 键关闭）
  • 'inside' - 仅通过单击下拉菜单内部将关闭下拉菜单。
  • 'outside' - 仅通过单击下拉菜单外部将关闭下拉菜单。
注意：始终可以通过 Esc 键关闭下拉菜单。
boundary 字符串、元素 'clippingParents' 下拉菜单的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它是 clippingParents，并且可以接受一个 HTMLElement 引用（仅通过 JavaScript）。有关详细信息，请参阅 Popper 的 detectOverflow 文档。
display 字符串 'dynamic' 默认情况下，我们使用 Popper 进行动态定位。使用 static 禁用此功能。
offset 数组、字符串、函数 [0, 2] 下拉菜单相对于其目标的偏移量。您可以使用逗号分隔值在数据属性中传递字符串，例如：data-bs-offset="10,20"。当使用函数确定偏移量时，它会被调用，其第一个参数是一个包含 Popper 放置、引用和 Popper 矩形的对象。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding、distance。有关详细信息，请参阅 Popper 的 offset 文档。
popperConfig null、对象、函数 null 要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。当使用函数创建 Popper 配置时，它会被调用，其中包含一个对象，该对象包含 Bootstrap 的默认 Popper 配置。它可以帮助你使用和合并默认配置和自定义配置。该函数必须返回一个 Popper 配置对象。
reference 字符串、元素、对象 'toggle' 下拉菜单的引用元素。接受的值包括 'toggle'、'parent'、一个 HTMLElement 引用或一个提供 getBoundingClientRect 的对象。有关更多信息，请参阅 Popper 的 构造函数文档 和 虚拟元素文档。

使用带有 popperConfig 的函数 

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

方法

方法 描述
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 时），其中包含一个用于单击事件的事件对象。

事件类型 描述
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...
})