下拉選單（Dropdowns）

使用 Bootstrap 下拉選單外掛程式，切換顯示連結清單及更多內容的情境式覆蓋層。

本頁內容

概覽（Overview）

下拉選單是可切換的情境式覆蓋層，用於顯示連結清單及更多內容。透過內建的 Bootstrap 下拉選單 JavaScript 外掛程式，使其具有互動性。下拉選單是透過點擊而非懸停來觸發；這是刻意的設計決定。

下拉選單建構於第三方函式庫 Popper 之上，提供動態定位和視窗偵測功能。請確保在 Bootstrap 的 JavaScript 之前引入 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js。不過在導覽列中的下拉選單不會使用 Popper，因為不需要動態定位。

無障礙（Accessibility）

WAI ARIA 標準定義了實際的 role="menu" 小工具，但這是專門用於觸發動作或函式的應用程式選單。ARIA 選單只能包含選單項目、核取方塊選單項目、單選按鈕選單項目、單選按鈕群組和子選單。

另一方面，Bootstrap 的下拉選單設計為通用型，適用於各種情況和標記結構。例如，可以建立包含額外輸入欄位和表單控制項的下拉選單，如搜尋欄位或登入表單。因此，Bootstrap 不期望（也不會自動加入）真正的 ARIA 選單所需的任何 role 和 aria- 屬性。開發者需要自行加入這些更具體的屬性。

然而，Bootstrap 確實為大多數標準鍵盤選單互動加入了內建支援，例如使用方向鍵在各個 .dropdown-item 元素之間移動，以及使用 Esc 鍵關閉選單的功能。

範例（Examples）

將下拉選單的切換器（您的按鈕或連結）和下拉選單包裹在 .dropdown 中，或另一個宣告 position: relative; 的元素中。理想情況下，您應該使用 <button> 元素作為下拉選單觸發器，但外掛程式也可以與 <a> 元素搭配使用。這裡顯示的範例在適當的地方使用語意化的 <ul> 元素，但也支援自訂標記。

單一按鈕（Single button）

任何單一 .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">
    Danger
  </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>

分離式按鈕（Split button）

同樣地，使用與單一按鈕下拉選單幾乎相同的標記來建立分離式按鈕下拉選單，但需要加入 .dropdown-toggle-split 以在下拉箭頭周圍提供適當的間距。

我們使用這個額外的類別來將箭頭兩側的水平 padding 減少 25%，並移除一般按鈕下拉選單所加入的 margin-left。這些額外的變更使箭頭在分離式按鈕中保持置中，並在主按鈕旁邊提供更適當大小的點擊區域。

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Danger</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>

深色下拉選單（Dark dropdowns）

Deprecated in 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>

方向（Directions）

方向在 RTL 模式下會翻轉。 因此，.dropstart 會出現在右側。

置中（Centered）

在父元素上使用 .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）

在父元素上加入 .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 centered）

在父元素上使用 .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）

在下拉選單項目上加入 .disabled，將其設定為停用狀態樣式。

html

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

預設情況下，下拉選單會自動定位於距離父元素頂部 100% 處，並沿著父元素的左側。您可以使用方向性的 .drop* 類別來變更此設定，也可以使用額外的修飾類別來控制。

在 .dropdown-menu 上加入 .dropdown-menu-end，使下拉選單靠右對齊。在 Bootstrap 的 RTL 模式下，方向會鏡像翻轉，這意味著 .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>

響應式對齊（Responsive alignment）

如果您想使用響應式對齊，請透過加入 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。

對齊選項（Alignment options）

結合上述大部分選項，以下是各種下拉選單對齊選項的綜合展示。

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>

標題（Headers）

在任何下拉選單中加入標題來標示動作區塊。

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>

分隔線（Dividers）

使用分隔線來區隔相關選單項目的群組。

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>

文字（Text）

在下拉選單中放置任意格式的文字，並使用間距通用類別。請注意，您可能需要額外的尺寸樣式來限制選單寬度。

html

<div class="dropdown-menu p-4 text-body-secondary" style="max-width: 200px;">
  <p>
    Some example text that’s free-flowing within the dropdown menu.
  </p>
  <p class="mb-0">
    And this is more example text.
  </p>
</div>

表單（Forms）

將表單放置在下拉選單中，或將其製作成下拉選單，並使用外距或內距通用類別來提供您所需的間距。

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>

自動關閉行為（Auto close behavior）

預設情況下，點擊下拉選單內部或外部時都會關閉選單。您可以使用 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

變數（Variables）

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 變數（Sass variables）

所有下拉選單的變數：

scss/_variables.scss

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

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

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

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

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

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

深色下拉選單的變數：

scss/_variables.scss

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

表示下拉選單互動性的 CSS 箭頭變數：

scss/_variables.scss

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

Sass mixins

Mixins 用於產生 CSS 箭頭，可以在 scss/mixins/_caret.scss 中找到。

scss/mixins/_caret.scss

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

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

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

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

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

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

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

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

使用方式（Usage）

透過 data 屬性或 JavaScript，下拉選單外掛程式會透過在父元素 .dropdown-menu 上切換 .show 類別來切換隱藏內容（下拉選單）。data-bs-toggle="dropdown" 屬性用於在應用程式層級關閉下拉選單，因此建議始終使用它。

在觸控裝置上，開啟下拉選單會在 <body> 元素的直接子元素上加入空的 mouseover 處理器。這個看起來不太優雅的技巧是為了解決 iOS 事件委派的怪異行為，否則點擊下拉選單外部的任何地方都無法觸發關閉下拉選單的程式碼。一旦下拉選單關閉，這些額外的空 mouseover 處理器就會被移除。

透過 data 屬性（Via data attributes）

在連結或按鈕上加入 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（Via JavaScript）

無論您是透過 JavaScript 呼叫下拉選單還是使用 data-api，下拉選單的觸發元素都必須有 data-bs-toggle="dropdown"。

透過 JavaScript 呼叫下拉選單：

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

選項（Options）

由於選項可以透過 data 屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過 data 屬性傳遞選項時，請確保將選項名稱的大小寫類型從「camelCase」更改為「kebab-case」。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援實驗性的保留 data 屬性 data-bs-config，可以將簡單的元件配置作為 JSON 字串存放。當元素同時具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最終的 title 值將是 456，個別的 data 屬性將覆寫 data-bs-config 中給定的值。此外，現有的 data 屬性也能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

名稱	類型	預設值	說明
`autoClose`	boolean, string	`true`	設定下拉選單的自動關閉行為： `true` - 點擊下拉選單內部或外部都會關閉選單。 `false` - 需要點擊切換按鈕或手動呼叫 `hide` 或 `toggle` 方法才會關閉選單。（按 `Esc` 鍵也不會關閉） `'inside'` - 只有點擊下拉選單內部才會關閉選單。 `'outside'` - 只有點擊下拉選單外部才會關閉選單。注意：下拉選單始終可以使用 `Esc` 鍵關閉。
`boundary`	string, element	`'clippingParents'`	下拉選單的溢位限制邊界（僅適用於 Popper 的 preventOverflow 修飾器）。預設為 `clippingParents`，可以接受 HTMLElement 參考（僅限透過 JavaScript）。更多資訊請參閱 Popper 的 detectOverflow 文件。
`display`	string	`'dynamic'`	預設情況下，我們使用 Popper 進行動態定位。使用 `static` 來停用此功能。
`offset`	array, string, function	`[0, 2]`	下拉選單相對於目標的位移。您可以在 data 屬性中傳遞以逗號分隔的字串值，例如：`data-bs-offset="10,20"`。當使用函式來決定位移時，它會以包含 popper 位置、參考和 popper 矩形的物件作為第一個引數被呼叫。觸發元素的 DOM 節點會作為第二個引數傳遞。函式必須傳回包含兩個數字的陣列：skidding、distance。更多資訊請參閱 Popper 的 offset 文件。
`popperConfig`	null, object, function	`null`	若要變更 Bootstrap 的預設 Popper 設定，請參閱 Popper 的配置。當使用函式來建立 Popper 配置時，它會以包含 Bootstrap 預設 Popper 配置的物件被呼叫。這可以幫助您使用並合併預設設定和您自己的配置。函式必須傳回 Popper 的配置物件。
`reference`	string, element, object	`'toggle'`	下拉選單的參考元素。接受 `'toggle'`、`'parent'`、HTMLElement 參考或提供 `getBoundingClientRect` 的物件。更多資訊請參閱 Popper 的 constructor 文件和 virtual element 文件。

使用函式搭配 `popperConfig`（Using function with `popperConfig`）

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

方法（Methods）

方法	說明
`dispose`	銷毀元素的下拉選單。（移除儲存在 DOM 元素上的資料）
`getInstance`	靜態方法，允許您取得與 DOM 元素關聯的下拉選單實體，您可以這樣使用：`bootstrap.Dropdown.getInstance(element)`。
`getOrCreateInstance`	靜態方法，傳回與 DOM 元素關聯的下拉選單實體，如果尚未初始化則建立新的。您可以這樣使用：`bootstrap.Dropdown.getOrCreateInstance(element)`。
`hide`	隱藏指定導覽列或分頁導覽的下拉選單。
`show`	顯示指定導覽列或分頁導覽的下拉選單。
`toggle`	切換指定導覽列或分頁導覽的下拉選單。
`update`	更新元素下拉選單的位置。

事件（Events）

所有下拉選單事件都在切換元素上觸發，然後向上冒泡。因此您也可以在 .dropdown-menu 的父元素上加入事件監聽器。hide.bs.dropdown 和 hidden.bs.dropdown 事件有一個 clickEvent 屬性（僅當原始事件類型是 click 時），其中包含點擊事件的 Event 物件。

事件類型	說明
`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...
})

下拉選單（Dropdowns）

概覽（Overview）

無障礙（Accessibility）

範例（Examples）

單一按鈕（Single button）

分離式按鈕（Split button）

尺寸（Sizing）

深色下拉選單（Dark dropdowns）

方向（Directions）

置中（Centered）

向上展開（Dropup）

向上展開置中（Dropup centered）

向右展開（Dropend）

向左展開（Dropstart）

選單項目（Menu items）

啟用狀態（Active）

停用狀態（Disabled）

選單對齊（Menu alignment）

響應式對齊（Responsive alignment）

對齊選項（Alignment options）

選單內容（Menu content）

標題（Headers）

分隔線（Dividers）

文字（Text）

表單（Forms）

自動關閉行為（Auto close behavior）

CSS

變數（Variables）

Sass 變數（Sass variables）

Sass mixins

使用方式（Usage）

透過 data 屬性（Via data attributes）

透過 JavaScript（Via JavaScript）

選項（Options）

使用函式搭配 `popperConfig`（Using function with `popperConfig`）

方法（Methods）

事件（Events）

下拉選單（Dropdowns）

概覽（Overview）

無障礙（Accessibility）

範例（Examples）

單一按鈕（Single button）

分離式按鈕（Split button）

尺寸（Sizing）

深色下拉選單（Dark dropdowns）

方向（Directions）

置中（Centered）

向上展開（Dropup）

向上展開置中（Dropup centered）

向右展開（Dropend）

向左展開（Dropstart）

選單項目（Menu items）

啟用狀態（Active）

停用狀態（Disabled）

選單對齊（Menu alignment）

響應式對齊（Responsive alignment）

對齊選項（Alignment options）

選單內容（Menu content）

標題（Headers）

Dropdown header

分隔線（Dividers）

文字（Text）

表單（Forms）

下拉選單選項（Dropdown options）

自動關閉行為（Auto close behavior）

CSS

變數（Variables）

Sass 變數（Sass variables）

Sass mixins

使用方式（Usage）

透過 data 屬性（Via data attributes）

透過 JavaScript（Via JavaScript）

選項（Options）

使用函式搭配 popperConfig（Using function with popperConfig）

方法（Methods）

事件（Events）

使用函式搭配 `popperConfig`（Using function with `popperConfig`）