下拉式選單

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

概觀

下拉式選單是可以切換的，用於顯示連結清單等內容的情境式覆蓋層。它們透過內含的 Bootstrap 下拉式選單 JavaScript 外掛程式，變成互動式的。它們是透過點擊切換，而不是滑鼠移入；這是一項有意的設計決策。

下拉式選單建立在第三方函式庫 Popper 上，它提供動態定位和視窗偵測。務必在 Bootstrap 的 JavaScript 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js。不過，Popper 並未用於定位導覽列中的下拉式選單，因為不需要動態定位。

如果您從原始碼建置我們的 JavaScript，它需要 util.js。

無障礙

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

另一方面，Bootstrap 的下拉式選單設計成通用，適用於各種情況和標記結構。例如，可以建立包含其他輸入和表單控制項的下拉式選單，例如搜尋欄位或登入表單。因此，Bootstrap 沒有預期（或自動新增）任何真正的 ARIA 選單所需的 role 和 aria- 屬性。作者必須自己包含這些更具體的屬性。

不過，Bootstrap 確實新增了對大多數標準鍵盤選單互動的內建支援，例如使用游標鍵瀏覽個別 .dropdown-item 元素，並使用 ESC 鍵關閉選單。

範例

將下拉式選單的切換（按鈕或連結）和下拉式選單包在 .dropdown 中，或宣告 position: relative; 的其他元素中。可以從 <a> 或 <button> 元素觸發下拉式選單，以更符合您的潛在需求。

單一按鈕

任何單一的 .btn 都可以透過一些標記變更變成下拉式選單切換。以下是使用 <button> 元素讓它們運作的方法

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

以及使用 <a> 元素

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown link
  </a>

  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

最棒的是，您也可以對任何按鈕變體執行此操作

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Action
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</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-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

大小

按鈕下拉式選單適用於所有尺寸的按鈕，包括預設和分割下拉式按鈕。

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Large button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</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-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- Small button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Small button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</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-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

方向

向上彈出

透過在父元素中新增 .dropup 來在元素上方觸發下拉式選單。

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</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-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

向右彈出

透過在父元素中新增 .dropright 來在元素右側觸發下拉式選單。

<!-- Default dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropright
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Split dropright
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropright</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

向左彈出

透過在父元素中新增 .dropleft 來在元素左側觸發下拉式選單。

<!-- Default dropleft button -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropleft
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropleft button -->
<div class="btn-group">
  <div class="btn-group dropleft">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
      <span class="sr-only">Toggle Dropleft</span>
    </button>
    <div class="dropdown-menu">
      <!-- Dropdown menu links -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Split dropleft
  </button>
</div>

傳統上，下拉式選單內容必須是連結，但在 v4 中已不再如此。現在，您可以在下拉式選單中選擇使用 <button> 元素，而不再僅限於 <a>。

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

您也可以使用 .dropdown-item-text 建立非互動式下拉式選單項目。歡迎使用自訂 CSS 或文字工具進一步設定樣式。

<div class="dropdown-menu">
  <span class="dropdown-item-text">Dropdown item text</span>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
</div>

作用中

在下拉式選單中新增 .active 至項目以將其樣式設定為已啟用。

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item active" href="#">Active link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

停用

在下拉式選單中新增 .disabled 至項目以將其樣式設定為已停用。

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

預設情況下，下拉式選單會自動從其父元素的頂端和左側定位 100%。在 .dropdown-menu 中新增 .dropdown-menu-right 以將下拉式選單右對齊。

請注意！ 下拉式選單會透過 Popper 定位（除非它們包含在導覽列中）。

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Right-aligned menu
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

回應式對齊

如果您想使用回應式對齊，請透過新增 data-display="static" 屬性來停用動態定位，並使用回應式變異類別。

若要將下拉式選單與指定的斷點或較大尺寸右對齊，請新增 .dropdown-menu{-sm|-md|-lg|-xl}-right。

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    Left-aligned but right aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-lg-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

若要將下拉式選單與指定的斷點或較大尺寸左對齊，請新增 .dropdown-menu-right 和 .dropdown-menu{-sm|-md|-lg|-xl}-left。

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    Right-aligned but left aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

請注意，您不需要在導覽列中的下拉式按鈕中新增 data-display="static" 屬性，因為導覽列中不會使用 Popper。

標題

在任何下拉式選單中新增標頭標籤動作區段。

<div class="dropdown-menu">
  <h6 class="dropdown-header">Dropdown header</h6>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
</div>

分隔線

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

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Separated link</a>
</div>

文字

在下拉式選單中放置任何自由格式文字和使用間距工具。請注意，您可能需要額外的調整大小樣式來限制選單寬度。

<div class="dropdown-menu p-4 text-muted" 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>

表單

在下拉式選單中放置表單，或將其製成下拉式選單，並使用邊距或內距工具來提供您所需的負空間。

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="form-group">
      <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>

<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Email address</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="form-group">
    <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>

使用 data-offset 或 data-reference 來變更下拉式選單的位置。

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false" data-offset="10,20">
      Offset
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
    </div>
  </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-toggle="dropdown" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
      <div class="dropdown-divider"></div>
      <a class="dropdown-item" href="#">Separated link</a>
    </div>
  </div>
</div>

用法

透過資料屬性或 JavaScript，下拉式選單外掛程式會在父 .dropdown-menu 上切換 .show 類別，來切換隱藏的內容（下拉式選單）。data-toggle="dropdown" 屬性用於在應用程式層級關閉下拉式選單，因此最好總是使用它。

在觸控裝置上，開啟下拉式選單會將空的 ($.noop) mouseover 處理常式新增到 <body> 元素的直接子元素。這種公認醜陋的技巧對於解決 iOS 事件委派中的怪癖是必要的，否則會阻止在下拉式選單外部的任何地方輕觸，觸發關閉下拉式選單的程式碼。一旦下拉式選單關閉，這些額外的空 mouseover 處理常式就會被移除。

透過資料屬性

將 data-toggle="dropdown" 加入連結或按鈕以切換下拉選單。

<div class="dropdown">
  <button type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown trigger
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

透過 JavaScript

透過 JavaScript 呼叫下拉選單

$('.dropdown-toggle').dropdown()

`data-toggle="dropdown"` 仍然需要

無論您透過 JavaScript 呼叫下拉選單或使用 data-api，data-toggle="dropdown" 始終需要存在於下拉選單的觸發元素中。

選項

選項可透過資料屬性或 JavaScript 傳遞。對於資料屬性，將選項名稱附加到 data-，例如 data-offset=""。

名稱	類型	預設值	說明
offset	數字 \| 字串 \| 函式	0	下拉選單相對於其目標的偏移量。當使用函式來決定偏移量時，會呼叫一個物件，其中包含偏移量資料作為其第一個引數。函式必須傳回具有相同結構的物件。觸發元素 DOM 節點傳遞為第二個引數。有關更多資訊，請參閱 Popper 的偏移量文件。
flip	布林值	true	允許下拉選單在與參考元素重疊的情況下翻轉。有關更多資訊，請參閱 Popper 的翻轉文件。
boundary	字串 \| 元素	'scrollParent'	下拉選單功能表的溢位約束邊界。接受 `'viewport'`、`'window'`、`'scrollParent'` 的值，或一個 HTMLElement 參考（僅限 JavaScript）。有關更多資訊，請參閱 Popper 的防止溢位文件。
reference	字串 \| 元素	'toggle'	下拉選單功能表的參考元素。接受 `'toggle'`、`'parent'` 的值，或一個 HTMLElement 參考。有關更多資訊，請參閱 Popper 的 referenceObject 文件。
display	字串	'dynamic'	預設情況下，我們使用 Popper 進行動態定位。使用 `static` 停用此功能。
popperConfig	null \| 物件	null	若要變更 Bootstrap 的預設 Popper 組態，請參閱 Popper 的組態

請注意，當 boundary 設定為 'scrollParent' 以外的任何值時，樣式 position: static 會套用至 .dropdown 容器。

方法

方法	說明
`$().dropdown('toggle')`	切換給定導覽列或標籤式導覽的下拉式選單。
`$().dropdown('show')`	顯示給定導覽列或標籤式導覽的下拉式選單。
`$().dropdown('hide')`	隱藏給定導覽列或標籤式導覽的下拉式選單。
`$().dropdown('update')`	更新元素下拉式選單的位置。
`$().dropdown('dispose')`	銷毀元素的下拉式選單。

事件

所有下拉式選單事件都觸發於 .dropdown-menu 的父元素，並具有 relatedTarget 屬性，其值為切換錨定元素。hide.bs.dropdown 和 hidden.bs.dropdown 事件具有 clickEvent 屬性（僅當原始事件類型為 click 時），其中包含點擊事件的事件物件。

事件	說明
`show.bs.dropdown`	當呼叫 show 實例方法時，此事件會立即觸發。
`shown.bs.dropdown`	當下拉式選單對使用者可見時，此事件會觸發（會等待 CSS 轉場完成）。
`hide.bs.dropdown`	當呼叫 hide 實例方法時，此事件會立即觸發。
`hidden.bs.dropdown`	當下拉式選單對使用者隱藏完成時，此事件會觸發（會等待 CSS 轉場完成）。

$('#myDropdown').on('show.bs.dropdown', function () {
  // do something...
})

下拉式選單

概觀

無障礙

範例

單一按鈕

分割按鈕

大小

方向

向上彈出

向右彈出

向左彈出

選單項目

作用中

停用

選單對齊

回應式對齊

選單內容

標題

下拉式選單標頭

分隔線

文字

表單