下拉菜单（Dropdowns）

下拉菜单是一个可切换的叠加层，用于显示链接列表等。Bootstrap 5 的下拉菜单基于 Popper.js 实现定位，支持多种触发方式、对齐选项和变体样式。

注意：下拉菜单依赖 Popper.js，bootstrap.bundle.js 已内置 Popper。

基础下拉菜单

<div class="dropdown">
    <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
        下拉按钮
    </button>
    <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">操作一</a></li>
        <li><a class="dropdown-item" href="#">操作二</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#">分离操作</a></li>
    </ul>
</div>

按钮组下拉

将下拉菜单与其他按钮组合，创建分割按钮效果：

<div class="btn-group">
    <button type="button" class="btn btn-primary">主要操作</button>
    <button type="button" class="btn btn-primary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false">
        <span class="visually-hidden">切换下拉</span>
    </button>
    <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">操作一</a></li>
        <li><a class="dropdown-item" href="#">操作二</a></li>
    </ul>
</div>

对齐方式

通过 .dropdown-menu-end 实现右对齐：

<div class="dropdown">
    <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
        右对齐下拉
    </button>
    <ul class="dropdown-menu dropdown-menu-end">
        <li><a class="dropdown-item" href="#">菜单项</a></li>
    </ul>
</div>

响应式对齐：.dropdown-menu{-sm|-md|-lg|-xl|-xxl}-end

触发方式

默认点击触发，可使用以下 data-bs-* 属性改变行为：

属性	说明
`data-bs-toggle="dropdown"`	点击触发（默认）
`data-bs-auto-close="true"`	点击外部区域时关闭（默认）
`data-bs-auto-close="false"`	点击外部区域时不关闭
`data-bs-auto-close="inside"`	仅点击菜单内部时关闭
`data-bs-auto-close="outside"`	仅点击菜单外部时关闭
`data-bs-display="static"`	不动态调整位置
`data-bs-dropdown="true"`	Navbar 中防止链接跳转

悬停触发

使用 CSS 实现鼠标悬停展开：

<div class="dropdown dropdown-hover">
    <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
        悬停触发
    </button>
    <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">鼠标悬停展开</a></li>
    </ul>
</div>

<style>
.dropdown-hover:hover > .dropdown-menu {
    display: block;
}
</style>

菜单内容

下拉菜单不仅限于链接，可以包含多种内容：

<div class="dropdown-menu">
    <!-- 标题 -->
    <h6 class="dropdown-header">下拉菜单标题</h6>
    
    <!-- 普通项 -->
    <a class="dropdown-item" href="#">普通链接</a>
    
    <!-- 禁用项 -->
    <a class="dropdown-item disabled" href="#">禁用项</a>
    
    <!-- 分隔线 -->
    <hr class="dropdown-divider">
    
    <!-- 表单 -->
    <form class="px-4 py-3">
        <div class="mb-3">
            <label class="form-label">邮箱</label>
            <input type="email" class="form-control" placeholder="[email protected]">
        </div>
        <button type="submit" class="btn btn-primary">登录</button>
    </form>
</div>

变体样式

不同的按钮颜色都支持下拉菜单：

<!-- 使用不同颜色的按钮 -->
<button class="btn btn-primary dropdown-toggle" data-bs-toggle="dropdown">主要</button>
<button class="btn btn-success dropdown-toggle" data-bs-toggle="dropdown">成功</button>
<button class="btn btn-outline-danger dropdown-toggle" data-bs-toggle="dropdown">警告</button>

<!-- 大/小尺寸 -->
<button class="btn btn-primary btn-lg dropdown-toggle" data-bs-toggle="dropdown">大按钮</button>
<button class="btn btn-primary btn-sm dropdown-toggle" data-bs-toggle="dropdown">小按钮</button>

方向上拉

使用 .dropup 让菜单向上展开：

<div class="btn-group dropup">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown">
        上拉菜单
    </button>
    <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">菜单项</a></li>
    </ul>
</div>

其他方向：

.dropup — 向上展开
.dropend — 向右展开
.dropstart — 向左展开

JavaScript API

// 通过 data 属性（推荐使用）
data-bs-toggle="dropdown"

// 编程式控制
const dropdownEl = document.getElementById('myDropdown');
const dropdown = bootstrap.Dropdown.getOrCreateInstance(dropdownEl);
dropdown.show();
dropdown.hide();
dropdown.toggle();

// 更新位置（当菜单内容变化时）
dropdown.update();

// 监听事件
dropdownEl.addEventListener('show.bs.dropdown', () => {});
dropdownEl.addEventListener('shown.bs.dropdown', () => {});
dropdownEl.addEventListener('hide.bs.dropdown', () => {});
dropdownEl.addEventListener('hidden.bs.dropdown', () => {});