下拉選單 (Dropdowns)

使用 Bootstrap 下拉選單插件透過連結來切換內文框顯示。

六角學院 六角學院

六角學院的 Bootstrap 課程上線囉,立即與萬人一同學習最專業、最深入的 Bootstrap 課程。

立即上課去

概述

下拉選單是可切換的,內文框用於顯示連結列表或其他。這些交互功能於 Bootstrap JavaScript 下拉選單插件提供。透過點擊切換,而不是滑入的方式,這是一個策劃好了的 設計決定

下拉選單是透過第三方插件 Popper.js 所建構的,這提供了動態位置及 viewport 的監控。使用前請確認 popper.min.js 在 Bootstrap’s JavaScript 之前,或者使用 bootstrap.bundle.min.js / bootstrap.bundle.js 這已經包含 Popper.js。

如果你要自行編譯 JS,記得 requires util.js

親和性

WAI ARIA 該標準定義了 role="menu" widget,但這是專門用於應用程式的功能表,它們觸發動作或功能。 ARIA 選單只能包含功能表項目,核取方塊功能表項目,選項按鈕功能表項目,選項按鈕組和子功能表。

Bootstrap 的下拉選單是設計為通用的,適用於各種情況和標記結構。 例如,可以創建包含其他輸入和表單控制項(如搜索欄位或登錄表單)的下拉選單。 因此,Bootstrap 不希望(也不能自動添加)true ARIA 功能表所需的任何 rolearia- 屬性。 作者必須自己加入這些具體屬性。

然而,Bootstrap 為大多數標準鍵盤功能表操作加入內置支援,例如使用游標鍵移動單個 .dropdown-item 元素並使用 ESC 鍵關閉功能表的功能。

範例

.dropdown 中包含下拉選單的切換(你的按鈕或連結)和下拉式功能表,或者另外一個聲明 position:relative; 的元素。 可以從 <a><button> 元素裡觸發下拉選單,以適應您的潛在需求。

單一按鈕的下拉選單

任何單個 .btn 可以變成帶有一些標記的下拉式切換。以下是您如何使用 <button> 元素:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <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 show">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown link
  </a>

  <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <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-haspopup="true" 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 以在下拉插入符號做適當間隔。

我們使用這個額外的 class 將插入符號的兩邊水平 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-haspopup="true" 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-haspopup="true" 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 button
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" 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-haspopup="true" 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 button
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" 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">Dropup</button>
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </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" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

選單物件

在過去下拉選單內容必須是個連接,但 v4 不再是這樣。現在您可以選擇在下拉選單中使用 <button> 元素,而不是僅使用 <a>

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
    <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>

選單對齊

預設情況下,下拉選單自動位於其父級的上方的 100% 及貼齊左邊緣。將 .dropdown-menu-right 加到 .dropdown-menu 中可對齊右方邊緣。

小心! 讚嘆 Popper.js 下拉選單會自動定位 (包含在導覽列的狀況除外)

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    This dropdown's menu is right-aligned
  </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>

選單標題

添加標題來標記下拉選單中的操作部分。

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

選單式表單

在下拉式選單中加入表單,並且使用 margin 或 padding 通用類別 調整所需要的空間。

<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-check">
      <label class="form-check-label">
        <input type="checkbox" class="form-check-input">
        Remember me
      </label>
    </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-check">
    <label class="form-check-label">
      <input type="checkbox" class="form-check-input">
      Remember me
    </label>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

選單中的禁用選項

.disabled 加到下拉選單中的項目,將其設為禁用。

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

用法

通過資料屬性或 JavaScript,下拉選單插件透過切換父級按鈕上 .show 來切換隱藏內容(下拉選單)。 data-toggle="dropdown" 屬性相依於應用程式級別關閉下拉式功能表,因此始終使用它是一個好方法。

在觸控功能的裝置上,打開一個下拉選單會加入 ($.noop) mouseover)給 <body> 元素的直接子元素。這肯定是怪異的手法來 快速解決 iOS 的問題,否則在下拉選單之外的任何地方點擊會無法觸發關閉下拉選單的事件。一旦下拉關閉,這些額外的事件就會被移除。

透過資料屬性

加入 data-toggle="drown" 至連結或按鈕來啟用切換下拉選單。

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

透過 JavaScript

透過 JavaScript 來調用下拉選單:

$('.dropdown-toggle').dropdown()
data-toggle="dropdown" 仍然是必要的

無論是透過 JavaScript 調用您的下拉清單或使用 data-api, data-toggle="dropdown" 都需要在下拉選單的觸發器元素中顯示。

選項

可以透過資料屬性或 JavaScript 插件傳遞選項。對於資料屬性,將選項名稱加到 data- 上,如 data-offset=""

名稱 類型 預設值 描述
offset number | string | function 0 下拉選單相對於其目標的偏移參考 Popper.js 的位移文件
flip boolean true 允許下拉選單重疊到其相關的元素上,更多資訊可參考 Popper.js 的觸發文件.

方法

方法 描述
$().dropdown('toggle') 給予導覽列或分頁導覽使用切換下拉選單功能。
$().dropdown('update') 更新下拉選單元素的定位。
$().dropdown('dispose') 銷毀一個元素的下拉選單。

事件

所有下拉選單事件在 .dropdown-menu 的父元素下觸發,並具有一個 relatedTarget 屬性,其值是切換的錨元素。

事件 描述
show.bs.dropdown 這個事件在調用顯示時被立即觸發。
shown.bs.dropdown 當這個物件可被看見時會觸發此事件(當完成 CSS 轉換後)。
hide.bs.dropdown 這個事件在調用隱藏時被立即觸發。
hidden.bs.dropdown 當這個物件隱藏後會觸發此事件(當完成 CSS 轉換後)。
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})