bootstrap-icons

Bootstrap Icons

Bootstrap Icons 是一个官方开源图标库，包含 2,000 多个图标，专为配合 Bootstrap 组件和文档使用而设计。

当前版本：1.13.x（查看 https://icons.getbootstrap.com 获取最新版本）

安装方式

CDN（最快）

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.min.css" integrity="sha384-CK2SzKma4jA5H/MXDUU7i1TqZlCFaD4T01vtyDFvPlD97JQyS+IsSh1nI2EFbpyk" crossorigin="anonymous">

npm

npm install bootstrap-icons

然后导入：

// In SCSS
@import "bootstrap-icons/font/bootstrap-icons.css";

// In JavaScript
import 'bootstrap-icons/font/bootstrap-icons.css';

下载

从 https://icons.getbootstrap.com 下载，并在本地引入文件。

Composer（PHP）

对于使用 Composer 的 PHP 项目：

composer require twbs/bootstrap-icons

然后从 vendor 目录引用图标：

// Laravel Blade example
<img src="{{ asset('vendor/twbs/bootstrap-icons/icons/heart.svg') }}" alt="Heart">

// Symfony Twig example
<img src="{{ asset('bundles/bootstrap-icons/icons/heart.svg') }}" alt="Heart">

使用方式

图标字体（大多数情况下推荐）

对于大多数项目，图标字体是最简单的方式：

• 语法简单：只需添加 <i class="bi bi-*"></i>
• 自动调整大小：图标会随周围文本缩放
• 继承颜色：图标使用父元素的 color 属性
• 单一依赖：一个 CSS 文件即可提供所有图标

对于高级用例（颜色渐变、动画或离线／电子邮件场景），建议改用 SVG 方式。

<i class="bi bi-alarm"></i>
<i class="bi bi-heart-fill"></i>
<i class="bi bi-check-circle"></i>


<i class="bi bi-alarm" style="font-size: 2rem;"></i>


<i class="bi bi-alarm fs-1"></i>
<i class="bi bi-alarm fs-3"></i>


<i class="bi bi-heart-fill text-danger"></i>
<i class="bi bi-check-circle text-success"></i>
<i class="bi bi-star-fill text-warning"></i>

内嵌 SVG

直接从网站复制 SVG 代码：

<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-heart" viewBox="0 0 16 16">
  <path d="m8 2.748-.717-.737C5.6.281 2.514.878 1.4 3.053c-.523 1.023-.641 2.5.314 4.385.92 1.815 2.834 3.989 6.286 6.357 3.452-2.368 5.365-4.542 6.286-6.357.955-1.886.838-3.362.314-4.385C13.486.878 10.4.28 8.717 2.01L8 2.748zM8 15C-7.333 4.868 3.279-3.04 7.824 1.143c.06.055.119.112.176.171a3.12 3.12 0 0 1 .176-.17C12.72-3.042 23.333 4.867 8 15z"/>
</svg>

内嵌 SVG 的优点：

• 无外部依赖
• 可全面控制 CSS
• 可通过 JavaScript 操作
• currentColor 会继承文本颜色

SVG 雪碧图

引入一次雪碧图，然后引用图标：

<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
  <symbol id="heart" viewBox="0 0 16 16">
    <path d="m8 2.748-.717-.737C5.6.281..."/>
  </symbol>
  <symbol id="star" viewBox="0 0 16 16">
    <path d="M2.866 14.85c-.078.444..."/>
  </symbol>
</svg>


<svg class="bi" width="32" height="32" fill="currentColor">
  <use xlink:href="#heart"/>
</svg>

或者引用外部雪碧图文件：

<svg class="bi" width="32" height="32" fill="currentColor">
  <use xlink:href="bootstrap-icons.svg#heart"/>
</svg>

外部图像

通过 <img> 元素直接引用图标 SVG 文件：

<img src="https://cdn.jsdelivr.net/npm/[email protected]/icons/heart.svg" alt="Heart" width="32" height="32">


<img src="/assets/icons/heart.svg" alt="Heart" width="32" height="32">

适用场景：

• 电子邮件模板（无 CSS／字体依赖）
• 简单的静态页面
• 内容管理系统
• 需要缓存单个图标时

权衡：

• 无法继承文本颜色（如需此功能，请使用 CSS 方式）
• 每个图标都会产生单独的 HTTP 请求（除非使用 HTTP/2）
• 需要显式设置 width/height 属性

CSS 方式

通过 CSS background-image 或 mask 引入图标：

/* Background-image approach (fixed color) */
.icon-heart {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-image: url("https://cdn.jsdelivr.net/npm/[email protected]/icons/heart.svg");
  background-size: contain;
  background-repeat: no-repeat;
}

/* Mask approach (inherits currentColor) */
.icon-heart-mask {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  mask-image: url("https://cdn.jsdelivr.net/npm/[email protected]/icons/heart.svg");
  mask-size: contain;
  mask-repeat: no-repeat;
  -webkit-mask-image: url("https://cdn.jsdelivr.net/npm/[email protected]/icons/heart.svg");
  -webkit-mask-size: contain;
  -webkit-mask-repeat: no-repeat;
}

适用场景：

• 通过 CSS 类应用装饰性图标
• 需要继承文本颜色的图标（使用 mask 方式）
• 避免修改标记

权衡：

• Background-image：无法动态更改颜色
• Mask 方式：Safari 需要厂商前缀（-webkit-mask-*）
• 两种方式：若不添加额外的 ARIA 标记，则无法实现无障碍访问

图标样式

大小

<i class="bi bi-heart" style="font-size: 24px;"></i>
<i class="bi bi-heart" style="font-size: 2rem;"></i>


<i class="bi bi-heart fs-1"></i>  
<i class="bi bi-heart fs-2"></i>  
<i class="bi bi-heart fs-3"></i>  
<i class="bi bi-heart fs-4"></i>  
<i class="bi bi-heart fs-5"></i>  
<i class="bi bi-heart fs-6"></i>  


<style>
  .icon-lg { font-size: 3rem; }
  .icon-md { font-size: 1.5rem; }
  .icon-sm { font-size: 0.875rem; }
</style>
<i class="bi bi-heart icon-lg"></i>


<svg class="bi" width="48" height="48">...</svg>

颜色

<i class="bi bi-heart text-primary"></i>
<i class="bi bi-heart text-danger"></i>
<i class="bi bi-heart text-success"></i>
<i class="bi bi-heart text-warning"></i>
<i class="bi bi-heart text-info"></i>


<i class="bi bi-heart" style="color: #ff6b6b;"></i>


<svg class="bi" fill="#ff6b6b">...</svg>


<div style="color: red;">
  <svg class="bi" fill="currentColor">...</svg>
</div>

垂直对齐

<i class="bi bi-heart" style="vertical-align: middle;"></i>


<i class="bi bi-heart align-middle"></i>


<style>
  .bi {
    vertical-align: -.125em;
  }
</style>

无障碍访问

有含义的图标

当图标传达含义时，请提供无障碍文本：

<button class="btn btn-danger">
  <i class="bi bi-trash" aria-hidden="true"></i>
  <span class="visually-hidden">Delete</span>
</button>


<button class="btn btn-danger" aria-label="Delete">
  <i class="bi bi-trash" aria-hidden="true"></i>
</button>


<i class="bi bi-info-circle" title="More information" role="img" aria-label="More information"></i>

装饰性图标

将纯装饰性图标从屏幕阅读器中隐藏：

<i class="bi bi-star-fill" aria-hidden="true"></i>

带可见文本的图标

当文本可见时，将图标从屏幕阅读器中隐藏：

<button class="btn btn-primary">
  <i class="bi bi-download" aria-hidden="true"></i> Download
</button>

常见模式

带图标的按钮

<button class="btn btn-primary">
  <i class="bi bi-download me-1"></i> Download
</button>


<button class="btn btn-primary">
  Next <i class="bi bi-arrow-right ms-1"></i>
</button>


<button class="btn btn-outline-secondary" aria-label="Settings">
  <i class="bi bi-gear-fill"></i>
</button>

带图标的导航

<ul class="nav nav-pills">
  <li class="nav-item">
    <a class="nav-link active" href="#">
      <i class="bi bi-house-fill me-1"></i> Home
    </a>
  </li>
  <li class="nav-item">
    <a class="nav-link" href="#">
      <i class="bi bi-person me-1"></i> Profile
    </a>
  </li>
</ul>

带图标的列表

<ul class="list-unstyled">
  <li><i class="bi bi-check-circle text-success me-2"></i>Feature one</li>
  <li><i class="bi bi-check-circle text-success me-2"></i>Feature two</li>
  <li><i class="bi bi-x-circle text-danger me-2"></i>Not included</li>
</ul>

社交图标

<div class="d-flex gap-3 fs-4">
  <a href="#" class="text-decoration-none">
    <i class="bi bi-facebook text-primary"></i>
  </a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-twitter-x text-dark"></i>
  </a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-instagram text-danger"></i>
  </a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-linkedin text-primary"></i>
  </a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-github text-dark"></i>
  </a>
</div>

图标徽章

<button class="btn btn-primary position-relative">
  <i class="bi bi-envelope"></i>
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger">
    99+
    <span class="visually-hidden">unread messages</span>
  </span>
</button>

常用图标名称

操作

bi-plus、bi-dash、bi-x、bi-check、bi-pencil、bi-trash、bi-download、bi-upload、bi-search、bi-filter

导航

bi-arrow-left、bi-arrow-right、bi-arrow-up、bi-arrow-down、bi-chevron-left、bi-chevron-right、bi-house、bi-list、bi-grid

UI 元素

bi-bell、bi-gear、bi-sliders、bi-three-dots、bi-three-dots-vertical、bi-person、bi-people、bi-envelope、bi-chat

状态

bi-check-circle、bi-x-circle、bi-exclamation-circle、bi-info-circle、bi-question-circle

文件

bi-file、bi-folder、bi-image、bi-film、bi-music-note、bi-file-pdf、bi-file-word、bi-file-excel

社交

bi-facebook、bi-twitter-x、bi-instagram、bi-linkedin、bi-github、bi-youtube、bi-discord、bi-slack

更多资源

参考文件

• references/icon-categories.md - 按类别整理的完整图标列表（操作、导航、界面元素、状态、文件、媒体、社交、设备、天气、电商、开发）
• references/sass-integration.md - Sass 变量、打包工具配置（Vite、Parcel、Webpack）、与 Bootstrap Sass 集成以及故障排除
• references/rails-integration.md - Rails 8 Propshaft 配置、cssbundling-rails、dartsass-rails、bootstrap-icons gem 以及故障排除

示例文件

• examples/icon-methods-styling-patterns.html - 图标字体、嵌入式 SVG、SVG 雪碧图、尺寸调整、颜色设置和垂直对齐技巧
• examples/icon-ui-accessibility-patterns.html - 按钮、导航、列表、社交图标、徽章和无障碍模式