列表组(List group)
列表组是用于显示一系列内容的灵活而强大的组件。修改和扩展它们可支持其中的任何内容。
基本示例
最基本的列表组是带有列表项和适当类别的无序列表。在此基础上,你可以使用后面的选项,或根据需要使用自己的 CSS。
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul>
活动项目
将 .active
添加到 .list-group-item
,以指示当前的活动选区。
- An active item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group">
<li class="list-group-item active" aria-current="true">An active item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul>
禁用项目
向.list-group-item
添加.disabled
可使其 看起来 禁用。请注意,某些带有.disabled
的元素还需要自定义 JavaScript 才能完全禁用其点击事件(如链接)。
- A disabled item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group">
<li class="list-group-item disabled" aria-disabled="true">A disabled item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul>
链接和按钮
使用 <a>
或 <button>
,通过添加 . list-group-item-action
来创建具有悬停、禁用和激活状态的 actionable 列表组项。我们将这些伪类分开,以确保由非交互式元素(如 <li>
或 <div>
)组成的列表组不会提供点击或轻点功能。
请务必 不要在此处使用标准的 .btn
类 。
<div class="list-group">
<a href="#" class="list-group-item list-group-item-action active" aria-current="true">
The current link item
</a>
<a href="#" class="list-group-item list-group-item-action">A second link item</a>
<a href="#" class="list-group-item list-group-item-action">A third link item</a>
<a href="#" class="list-group-item list-group-item-action">A fourth link item</a>
<a class="list-group-item list-group-item-action disabled" aria-disabled="true">A disabled link item</a>
</div>
使用 <button>
s 时,您还可以使用 disabled
属性而不是 .disabled
类。
With <button>
s, you can also make use of the disabled
attribute instead of the .disabled
class. 遗憾的是,<a>
不支持 disabled 属性。
<div class="list-group">
<button type="button" class="list-group-item list-group-item-action active" aria-current="true">
The current button
</button>
<button type="button" class="list-group-item list-group-item-action">A second button item</button>
<button type="button" class="list-group-item list-group-item-action">A third button item</button>
<button type="button" class="list-group-item list-group-item-action">A fourth button item</button>
<button type="button" class="list-group-item list-group-item-action" disabled>A disabled button item</button>
</div>
刷新(Flush)
添加 .list-group-flush
,以移除某些边框和圆角,从而在父容器(如卡片)中呈现边缘到边缘的列表组项。
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group list-group-flush">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul>
编号
添加.list-group-numbered
修饰符类(可选择使用 <ol>
元素),以选择进入编号列表组项。数字是通过 CSS 生成的(不同于<ol>
默认的浏览器样式),以便更好地放置在列表组项中,并允许更好的自定义。
数字由<ol>
上的counter-reset
生成,然后通过::before
伪元素在<li>
上与counter-increment
和content
一起进行样式设计和放置。
- A list item
- A list item
- A list item
<ol class="list-group list-group-numbered">
<li class="list-group-item">A list item</li>
<li class="list-group-item">A list item</li>
<li class="list-group-item">A list item</li>
</ol>
这些功能对自定义内容也非常有效。
-
SubheadingContent for list item
-
SubheadingContent for list item
-
SubheadingContent for list item
<ol class="list-group list-group-numbered">
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
</ol>
水平列表组
添加 .list-group-horizontal
,可将列表组项在所有断点上的布局从垂直改为水平。或者,选择响应式变体 .list-group-horizontal-{sm|md|lg|xl|xxl}
,使列表组从该断点的 min-width
开始水平布局。目前,水平列表组不能与齐平列表组结合使用。
专业提示: 想要水平方向上的列表组项等宽?在每个列表组项中添加 .flex-fill
。
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
<ul class="list-group list-group-horizontal">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-sm">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-md">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-lg">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xxl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
变体
list-group-item-variant()
Sass mixin 已被弃用。列表组项变量现在可以在 a Sass loop 中重写 CSS 变量。
使用上下文类为列表项设计有状态的背景和颜色。
- A simple default list group item
- A simple primary list group item
- A simple secondary list group item
- A simple success list group item
- A simple danger list group item
- A simple warning list group item
- A simple info list group item
- A simple light list group item
- A simple dark list group item
<ul class="list-group">
<li class="list-group-item">A simple default list group item</li>
<li class="list-group-item list-group-item-primary">A simple primary list group item</li>
<li class="list-group-item list-group-item-secondary">A simple secondary list group item</li>
<li class="list-group-item list-group-item-success">A simple success list group item</li>
<li class="list-group-item list-group-item-danger">A simple danger list group item</li>
<li class="list-group-item list-group-item-warning">A simple warning list group item</li>
<li class="list-group-item list-group-item-info">A simple info list group item</li>
<li class="list-group-item list-group-item-light">A simple light list group item</li>
<li class="list-group-item list-group-item-dark">A simple dark list group item</li>
</ul>
链接和按钮
上下文类还可与 .list-group-item-action
一起用于 <a>
和 <button>
元素。请注意,这里添加了悬停样式,而上一个示例中没有。还支持 .active
状态;应用该状态可在上下文列表组项上显示活动选择。
<div class="list-group">
<a href="#" class="list-group-item list-group-item-action">A simple default list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-primary">A simple primary list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-secondary">A simple secondary list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-success">A simple success list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-danger">A simple danger list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-warning">A simple warning list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-info">A simple info list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-light">A simple light list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-dark">A simple dark list group item</a>
</div>
.visually-hidden
类隐藏的附加文本)明显看出含义。
带徽章
在一些实用工具 的帮助下,为任何列表组项目添加徽章,以显示未读计数、活动等信息。
- A list item 14
- A second list item 2
- A third list item 1
<ul class="list-group">
<li class="list-group-item d-flex justify-content-between align-items-center">
A list item
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-center">
A second list item
<span class="badge text-bg-primary rounded-pill">2</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-center">
A third list item
<span class="badge text-bg-primary rounded-pill">1</span>
</li>
</ul>
自定义内容
借助 flexbox 实用工具,你可以在其中添加几乎任何 HTML 内容,甚至是像下面这样的链接列表组。
List group item heading
3 days agoSome placeholder content in a paragraph.
And some small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.<div class="list-group">
<a href="#" class="list-group-item list-group-item-action active" aria-current="true">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small>3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small>And some small print.</small>
</a>
<a href="#" class="list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small class="text-body-secondary">3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small class="text-body-secondary">And some muted small print.</small>
</a>
<a href="#" class="list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small class="text-body-secondary">3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small class="text-body-secondary">And some muted small print.</small>
</a>
</div>
复选框和单选框
在列表组项中放置 Bootstrap 的复选框和单选框,并根据需要进行自定义。您可以在不使用 <label>
的情况下使用它们,但请记得包含一个 aria-label
属性和值,以便于访问。
<ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="firstCheckbox">
<label class="form-check-label" for="firstCheckbox">First checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="secondCheckbox">
<label class="form-check-label" for="secondCheckbox">Second checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckbox">
<label class="form-check-label" for="thirdCheckbox">Third checkbox</label>
</li>
</ul>
<ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="firstRadio" checked>
<label class="form-check-label" for="firstRadio">First radio</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="secondRadio">
<label class="form-check-label" for="secondRadio">Second radio</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="thirdRadio">
<label class="form-check-label" for="thirdRadio">Third radio</label>
</li>
</ul>
您可以在<label>
上使用.stretched-link
,使整个列表组项目都可以点击。
<ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="firstCheckboxStretched">
<label class="form-check-label stretched-link" for="firstCheckboxStretched">First checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="secondCheckboxStretched">
<label class="form-check-label stretched-link" for="secondCheckboxStretched">Second checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckboxStretched">
<label class="form-check-label stretched-link" for="thirdCheckboxStretched">Third checkbox</label>
</li>
</ul>
CSS
变量
Added in v5.2.0作为 Bootstrap 不断发展的 CSS 变量方法的一部分,列表组现在使用.list-group
上的本地 CSS 变量来增强实时自定义功能。CSS 变量的值通过 Sass 设置,因此仍支持 Sass 自定义。
--#{$prefix}list-group-color: #{$list-group-color};
--#{$prefix}list-group-bg: #{$list-group-bg};
--#{$prefix}list-group-border-color: #{$list-group-border-color};
--#{$prefix}list-group-border-width: #{$list-group-border-width};
--#{$prefix}list-group-border-radius: #{$list-group-border-radius};
--#{$prefix}list-group-item-padding-x: #{$list-group-item-padding-x};
--#{$prefix}list-group-item-padding-y: #{$list-group-item-padding-y};
--#{$prefix}list-group-action-color: #{$list-group-action-color};
--#{$prefix}list-group-action-hover-color: #{$list-group-action-hover-color};
--#{$prefix}list-group-action-hover-bg: #{$list-group-hover-bg};
--#{$prefix}list-group-action-active-color: #{$list-group-action-active-color};
--#{$prefix}list-group-action-active-bg: #{$list-group-action-active-bg};
--#{$prefix}list-group-disabled-color: #{$list-group-disabled-color};
--#{$prefix}list-group-disabled-bg: #{$list-group-disabled-bg};
--#{$prefix}list-group-active-color: #{$list-group-active-color};
--#{$prefix}list-group-active-bg: #{$list-group-active-bg};
--#{$prefix}list-group-active-border-color: #{$list-group-active-border-color};
Sass 变量
$list-group-color: var(--#{$prefix}body-color);
$list-group-bg: var(--#{$prefix}body-bg);
$list-group-border-color: var(--#{$prefix}border-color);
$list-group-border-width: var(--#{$prefix}border-width);
$list-group-border-radius: var(--#{$prefix}border-radius);
$list-group-item-padding-y: $spacer * .5;
$list-group-item-padding-x: $spacer;
// fusv-disable
$list-group-item-bg-scale: -80%; // Deprecated in v5.3.0
$list-group-item-color-scale: 40%; // Deprecated in v5.3.0
// fusv-enable
$list-group-hover-bg: var(--#{$prefix}tertiary-bg);
$list-group-active-color: $component-active-color;
$list-group-active-bg: $component-active-bg;
$list-group-active-border-color: $list-group-active-bg;
$list-group-disabled-color: var(--#{$prefix}secondary-color);
$list-group-disabled-bg: $list-group-bg;
$list-group-action-color: var(--#{$prefix}secondary-color);
$list-group-action-hover-color: var(--#{$prefix}emphasis-color);
$list-group-action-active-color: var(--#{$prefix}body-color);
$list-group-action-active-bg: var(--#{$prefix}secondary-bg);
Sass mixins
Deprecated in v5.3.0@mixin list-group-item-variant($state, $background, $color) {
.list-group-item-#{$state} {
color: $color;
background-color: $background;
&.list-group-item-action {
&:hover,
&:focus {
color: $color;
background-color: shade-color($background, 10%);
}
&.active {
color: $white;
background-color: $color;
border-color: $color;
}
}
}
}
Sass loop 循环
循环,通过覆盖 CSS 变量生成修改器类。
// List group contextual variants
//
// Add modifier classes to change text and background color on individual items.
// Organizationally, this must come after the `:hover` states.
@each $state in map-keys($theme-colors) {
.list-group-item-#{$state} {
--#{$prefix}list-group-color: var(--#{$prefix}#{$state}-text-emphasis);
--#{$prefix}list-group-bg: var(--#{$prefix}#{$state}-bg-subtle);
--#{$prefix}list-group-border-color: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-action-hover-color: var(--#{$prefix}emphasis-color);
--#{$prefix}list-group-action-hover-bg: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-action-active-color: var(--#{$prefix}emphasis-color);
--#{$prefix}list-group-action-active-bg: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-active-color: var(--#{$prefix}#{$state}-bg-subtle);
--#{$prefix}list-group-active-bg: var(--#{$prefix}#{$state}-text-emphasis);
--#{$prefix}list-group-active-border-color: var(--#{$prefix}#{$state}-text-emphasis);
}
}
JavaScript 行为
使用选项卡 JavaScript 插件(单独包含或通过编译后的 bootstrap.js
文件包含)扩展我们的列表组,创建本地内容的选项卡面板。
<div class="row">
<div class="col-4">
<div class="list-group" id="list-tab" role="tablist">
<a class="list-group-item list-group-item-action active" id="list-home-list" data-bs-toggle="list" href="#list-home" role="tab" aria-controls="list-home">Home</a>
<a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="list" href="#list-profile" role="tab" aria-controls="list-profile">Profile</a>
<a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="list" href="#list-messages" role="tab" aria-controls="list-messages">Messages</a>
<a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="list" href="#list-settings" role="tab" aria-controls="list-settings">Settings</a>
</div>
</div>
<div class="col-8">
<div class="tab-content" id="nav-tabContent">
<div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list">...</div>
<div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list">...</div>
<div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list">...</div>
<div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list">...</div>
</div>
</div>
</div>
使用数据属性
只需指定 data-bs-toggle="list"
或在元素上指定 data-bs-toggle="list"
即可激活列表组导航,而无需编写任何 JavaScript。在 .list-group-item
上使用这些数据属性。
<div role="tabpanel">
<!-- List group -->
<div class="list-group" id="myList" role="tablist">
<a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#messages" role="tab">Messages</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#settings" role="tab">Settings</a>
</div>
<!-- Tab panes -->
<div class="tab-content">
<div class="tab-pane active" id="home" role="tabpanel">...</div>
<div class="tab-pane" id="profile" role="tabpanel">...</div>
<div class="tab-pane" id="messages" role="tabpanel">...</div>
<div class="tab-pane" id="settings" role="tabpanel">...</div>
</div>
</div>
通过 JavaScript
通过 JavaScript 启用标签列表项(每个列表项都需要单独激活):
const triggerTabList = document.querySelectorAll('#myTab a')
triggerTabList.forEach(triggerEl => {
const tabTrigger = new bootstrap.Tab(triggerEl)
triggerEl.addEventListener('click', event => {
event.preventDefault()
tabTrigger.show()
})
})
您可以通过多种方式激活单个列表项:
const triggerEl = document.querySelector('#myTab a[href="#profile"]')
bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name
const triggerFirstTabEl = document.querySelector('#myTab li:first-child a')
bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab
渐变效果
要使选项卡面板淡入,请在每个 .tab-pane
中添加 .fade
。第一个选项卡窗格也必须有 .show
,以使初始内容可见。
<div class="tab-content">
<div class="tab-pane fade show active" id="home" role="tabpanel">...</div>
<div class="tab-pane fade" id="profile" role="tabpanel">...</div>
<div class="tab-pane fade" id="messages" role="tabpanel">...</div>
<div class="tab-pane fade" id="settings" role="tabpanel">...</div>
</div>
方法
将内容激活为标签页元素。
例如,您可以使用构造函数创建一个选项卡实例:
const bsTab = new bootstrap.Tab('#myTab')
Method | Description |
---|---|
dispose |
销毁元素的选项卡。 |
getInstance |
静态方法,用于获取与 DOM 元素相关联的选项卡实例: bootstrap.Tab.getInstance(element) 。 |
getOrCreateInstance |
静态方法,用于返回与 DOM 元素相关联的标签实例,或在未初始化的情况下创建一个新的标签实例。您可以这样使用它 bootstrap.Tab.getOrCreateInstance(element) 。 |
show |
选择给定的选项卡并显示其相关窗格。之前选中的任何其他选项卡都会被取消选中,其相关窗格也会被隐藏。在选项卡窗格实际显示之前(即在 shown.bs.tab 事件发生之前)返回调用者。 |
事件
显示新标签页时,事件按以下顺序触发:
hide.bs.tab
(在当前活动标签页上)show.bs.tab
(在待显示选项卡上)hidden.bs.tab
(在前一个活动标签页上,与hide.bs.tab
事件相同)shown.bs.tab
(在新活动的刚显示的选项卡上,与show.bs.tab
事件相同)
如果没有标签页处于活动状态,则 hide.bs.tab
和 hidden.bs.tab
事件不会被触发。
Event type | Description |
---|---|
hide.bs.tab |
当要显示一个新标签页(因此要隐藏之前的活动标签页)时,该事件就会触发。使用 event.target 和 event.relatedTarget 分别定位当前活动标签页和即将活动的新标签页。 |
hidden.bs.tab |
该事件在新标签页显示后触发(因此前一个活动标签页被隐藏)。使用event.target 和event.relatedTarget 可分别针对前一个活动标签页和新的活动标签页。 |
show.bs.tab |
该事件在标签页显示时触发,但在新标签页显示之前。使用event.target 和event.relatedTarget 可分别瞄准活动标签页和上一个活动标签页(如果有)。 |
shown.bs.tab |
此事件在标签页显示后触发。使用event.target 和event.relatedTarget 可分别针对活动标签页和上一个活动标签页(如果有)。 |
const tabElms = document.querySelectorAll('a[data-bs-toggle="list"]')
tabElms.forEach(tabElm => {
tabElm.addEventListener('shown.bs.tab', event => {
event.target // newly activated tab
event.relatedTarget // previous active tab
})
})