下拉菜单

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

当前页

概述

下拉列表是可切换的上下文叠加层，用于显示链接列表等。它们与随附的 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>

调整尺寸大小（Sizing）

按钮下拉列表适用于各种大小的按钮，包括默认和拆分下拉按钮。

<!-- 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-dark添加到现有的.dropdown-menu。无需对下拉项进行任何更改。

注意！ 组件的深色变体在 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

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

通过将.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

将.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">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@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:               $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 用于生成基于 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" 属性依赖于在应用程序级别关闭下拉菜单，因此最好始终使用它。

在支持触摸的设备上，打开下拉列表会将空的 mouseover处理程序添加到<body>元素的直接子级。这个公认的丑陋黑客对于解决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

下拉列表的触发器元素上必须包含data-bs-toggle="dropdown"，无论您是通过 JavaScript 调用下拉列表还是使用 data-api。

通过 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}'。

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

将函数与`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...
})

下拉菜单

概述

可访问性

示例

单个按钮

拆分按钮

调整尺寸大小（Sizing）

深色下拉菜单

方向

居中

下拉

下拉居中

Dropend

启动（Dropstart）

菜单项

Active

禁用

菜单对齐

响应式对齐

对齐选项

菜单内容

标题

Dropdown header

分隔符

文本

表单

下拉选项

自动关闭行为

CSS

变量

Sass 变量

Sass 混合

用法

通过数据属性

通过 JavaScript

选项

将函数与popperConfig一起使用

方法

事件

将函数与`popperConfig`一起使用