跳到主要内容 跳到文档导航
Check
in English

列表组

列表组是用于显示一系列内容的灵活而强大的组件。修改和扩展它们以支持其中的任何内容。

基本示例

最基本的列表组是一个包含列表项和适当类的无序列表。使用以下选项或根据需要使用您自己的 CSS 构建它。

  • 一个物品
  • 第二项
  • 第三项
  • 第四项
  • 还有第五个
html
<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到 a.list-group-item以指示当前的活动选择。

  • 一个活跃的项目
  • 第二项
  • 第三项
  • 第四项
  • 还有第五个
html
<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>

残障物品

添加.disabled到 a.list-group-item以使其显示为禁用。请注意,某些元素.disabled还需要自定义 JavaScript 才能完全禁用其点击事件(例如,链接)。

  • 禁用的项目
  • 第二项
  • 第三项
  • 第四项
  • 还有第五个
html
<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>s 或<button>s 通过添加来创建具有悬停、禁用和活动状态的可操作.list-group-item-action列表组项。我们将这些伪类分开,以确保由非交互元素(如<li>s 或<div>s)组成的列表组不会提供点击或点击功能。

一定不要在这里使用标准.btn

html
<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">A disabled link item</a>
</div>

使用<button>s,您还可以使用disabled属性而不是.disabled类。可悲的是,<a>s 不支持 disabled 属性。

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

冲洗

添加.list-group-flush以删除一些边框和圆角以在父容器(例如卡片)中边对边呈现列表组项目。

  • 一个物品
  • 第二项
  • 第三项
  • 第四项
  • 还有第五个
html
<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>s 默认浏览器样式),以便更好地放置在列表组项目中并允许更好的自定义。

数字由counter-reseton生成<ol>,然后在with和上使用::before伪元素设置样式和放置。<li>counter-incrementcontent

  1. 一个列表项
  2. 一个列表项
  3. 一个列表项
html
<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>

这些也适用于自定义内容。

  1. 副标题
    列表项的内容
    14
  2. 副标题
    列表项的内容
    14
  3. 副标题
    列表项的内容
    14
html
<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 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 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 bg-primary rounded-pill">14</span>
  </li>
</ol>

水平的

添加.list-group-horizontal以跨所有断点将列表组项的布局从垂直更改为水平。或者,选择一个响应式变体.list-group-horizontal-{sm|md|lg|xl|xxl}以使列表组水平从该断点的min-width. 目前水平列表组不能与刷新列表组组合。

专业提示:想要水平时等宽列表组项目?添加.flex-fill到每个列表组项目。

  • 一个物品
  • 第二项
  • 第三项
  • 一个物品
  • 第二项
  • 第三项
  • 一个物品
  • 第二项
  • 第三项
  • 一个物品
  • 第二项
  • 第三项
  • 一个物品
  • 第二项
  • 第三项
  • 一个物品
  • 第二项
  • 第三项
html
<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>

上下文类

使用上下文类来设置具有状态背景和颜色的列表项的样式。

  • 一个简单的默认列表组项
  • 一个简单的主要列表组项
  • 一个简单的二级列表组项
  • 一个简单的成功列表组项
  • 一个简单的危险列表组项
  • 一个简单的警告列表组项
  • 一个简单的信息列表组项
  • 一个简单的灯光列表组项
  • 一个简单的黑名单组项
html
<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. 请注意,此处添加的悬停样式在前面的示例中没有出现。还支持.active状态;应用它来指示上下文列表组项上的活动选择。

html
<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类中的附加文本。

带徽章

在某些实用程序的帮助下,将徽章添加到任何列表组项目以显示未读计数、活动等。

  • 一个列表项14
  • 第二个列表项2
  • 第三个列表项1
html
<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    A list item
    <span class="badge 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 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 bg-primary rounded-pill">1</span>
  </li>
</ul>

自定义内容

在flexbox 实用程序的帮助下,几乎可以在其中添加任何 HTML,甚至是像下面这样的链表组。

html
<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-muted">3 days ago</small>
    </div>
    <p class="mb-1">Some placeholder content in a paragraph.</p>
    <small class="text-muted">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-muted">3 days ago</small>
    </div>
    <p class="mb-1">Some placeholder content in a paragraph.</p>
    <small class="text-muted">And some muted small print.</small>
  </a>
</div>

复选框和收音机

将 Bootstrap 的复选框和单选放在列表组项目中,并根据需要进行自定义。您可以在没有<label>s 的情况下使用它们,但请记住包含aria-label可访问性的属性和值。

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

您可以使用.stretched-linkon <label>s 使整个列表组项可单击。

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

变量

在 v5.2.0 中添加

作为 Bootstrap 不断发展的 CSS 变量方法的一部分,列表组现在使用本地 CSS 变量.list-group来增强实时自定义。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:                  $gray-900;
$list-group-bg:                     $white;
$list-group-border-color:           rgba($black, .125);
$list-group-border-width:           $border-width;
$list-group-border-radius:          $border-radius;

$list-group-item-padding-y:         $spacer * .5;
$list-group-item-padding-x:         $spacer;
$list-group-item-bg-scale:          -80%;
$list-group-item-color-scale:       40%;

$list-group-hover-bg:               $gray-100;
$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:         $gray-600;
$list-group-disabled-bg:            $list-group-bg;

$list-group-action-color:           $gray-700;
$list-group-action-hover-color:     $list-group-action-color;

$list-group-action-active-color:    $body-color;
$list-group-action-active-bg:       $gray-200;

混合

与 结合使用$theme-colors以生成s的上下文变体类.list-group-item

@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;
      }
    }
  }
}

环形

list-group-item-variant()使用mixin生成修饰符类的循环。

// 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, $value in $theme-colors {
  $list-group-variant-bg: shift-color($value, $list-group-item-bg-scale);
  $list-group-variant-color: shift-color($value, $list-group-item-color-scale);
  @if (contrast-ratio($list-group-variant-bg, $list-group-variant-color) < $min-contrast-ratio) {
    $list-group-variant-color: mix($value, color-contrast($list-group-variant-bg), abs($list-group-item-color-scale));
  }

  @include list-group-item-variant($state, $list-group-variant-bg, $list-group-variant-color);
}

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>

使用数据属性

您无需编写任何 JavaScript,只需data-bs-toggle="list"在元素上指定或即可激活列表组导航。在 上使用这些数据属性.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

淡化效果

要使选项卡面板淡入,请添加.fade到每个.tab-pane. 第一个选项卡窗格还必须.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>

方法

异步方法和转换

所有 API 方法都是异步的并开始一个转换他们在转换开始但在结束之前立即返回给调用者。此外,过渡组件上的方法调用将被忽略

有关更多信息,请参阅我们的 JavaScript 文档

将您的内容激活为选项卡元素。

您可以使用构造函数创建选项卡实例,例如:

const bsTab = new bootstrap.Tab('#myTab')
方法 描述
dispose 销毁元素的选项卡。
getInstance 允许您获取与 DOM 元素关联的选项卡实例的静态方法,您可以像这样使用它bootstrap.Tab.getInstance(element)
getOrCreateInstance 返回与 DOM 元素关联的选项卡实例或创建一个新的选项卡实例以防它未初始化的静态方法。你可以像这样使用它:bootstrap.Tab.getOrCreateInstance(element).
show 选择给定的选项卡并显示其关联的窗格。之前选择的任何其他选项卡都将被取消选择,并且其关联的窗格被隐藏。在选项卡窗格实际显示之前(即在事件发生之前)返回给调用者。shown.bs.tab

活动

显示新选项卡时,事件按以下顺序触发:

  1. hide.bs.tab(在当前活动选项卡上)
  2. show.bs.tab(在待显示的选项卡上)
  3. hidden.bs.tab(在上一个活动选项卡上,与hide.bs.tab事件相同)
  4. shown.bs.tab(在刚刚显示的新活动选项卡上,与show.bs.tab活动相同)

如果没有选项卡处于活动状态,则不会触发hide.bs.taband事件。hidden.bs.tab

事件类型 描述
hide.bs.tab 此事件在要显示新选项卡时触发(因此要隐藏先前的活动选项卡)。使用event.targetevent.relatedTarget分别定位当前活动选项卡和新的即将活动选项卡。
hidden.bs.tab 此事件在显示新选项卡后触发(因此先前的活动选项卡被隐藏)。使用event.targetevent.relatedTarget分别定位前一个活动选项卡和新活动选项卡。
show.bs.tab 此事件在标签显示时触发,但在新标签显示之前。使用event.targetevent.relatedTarget分别定位活动选项卡和上一个活动选项卡(如果可用)。
shown.bs.tab 显示选项卡后,此事件在选项卡显示时触发。使用event.targetevent.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
  })
})