跳至主要內容 跳至文件瀏覽
在 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

在父元素中新增 .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 至項目，以設定為活動樣式。若要傳達活動狀態給輔助技術，請使用 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@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

變數

新增於 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 混用

混用用於產生 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))

選項

由於選項可以透過資料屬性或 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 物件 的合併結果，其中最新給定的鍵值會覆寫其他鍵值。

名稱 類型 預設值 說明
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...
})