下拉菜单(Dropdowns)

使用Bootstrap下拉插件切换上下文叠加层以显示链接列表以及更多内容。

概览

下拉菜单是可切换的上下文叠加层,用于显示链接列表等。 它们通过随附的Bootstrap下拉JavaScript插件进行了交互。 它们是通过单击而不是悬停来切换的; 这是an intentional design decision.

下拉列表基于第三方库Popper.js构建,该库提供动态定位和视口检测。 确保在Bootstrap的JavaScript之前包含popper.min.js 或使用包含Popper.js的bootstrap.bundle.min.js /bootstrap.bundle.js。 尽管不需要动态定位,但Popper.js并不用于在导航栏中定位下拉列表。

如果您是从源代码构建JavaScript,则它requires util.js.

辅助功能(Accessibility)

WAI ARIA 标准定义了一个实际的 role="menu" widget,但这特定于触发操作的类似于应用程序的菜单 或功能。 <abbr title =“可访问的Rich Internet Applications”> ARIA </ abbr>菜单只能包含菜单项,复选框菜单项,单选按钮菜单项,单选按钮组和子菜单。

另一方面,Bootstrap的下拉菜单被设计为通用的,适用于各种情况和标记结构。 例如,可以创建包含其他输入和表单控件(例如搜索字段或登录表单)的下拉菜单。 因此,Bootstrap不会期望(也不自动添加)真正的<abbr title =“ Accessible Rich Internet Applications”> ARIA </ abbr>菜单所需的rolearia-属性。 作者必须自己包括这些更具体的属性。

但是,Bootstrap确实为大多数标准键盘菜单交互添加了内置支持,例如能够使用光标键在各个.dropdown-item元素中移动并使用 ESC </ kbd>键关闭菜单的功能。

例子

将下拉菜单的切换开关(您的按钮或链接)和下拉菜单包装在.dropdown中,或者包装另一个声明position:relative;的元素中。 可以从

单按钮

任何单个“ .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">
  <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’以便在下拉插入符周围保持适当的间距。

我们使用此额外的类将插入符号两侧的水平“填充”减少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>

尺寸(Sizing)

按钮下拉菜单可用于所有大小的按钮,包括默认和拆分下拉按钮。

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

方向(Directions)

放弃(Dropup)

通过将.dropup添加到父元素来触发元素上方的下拉菜单。

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

右落(Dropright)

通过在父元素上添加.dropright来触发元素右侧的下拉菜单。

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

左落(Dropleft)

通过将.dropleft添加到父元素来触发元素左侧的下拉菜单。

<!-- Default dropleft button -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" 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" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" 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" 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>

您也可以使用.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以将样式设为[disabled]。

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled" href="#" tabindex="-1" aria-disabled="true">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</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">
    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-haspopup="true" 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-haspopup="true" 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>

请注意,由于导航栏中未使用Popper.js,因此您无需向导航栏中的下拉按钮添加data-display =“ static”属性。

菜单内容

Headers

在任何下拉菜单中添加标题以标记动作部分。

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

分频器(Dividers)

用分隔符将相关菜单项的组分开。

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

文本(Text)

将任意格式的文本放在带有文本的下拉菜单中,然后使用spacing utilities。 请注意,您可能需要其他调整样式来限制菜单宽度。

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

表单(Forms)

将表单放在下拉菜单中,或放入下拉菜单,然后使用margin or padding utilities 给出 它是您需要的负空间。

<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-offsetdata-reference来更改下拉菜单的位置。

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-offset="10,20">
      Offset
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
      <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" id="dropdownMenuReference" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
      <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,下拉插件通过在父列表项上切换.show类来切换隐藏内容(下拉菜单)。 依靠data-toggle =“ dropdown”属性在应用程序级别关闭下拉菜单,因此始终使用它是一个好主意。

On touch-enabled devices, opening a dropdown adds empty ($.noop) mouseover handlers to the immediate children of the <body> element. This admittedly ugly hack is necessary to work around a quirk in iOS’ event delegation, which would otherwise prevent a tap anywhere outside of the dropdown from triggering the code that closes the dropdown. Once the dropdown is closed, these additional empty mouseover handlers are removed.

通过数据属性

data-toggle =“ dropdown”添加到链接或按钮以切换下拉菜单。

<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,始终需要在下拉菜单的Trigger元素上出现“ data-toggle =“ dropdown”`。

选项(Options)

可以通过数据属性或JavaScript传递选项。 对于数据属性,将选项名称附加到data-中,如`data-offset =“”中所示。

Name Type Default Description
offset number | string | function 0

Offset of the dropdown relative to its target.

When a function is used to determine the offset, it is called with an object containing the offset data as its first argument. The function must return an object with the same structure. The triggering element DOM node is passed as the second argument.

For more information refer to Popper.js's offset docs.

flip boolean true Allow Dropdown to flip in case of an overlapping on the reference element. For more information refer to Popper.js's flip docs.
boundary string | element 'scrollParent' Overflow constraint boundary of the dropdown menu. Accepts the values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs.
reference string | element 'toggle' Reference element of the dropdown menu. Accepts the values of 'toggle', 'parent', or an HTMLElement reference. For more information refer to Popper.js's referenceObject docs.
display string 'dynamic' By default, we use Popper.js for dynamic positioning. Disable this with static.
popperConfig null | object null To change Bootstrap's default Popper.js config, see Popper.js's configuration

注意,当“ boundary”设置为“ scrollParent”以外的任何值时,样式“ position:static”将应用于.dropdown容器。

方法

方法 描述
$().dropdown('toggle') Toggles the dropdown menu of a given navbar or tabbed navigation.
$().dropdown('show') Shows the dropdown menu of a given navbar or tabbed navigation.
$().dropdown('hide') Hides the dropdown menu of a given navbar or tabbed navigation.
$().dropdown('update') Updates the position of an element’s dropdown.
$().dropdown('dispose') Destroys an element’s dropdown.

事件(Events)

所有下拉事件都在.dropdown-menu的父元素处触发,并具有relatedTarget属性,其值是切换锚元素。 “ hide.bs.dropdown”和“ hidden.bs.dropdown”事件具有“ clickEvent”属性(仅当原始事件类型为“ click”时),该属性包含click事件的事件对象。

事件 描述
show.bs.dropdown This event fires immediately when the show instance method is called.
shown.bs.dropdown This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete).
hide.bs.dropdown This event is fired immediately when the hide instance method has been called.
hidden.bs.dropdown This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete).
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something...
})