bootstrap_ref_js_dropdown

Bootstrap JS 下拉菜单参考 (Dropdown Reference)

JS 下拉菜单 (dropdown.js)

下拉菜单（Dropdowns）是可切换的、上下文相关的叠加层，用于显示链接列表等内容。它们通过 Bootstrap 的 dropdown JavaScript 插件实现交互，该插件依赖于 Popper.js 进行定位。

有关创建下拉菜单的分步教程，请参考我们的 Bootstrap 下拉菜单教程。

Dropdown 插件类和 HTML 结构

类 / 元素	描述
.dropdown	下拉菜单组件的主要包装器。
.dropdown-toggle	添加到触发下拉菜单的按钮/链接上。
.dropdown-menu	包含下拉菜单项的 <ul> 元素。
.dropdown-item	.dropdown-menu 内部的 <a> 或 <button> 元素的类。
.dropdown-divider	带此类的 <hr> 标签，用于分隔项目组。
.dropdown-header	带此类的 <h6> (通常在 <li> 内部)，用于标记区块标题。
.dropdown-menu-end	将下拉菜单与触发器右侧（末端）对齐。
.dropdown-menu-{breakpoint}-start/end	下拉菜单的响应式对齐。
.dropup, .dropend, .dropstart	添加到 .dropdown 父元素上以改变菜单方向的类。
.disabled	添加到 .dropdown-item 上以禁用它。

通过 Data 属性使用 (Usage via Data Attributes)

通过简单地向链接或按钮添加 data-bs-toggle="dropdown" 来激活下拉菜单，无需编写任何 JavaScript。还建议添加 aria-expanded 属性。

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButtonSimple" data-bs-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <ul class="dropdown-menu" aria-labelledby="dropdownMenuButtonSimple">
    <li><a class="dropdown-item" href="#">Action</a></li>
    <li><a class="dropdown-item" href="#">Another action</a></li>
  </ul>
</div>

通过 JavaScript 使用 (Usage via JavaScript)

你也可以使用 JavaScript 手动初始化下拉菜单：

var dropdownElement = document.getElementById('myDropdownToggle');
var dropdownInstance = new bootstrap.Dropdown(dropdownElement, {
  // optional options object
});

// To initialize all dropdowns on a page:
const dropdownElementList = document.querySelectorAll('.dropdown-toggle');
const dropdownList = [...dropdownElementList].map(dropdownToggleEl => new bootstrap.Dropdown(dropdownToggleEl));

注意：如果通过 JavaScript 初始化，触发元素上通常仍然会为了方便保留 data-bs-toggle="dropdown"，但 JS 构造函数优先级更高。

Dropdown 选项 (Options)

选项可以通过 data 属性或 JavaScript 传递。对于 data 属性，将选项名称附加到 data-bs- 之后，例如 data-bs-offset="[10,20]"。

名称	默认值	Data 属性	描述
offset	[0, 2]	data-bs-offset	下拉菜单相对于其目标的偏移量。可以是字符串，例如 ‘10,20’，或数组 [skidding, distance]。
boundary	’clippingParents’	data-bs-boundary	定义下拉菜单的溢出边界。接受 ‘clippingParents’、‘viewport’ 或 HTMLElement 引用。
reference	’toggle’	data-bs-reference	下拉菜单位置的参照元素。接受 ‘toggle’、‘parent’ 或 HTMLElement 引用。
display	’dynamic’	data-bs-display	默认情况下，我们使用 Popper 进行动态定位。使用 static 可以禁用此功能。
popperConfig	null	data-bs-popper-config	要更改 Bootstrap 默认的 Popper 配置，请参阅 Popper 配置。可以是对象或函数。

Dropdown 方法 (Methods)

Dropdown 方法在下拉菜单实例上调用。

方法 描述 示例

toggle() 切换（显示/隐藏）给定的导航栏或标签式导航的下拉菜单。 myDropdownInstance.toggle()

show() 显示给定的导航栏或标签式导航的下拉菜单。 myDropdownInstance.show()

hide() 隐藏给定的导航栏或标签式导航的下拉菜单。 myDropdownInstance.hide()

update() 更新元素的下拉菜单位置。 myDropdownInstance.update()

dispose() 销毁元素的下拉菜单。（移除 DOM 元素上存储的数据） myDropdownInstance.dispose()

getInstance(element) 静态方法，允许你获取与 DOM 元素关联的下拉菜单实例。 bootstrap.Dropdown.getInstance(myDropdownToggleElement)

getOrCreateInstance(element, config?) 静态方法，允许你获取与 DOM 元素关联的下拉菜单实例；如果尚未初始化，则创建一个新实例。 bootstrap.Dropdown.getOrCreateInstance(myDropdownToggleElement, { offset: [0,10] })

Dropdown 事件 (Events)

Bootstrap 的 dropdown 插件公开了一些事件，用于介入下拉菜单的功能。

事件类型 描述

show.bs.dropdown 此事件在调用 show 实例方法时立即触发。下拉菜单触发元素可通过事件的 relatedTarget 属性访问。

shown.bs.dropdown 此事件在下拉菜单对用户可见后触发（会等待 CSS 过渡完成）。下拉菜单触发元素可通过事件的 relatedTarget 属性访问。

hide.bs.dropdown 此事件在调用 hide 实例方法时立即触发。下拉菜单触发元素可通过事件的 relatedTarget 属性访问。

hidden.bs.dropdown 此事件在下拉菜单对用户隐藏完毕后触发（会等待 CSS 过渡完成）。下拉菜单触发元素可通过事件的 relatedTarget 属性访问。

使用事件的示例：

const myDropdownEl = document.getElementById('someDropdown');
myDropdownEl.addEventListener('shown.bs.dropdown', function (event) {
  // event.relatedTarget is the triggering Toggler element
  console.log('Dropdown shown, triggered by: ', event.relatedTarget.textContent);
  // Do something when the dropdown is shown
});