跳到主要内容
输入关键词开始搜索，↑ ↓ 选择，Enter 打开
没有找到匹配的文档

列表组

列表组是用于显示一系列内容的灵活且强大的组件。可以对其进行修改和扩展，以支持几乎任何内部内容。

层级：components
查看原文
本页目录

基本示例

最基本的列表组是一个带有列表项和适当类的无序列表。可以根据下面的选项，或根据需要使用你自己的 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 添加到 .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>

使用 <a> 或 <button> 来创建具有悬停、禁用和活动状态的 可操作 列表组项目，方法是添加 .list-group-item-action。我们将这些伪类分开，以确保由非交互元素（如 <li> 或 <div>）组成的列表组不会提供点击或轻触提示。

制造 .list-group-item-action 实例 出现 通过添加禁用 .disabled，和 aria-disabled="true" 通知辅助技术该元素已被禁用。你可能需要额外的 JavaScript 来完全禁用链接和按钮。

请确保不要在这里使用标准的.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 href="#" class="list-group-item list-group-item-action disabled" aria-disabled="true">A disabled link item</a>
</div>

使用<button>时，你也可以使用disabled属性，而不是.disabled类。不幸的是，<a>不支持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> 默认的浏览器样式），以便在列表组项目中更好地放置，并允许更好的自定义。

数字由 counter-reset 在 <ol> 上生成，然后使用 ::before 伪元素在 <li> 上进行样式设置和放置，并带有 counter-increment 和 content。

  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 theme-primary">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 theme-primary">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 theme-primary">14</span>
  </li>
</ol>

水平

添加 .list-group-horizontal 可以将列表组项目的布局从垂直变为在所有容器尺寸下水平。或者，选择响应式变体 .{sm|md|lg|xl|2xl}:list-group-horizontal 以在该断点的宽度开始时将列表组设置为水平。

响应式变体使用 容器查询，因此请将列表组包装在查询容器中——向父元素添加 .contains-inline 工具——以使其生效。目前 水平列表组不能与 flush 列表组结合使用。

专业提示：想要水平时列表组项目等宽吗？在每个列表组项目中添加 .flex-fill。

  • 一件物品
  • 第二项
  • 第三项
  • 一件物品
  • 第二项
  • 第三项
  • 一件物品
  • 第二项
  • 第三项
  • 一件物品
  • 第二项
  • 第三项
  • 一件物品
  • 第二项
  • 第三项
  • 一件物品
  • 第二项
  • 第三项
HTML
<div class="contains-inline">
  <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>
</div>
<div class="contains-inline">
  <ul class="list-group sm: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>
</div>
<div class="contains-inline">
  <ul class="list-group md: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>
</div>
<div class="contains-inline">
  <ul class="list-group lg: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>
</div>
<div class="contains-inline">
  <ul class="list-group xl: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>
</div>
<div class="contains-inline">
  <ul class="list-group 2xl: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>
</div>

拖动手柄以调整下面容器的大小，并观察列表组在容器（而非视口）跨越 md 断点时在垂直和水平布局之间切换。

  • 一件物品
  • 第二项
  • 第三项
HTML
<div class="contains-inline">
  <ul class="list-group md: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>
</div>

变体

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

  • 一个简单的默认列表组项
  • 一个简单的主要列表组项
  • 一个简单的重音列表组项
  • 一个简单的成功列表组项
  • 一个简单的危险清单组项目
  • 一个简单的警告列表组项
  • 一个简单的信息列表组项
  • 一个简单的反向列表组项
  • 一个简单的二级列表组项目
HTML
<ul class="list-group">
  <li class="list-group-item">A simple default list group item</li>
  
  <li class="list-group-item theme-primary">A simple primary list group item</li>
  <li class="list-group-item theme-accent">A simple accent list group item</li>
  <li class="list-group-item theme-success">A simple success list group item</li>
  <li class="list-group-item theme-danger">A simple danger list group item</li>
  <li class="list-group-item theme-warning">A simple warning list group item</li>
  <li class="list-group-item theme-info">A simple info list group item</li>
  <li class="list-group-item theme-inverse">A simple inverse list group item</li>
  <li class="list-group-item theme-secondary">A simple secondary list group item</li>
</ul>

上下文类也适用于.list-group-item-action的<a>和<button>元素。请注意这里添加了悬停样式，而在前一个示例中没有出现。同样支持.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 theme-primary">A simple primary list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-accent">A simple accent list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-success">A simple success list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-danger">A simple danger list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-warning">A simple warning list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-info">A simple info list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-inverse">A simple inverse list group item</a>
  <a href="#" class="list-group-item list-group-item-action theme-secondary">A simple secondary 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 theme-primary">14</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    A second list item
    <span class="badge theme-primary">2</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    A third list item
    <span class="badge theme-primary">1</span>
  </li>
</ul>

自定义内容

几乎可以在其中添加任何 HTML，即使是像下面这样的链接列表组，也可以借助 Flexbox 工具 实现。

列表组项目标题
3天前

段落中的一些占位内容。

以及一些小字。
列表组项目标题
3天前

段落中的一些占位内容。

还有一些小而不显眼的文字。
列表组项目标题
3天前

段落中的一些占位内容。

还有一些小而不显眼的文字。
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="fg-2">3 days ago</small>
    </div>
    <p class="mb-1">Some placeholder content in a paragraph.</p>
    <small class="fg-2">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="fg-2">3 days ago</small>
    </div>
    <p class="mb-1">Some placeholder content in a paragraph.</p>
    <small class="fg-2">And some muted small print.</small>
  </a>
</div>

复选框和单选按钮

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

HTML
<ul class="list-group">
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="firstCheckbox" class="check">
      <label for="firstCheckbox">First checkbox</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="secondCheckbox" class="check">
      <label for="secondCheckbox">Second checkbox</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="thirdCheckbox" class="check">
      <label for="thirdCheckbox">Third checkbox</label>
    </div>
  </li>
</ul>
HTML
<ul class="list-group">
  <li class="list-group-item">
    <div class="form-field">
      <input type="radio" name="listGroupRadio" value="" id="firstRadio" class="radio" checked>
      <label for="firstRadio">First radio</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="radio" name="listGroupRadio" value="" id="secondRadio" class="radio">
      <label for="secondRadio">Second radio</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="radio" name="listGroupRadio" value="" id="thirdRadio" class="radio">
      <label for="thirdRadio">Third radio</label>
    </div>
  </li>
</ul>

你可以使用 .stretched-link 开 <label>使整个列表组项可点击。

HTML
<ul class="list-group">
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="firstCheckboxStretched" class="check">
      <label class="stretched-link" for="firstCheckboxStretched">First checkbox</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="secondCheckboxStretched" class="check">
      <label class="stretched-link" for="secondCheckboxStretched">Second checkbox</label>
    </div>
  </li>
  <li class="list-group-item">
    <div class="form-field">
      <input type="checkbox" value="" id="thirdCheckboxStretched" class="check">
      <label class="stretched-link" for="thirdCheckboxStretched">Third checkbox</label>
    </div>
  </li>
</ul>

CSS

变量

列表组在.list-group上使用本地 CSS 变量进行实时自定义。CSS 变量的值是从每个组件独有的 Sass map生成，并应用于上述类。

scss/_list-group.scss
// stylelint-disable-next-line scss/dollar-variable-default
$list-group-tokens: defaults(
  (
    --list-group-color: var(--fg-body),
    --list-group-bg: var(--bg-body),
    --list-group-border-color: var(--border-color),
    --list-group-border-width: var(--border-width),
    --list-group-border-radius: var(--radius-5),
    --list-group-item-padding-x: var(--spacer),
    --list-group-item-padding-y: var(--spacer-2),
    --list-group-action-color: var(--fg-2),
    --list-group-action-hover-color: var(--fg-1),
    --list-group-action-hover-bg: var(--bg-1),
    --list-group-action-active-color: var(--fg-body),
    --list-group-action-active-bg: var(--bg-2),
    --list-group-disabled-color: var(--fg-3),
    --list-group-disabled-bg: var(--bg-body),
    --list-group-active-color: var(--primary-contrast),
    --list-group-active-bg: var(--primary-bg),
    --list-group-active-border-color: var(--primary-bg),
  ),
  $list-group-tokens
);

JavaScript 行为

使用 标签页插件 创建可切换的列表组面板。