in English

下拉菜單

使用 Bootstrap 下拉插件切換上下文覆蓋以顯示鏈接列表等。

概述

下拉菜單是可切換的上下文覆蓋,用於顯示鏈接列表等。它們與包含的 Bootstrap 下拉 JavaScript 插件交互。它們是通過單擊而不是懸停來切換的;這是一個有意的設計決定

下拉菜單基於第三方庫Popper構建,該庫提供動態定位和視口檢測。請務必在 Bootstrap 的 JavaScript 之前包含popper.min.jsbootstrap.bundle.min.js或使用/bootstrap.bundle.js其中包含 Popper。儘管不需要動態定位,但 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>s。

<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到下拉列表中的項目以將它們設置為 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到下拉列表中的項目以將它們設置為 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-right.dropdown-menu右對齊下拉菜單。

小心!下拉菜單的位置要歸功於 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 protected]">
    </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 protected]">
  </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-offsetdata-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,下拉插件通過切換.showparent 上的類來切換隱藏內容(下拉菜單) .dropdown-menu。該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="".

姓名 類型 默認 描述
抵消 號碼 | 字符串 | 功能 0

下拉菜單相對於其目標的偏移量。

當使用函數確定偏移量時,會使用包含偏移量數據的對像作為其第一個參數來調用它。該函數必須返回具有相同結構的對象。觸發元素 DOM 節點作為第二個參數傳遞。

有關更多信息,請參閱 Popper 的偏移量文檔

翻動 布爾值 真的 允許下拉菜單在參考元素重疊的情況下翻轉。有關更多信息,請參閱 Popper 的翻轉文檔
邊界 字符串 | 元素 '滾動父' 下拉菜單的溢出約束邊界。接受 、 、 或 HTMLElement 引用的值'viewport''window'僅限'scrollParent'JavaScript)。有關更多信息,請參閱 Popper 的preventOverflow 文檔
參考 字符串 | 元素 '切換' 下拉菜單的引用元素。接受 、 或 HTMLElement 引用的'toggle''parent'。有關詳細信息,請參閱 Popper 的referenceObject 文檔
展示 細繩 '動態的' 默認情況下,我們使用 Popper 進行動態定位。用 禁用它static
popperConfig 空 | 目的 無效的 要更改 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.dropdownevents 有一個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...
})