Bootstrap: 列表组与徽章

Q: 列表组可以嵌套吗？

不支持嵌套。列表组设计为扁平结构。如需层级，考虑用 Bootstrap 的 Accordion 组件或手写嵌套 ul 。

Q: 徽章的圆角怎么控制？

rounded-pill 是胶囊形（两端半圆）， rounded-1/2/3 是不同程度的圆角，不加则默认方角。

Q: 列表组可以做可点击的导航吗？

可以。用 <a> 或 <button> 元素，加 list-group-item-action ，配合 active 表示当前选中项。非常适合侧栏导航。

Q: 列表组的 active 状态在页面刷新后还能保持吗？

不能自动保持。 active 是静态 class，刷新后需要由后端或 JavaScript 根据当前路由动态添加，例如用 window.location 匹配后加 class。

Q: 列表组放在卡片内部和直接使用有什么区别？

卡片内的列表组通常用 list-group-flush 样式，这样列表组会贴合卡片边缘，没有额外边框和圆角，视觉上融为一体。卡片外的列表组有独立边框和圆角。

最后更新：2026-08-26

1. 本课导读

(1) 前置知识

第 10 课：卡片

(2) 🎯 你将学到

使用 list-group 和 list-group-item 构建列表
使用 list-group-item-action 实现可交互列表
使用 badge 徽章显示计数和状态
自定义列表组内容（Flex + 排版）
使用 list-group-flush 去除边框

(3) 痛点

Charlie 正在做一个工单管理系统，需要在侧栏显示"待处理(5)"、"进行中(3)"、"已完成(12)"——这恰好是列表组 + 徽章的经典组合。

(4) 解法

列表组和徽章是 Bootstrap 中轻量但实用的展示组件。列表组用于呈现一组相关条目，徽章用于在角落显示计数或状态。

(5) 收益

使用列表组配合徽章，可以清晰直观地展示分类通知计数，极大提升信息获取效率。

2. 列表组基础

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

▶ 试一试

▶ 示例：列表组基础

HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>List Group Demo</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
  <div class="container py-4">
    <div class="row">
      <div class="col-md-4">
        <h5>Basic List</h5>
        <ul class="list-group">
          <li class="list-group-item">Dashboard</li>
          <li class="list-group-item">Orders</li>
          <li class="list-group-item">Products</li>
          <li class="list-group-item">Customers</li>
        </ul>
      </div>

      <div class="col-md-4">
        <h5>Active & Disabled</h5>
        <div class="list-group">
          <a href="#" class="list-group-item list-group-item-action active">Home</a>
          <a href="#" class="list-group-item list-group-item-action">Profile</a>
          <a href="#" class="list-group-item list-group-item-action disabled">Settings (locked)</a>
        </div>
      </div>

      <div class="col-md-4">
        <h5>Flush Style</h5>
        <ul class="list-group list-group-flush">
          <li class="list-group-item">Inbox <span class="badge bg-primary rounded-pill">3</span></li>
          <li class="list-group-item">Sent</li>
          <li class="list-group-item">Drafts <span class="badge bg-warning">2</span></li>
        </ul>
      </div>
    </div>
  </div>
</body>
</html>

▶ 试一试

3. 列表组变体

(1) 可交互列表组

HTML

<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action active">Active link</a>
  <a href="#" class="list-group-item list-group-item-action">Regular link</a>
  <button class="list-group-item list-group-item-action">Button as item</button>
</div>

▶ 试一试

(2) 颜色变体

HTML

<ul class="list-group">
  <li class="list-group-item list-group-item-primary">Primary item</li>
  <li class="list-group-item list-group-item-success">Success item</li>
  <li class="list-group-item list-group-item-danger">Danger item</li>
</ul>

▶ 试一试

class	背景色	语义
`list-group-item-primary`	浅蓝	信息
`list-group-item-success`	浅绿	成功
`list-group-item-danger`	浅红	错误
`list-group-item-warning`	浅黄	警告

(3) 带徽章的列表组

HTML

<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Notifications
    <span class="badge bg-primary rounded-pill">14</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Messages
    <span class="badge bg-danger rounded-pill">3</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Updates
    <span class="badge bg-success rounded-pill">7</span>
  </li>
</ul>

▶ 试一试

4. 自定义列表组内容

HTML

<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action">
    <div class="d-flex w-100 justify-content-between">
      <h5 class="mb-1">New update released</h5>
      <small class="text-body-secondary">3 days ago</small>
    </div>
    <p class="mb-1">Version 2.4 includes bug fixes and performance improvements.</p>
    <small class="text-body-secondary">By Alice Chen</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">Server maintenance</h5>
      <small class="text-body-secondary">1 week ago</small>
    </div>
    <p class="mb-1">Scheduled downtime on Saturday 2:00 AM - 4:00 AM UTC.</p>
    <small class="text-body-secondary">By Bob Wang</small>
  </a>
</div>

▶ 试一试

5. 徽章

HTML

<h1>Example heading <span class="badge bg-secondary">New</span></h1>

<button class="btn btn-primary position-relative">
  Inbox
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger">
    99+
  </span>
</button>

<span class="badge rounded-pill bg-primary">Primary</span>
<span class="badge rounded-pill bg-warning">Warning</span>

<span class="badge bg-primary">Primary</span>
<span class="badge bg-success">Success</span>
<span class="badge bg-danger">Danger</span>
<span class="badge bg-warning">Warning</span>
<span class="badge bg-info">Info</span>
<span class="badge bg-dark">Dark</span>

▶ 试一试

(1) 徽章颜色语义

class	用途
`bg-primary`	默认标签
`bg-success`	已完成/通过
`bg-danger`	错误/失败数量
`bg-warning`	待处理/需要注意
`bg-info`	信息性标签
`bg-secondary`	次要/中性标签

6. 更多列表组示例

▶ 示例：标签式列表组导航

HTML

<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">Home</a>
      <a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="list" href="#list-profile" role="tab">Profile</a>
      <a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="list" href="#list-messages" role="tab">Messages</a>
      <a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="list" href="#list-settings" role="tab">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">Home content: welcome to the dashboard.</div>
      <div class="tab-pane fade" id="list-profile" role="tabpanel">Profile content: manage your personal info.</div>
      <div class="tab-pane fade" id="list-messages" role="tabpanel">Messages content: view your inbox.</div>
      <div class="tab-pane fade" id="list-settings" role="tabpanel">Settings content: configure preferences.</div>
    </div>
  </div>
</div>

▶ 试一试

▶ 示例：复杂列表（徽章 + 图标）

HTML

<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center">
    <div class="me-3 fs-5">📧</div>
    <div class="flex-grow-1">
      <div class="d-flex w-100 justify-content-between">
        <h6 class="mb-0">New message from Alice</h6>
        <small class="text-body-secondary">2 min ago</small>
      </div>
      <small class="text-body-secondary">Meeting rescheduled to 3pm.</small>
    </div>
    <span class="badge bg-danger rounded-pill ms-2">3</span>
  </a>
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center">
    <div class="me-3 fs-5">🔔</div>
    <div class="flex-grow-1">
      <div class="d-flex w-100 justify-content-between">
        <h6 class="mb-0">Server alert</h6>
        <small class="text-body-secondary">1 hr ago</small>
      </div>
      <small class="text-body-secondary">CPU usage exceeded 90%.</small>
    </div>
    <span class="badge bg-warning rounded-pill ms-2">5</span>
  </a>
  <a href="#" class="list-group-item list-group-item-action d-flex align-items-center">
    <div class="me-3 fs-5">✅</div>
    <div class="flex-grow-1">
      <div class="d-flex w-100 justify-content-between">
        <h6 class="mb-0">Deployment complete</h6>
        <small class="text-body-secondary">3 hr ago</small>
      </div>
      <small class="text-body-secondary">Version 2.4 deployed to production.</small>
    </div>
    <span class="badge bg-success rounded-pill ms-2">12</span>
  </a>
</div>

▶ 试一试

▶ 示例：复选框列表组

HTML

<div class="list-group">
  <label class="list-group-item d-flex align-items-center">
    <input class="form-check-input me-2" type="checkbox" value="" checked>
    HTML & CSS Basics
  </label>
  <label class="list-group-item d-flex align-items-center">
    <input class="form-check-input me-2" type="checkbox" value="">
    JavaScript Fundamentals
  </label>
  <label class="list-group-item d-flex align-items-center">
    <input class="form-check-input me-2" type="checkbox" value="" checked>
    Bootstrap 5 Framework
  </label>
  <label class="list-group-item d-flex align-items-center">
    <input class="form-check-input me-2" type="checkbox" value="">
    React & Vue.js
  </label>
  <label class="list-group-item d-flex align-items-center disabled">
    <input class="form-check-input me-2" type="checkbox" value="" disabled>
    Advanced Node.js (locked)
  </label>
</div>

▶ 试一试

▶ 示例：自定义颜色列表组

HTML

<div class="list-group">
  <button type="button" class="list-group-item list-group-item-action list-group-item-success d-flex justify-content-between align-items-center">
    <span>✅ Task completed</span>
    <span class="badge bg-success rounded-pill">12</span>
  </button>
  <button type="button" class="list-group-item list-group-item-action list-group-item-warning d-flex justify-content-between align-items-center">
    <span>⏳ In progress</span>
    <span class="badge bg-warning rounded-pill">5</span>
  </button>
  <button type="button" class="list-group-item list-group-item-action list-group-item-danger d-flex justify-content-between align-items-center">
    <span>❌ Overdue</span>
    <span class="badge bg-danger rounded-pill">3</span>
  </button>
  <button type="button" class="list-group-item list-group-item-action list-group-item-info d-flex justify-content-between align-items-center">
    <span>ℹ️ New updates</span>
    <span class="badge bg-info rounded-pill">8</span>
  </button>
</div>

▶ 试一试

(1) 列表组组件树

flowchart TD
    A[list-group 容器] --> B[list-group-item 列表项]
    B --> C[list-group-item-action<br/>可交互]
    B --> D[list-group-item-primary<br/>颜色变体]
    B --> E[badge 徽章]
    A --> F[list-group-flush<br/>去边框]
    A --> G[自定义内容<br/>Flex + 排版]

列表组变体	class	用途
基础列表	`list-group` + `list-group-item`	简单条目展示
可交互	`list-group-item-action`	导航、菜单
无边框	`list-group-flush`	卡片内部、紧凑场景
颜色行	`list-group-item-{color}`	状态分类
数字徽章	`badge rounded-pill`	计数、通知数量
复选/单选	`form-check-input` + `list-group-item`	任务列表、多选

徽章颜色	语义	适用场景
`bg-primary`	默认/信息	常规计数
`bg-success`	成功/完成	已完成任务、通过
`bg-danger`	错误/紧急	失败数、警报数
`bg-warning`	待处理	进行中、待审批
`bg-info`	提示	新通知、新消息
`bg-secondary`	次要	辅助计数

导航方案	优点	缺点	最佳场景
列表组导航	样式丰富、支持徽章	不支持嵌套	侧栏菜单、标签页
Nav nav-tabs	原生标签风格、支持下拉	无徽章支撑	页面内标签切换
Navbar nav	响应式、品牌整合	结构复杂	顶部主导航
Dropdown	紧凑、节省空间	仅显示当前项	用户菜单、设置

❓ 常见问题

Q 列表组可以嵌套吗？

A 不支持嵌套。列表组设计为扁平结构。如需层级，考虑用 Bootstrap 的 Accordion 组件或手写嵌套 ul。

Q 徽章的圆角怎么控制？

A rounded-pill 是胶囊形（两端半圆），rounded-1/2/3 是不同程度的圆角，不加则默认方角。

Q 列表组可以做可点击的导航吗？

A 可以。用 <a> 或 <button> 元素，加 list-group-item-action，配合 active 表示当前选中项。非常适合侧栏导航。

Q 列表组的 active 状态在页面刷新后还能保持吗？

A 不能自动保持。active 是静态 class，刷新后需要由后端或 JavaScript 根据当前路由动态添加，例如用 window.location 匹配后加 class。

Q 列表组放在卡片内部和直接使用有什么区别？

A 卡片内的列表组通常用 list-group-flush 样式，这样列表组会贴合卡片边缘，没有额外边框和圆角，视觉上融为一体。卡片外的列表组有独立边框和圆角。

📖 小节

列表组：list-group + list-group-item，list-group-item-action 启用交互
list-group-flush 去边框，list-group-item-{color} 颜色变体
自定义内容：在 list-group-item 内使用 Flexbox 和排版 class
徽章：badge bg-{color}，rounded-pill 胶囊形

📝 作业

⭐ 创建一个侧栏导航列表组：5 个菜单项，当前页高亮为 active，其中一个设为 disabled，每个项右侧显示对应的数字徽章。
⭐⭐ 用列表组 + 自定义内容做一个通知列表：每条通知有标题、时间（small）、正文预览，支持点击。
⭐⭐⭐ 创建一个按钮组，每个按钮右上方显示一个徽章计数，模拟"收件箱(12)"、"待审批(5)"、"草稿(3)"。

上一课： 卡片 · 下一课： 表格

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

Bootstrap: 列表组与徽章

1. 本课导读

(1) 前置知识

(2) 🎯 你将学到

(3) 痛点

(4) 解法

(5) 收益

2. 列表组基础

▶ 示例：列表组基础

3. 列表组变体

(1) 可交互列表组

(2) 颜色变体

(3) 带徽章的列表组

4. 自定义列表组内容

5. 徽章

(1) 徽章颜色语义

6. 更多列表组示例

▶ 示例：标签式列表组导航

▶ 示例：复杂列表（徽章 + 图标）

▶ 示例：复选框列表组

▶ 示例：自定义颜色列表组

(1) 列表组组件树

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好