1. 为什么进度条和滚动监控值得单独拎出来讲
Bootstrap 用久了会发现一个现象：栅格、按钮、表单这些组件大家都很熟，但进度条和滚动监控这两个组件，很多人只是“见过”，真到项目里要用的时候，往往还是自己手写。原因不复杂——进度条看起来太简单，滚动监控又容易被忽略。但恰恰是这两个组件，在后台系统、内容型网站、数据看板里出现的频率极高，而且用好了能省掉大量重复代码。
这篇内容围绕 Bootstrap 的进度条（Progress）和滚动监控（Scrollspy）两个组件展开。进度条解决的是“让用户知道当前进行到哪一步”的问题，滚动监控解决的是“让用户知道当前在看哪一块内容”的问题。一个偏状态反馈，一个偏导航联动。两者都属于那种“不用也能跑，用了体验明显不一样”的组件。
适合谁看？如果你已经写过一些 Bootstrap 页面，能看懂基础的 class 命名逻辑，但还没系统用过这两个组件，那这篇正好。如果你是完全的新手，也没关系，我会把每个 class 的作用、参数的计算过程、以及实际踩过的坑都讲清楚。下面所有示例基于 Bootstrap 5.x 的写法，4.x 的差异我会在关键位置标注出来。
我个人的习惯是：进度条不要只当成一个“加载动画”，它其实是一套状态表达系统；滚动监控也不要只当成“导航高亮”，它本质上是页面结构和导航结构之间的一次约定。理解了这个定位，用起来就不会跑偏。
2. 进度条组件：从一条横杠到一套状态表达
2.1 进度条的基本结构和最小可用写法
Bootstrap 进度条的核心结构只有两层：外层是.progress容器，内层是.progress-bar填充条。最小写法长这样：
<div class="progress"> <div class="progress-bar" style="width: 60%"></div> </div>这里有一个很多人第一次用会困惑的点：为什么宽度要写在行内 style 上？因为进度条的宽度是动态的，Bootstrap 没法预设一个固定值。.progress负责的是外框的样式——高度、背景色、圆角、溢出隐藏；.progress-bar负责的是填充部分的过渡动画和背景色。宽度必须由你自己根据实际进度来给。
那为什么不用width属性而用style？因为width属性在div上不生效，div不是替换元素。所以只能用 CSS 的width。这一点看起来是常识，但我见过不少人在div上写width="60%"，然后纳闷为什么没反应。
.progress默认高度是 1rem（16px），这个高度在后台系统里偏矮，在数据看板里又偏细。我一般会根据场景调整，后面会讲怎么改。
2.2 高度、颜色、条纹、动画：四个维度的定制
进度条的可定制维度其实就四个：高度、颜色、条纹、动画。把这四个吃透，基本就够用了。
高度通过给.progress加自定义样式或者用 Bootstrap 的尺寸类来控制。Bootstrap 5 没有直接提供进度条的高度类，所以要么写行内 style，要么在 CSS 里定义：
<div class="progress" style="height: 20px;"> <div class="progress-bar" style="width: 45%"></div> </div>这里有个细节：高度改了之后，如果进度条里有文字，文字会垂直居中，但字号不会自动变。高度超过 24px 的时候，建议手动调一下font-size，否则文字会显得很小。
颜色用.bg-*系列类，比如.bg-success、.bg-info、.bg-warning、.bg-danger。默认是.bg-primary的蓝色。颜色在进度条里的语义很重要——绿色表示完成或正常，黄色表示警告，红色表示异常或失败。我见过有人所有进度条都用蓝色，结果用户根本分不清哪个是正常的、哪个是出问题的。
条纹用.progress-bar-striped，动画在条纹基础上加.progress-bar-animated：
<div class="progress"> <div class="progress-bar progress-bar-striped progress-bar-animated" style="width: 70%"></div> </div>条纹动画的原理是 CSS 的background-image加animation，通过移动背景位置产生流动效果。这里要注意：动画会持续消耗 GPU 资源。如果一个页面里有十几个带动画的进度条，低端设备上会明显卡顿。我的做法是只在“进行中”的进度条上加动画，一旦完成就移除.progress-bar-animated。
2.3 多段进度条：一个容器里塞多条
多段进度条是很多人不知道但非常实用的功能。比如一个任务分三个阶段，每个阶段占比不同，就可以在一个.progress里放多个.progress-bar：
<div class="progress"> <div class="progress-bar bg-success" style="width: 35%">完成</div> <div class="progress-bar bg-warning" style="width: 25%">进行中</div> <div class="progress-bar bg-danger" style="width: 15%">异常</div> </div>这里的关键是：所有.progress-bar的宽度加起来不要超过 100%。超过的部分会被.progress的overflow: hidden裁掉，看起来就像“进度条爆了”。我一般会留 5% 到 10% 的余量，避免因为四舍五入导致最后一段被裁。
多段进度条最适合的场景是“任务状态分布”——比如一个批处理任务里，成功多少、失败多少、待处理多少。用一条进度条就能表达清楚，比三个独立的进度条直观得多。
2.4 带标签的进度条：文字放里面还是放外面
进度条上的文字有两种放法：放在.progress-bar内部，或者放在.progress外部。
放内部：
<div class="progress"> <div class="progress-bar" style="width: 60%">60%</div> </div>放外部：
<div class="progress"> <div class="progress-bar" style="width: 60%"></div> </div> <span>60%</span>放内部的问题是：当进度条宽度很小时（比如 5%），文字会被挤出去或者被裁掉。放外部的问题是：文字和进度条的对齐关系需要额外处理。
我的经验是：进度大于 30% 时放内部，小于 30% 时放外部。或者干脆统一放外部，用 flex 布局让文字和进度条在同一行。这样最稳，不会因为进度变化导致文字位置跳动。
2.5 动态更新进度：JS 控制的核心逻辑
进度条真正在项目里用起来，一定是动态的。核心逻辑就一句：拿到进度百分比，设置.progress-bar的style.width。
function setProgress(percent) { const bar = document.querySelector('.progress-bar'); const clamped = Math.min(100, Math.max(0, percent)); bar.style.width = clamped + '%'; bar.setAttribute('aria-valuenow', clamped); }这里有两个细节值得说。第一是clamp：进度值必须限制在 0 到 100 之间。我见过因为后端返回了 105 或者 -3，导致进度条直接溢出或者消失的情况。第二是aria-valuenow：这是无障碍属性，屏幕阅读器会读这个值。很多人只改宽度不改这个属性，结果无障碍体验很差。
如果是文件上传这种场景，进度值来自XMLHttpRequest的progress事件：
xhr.upload.addEventListener('progress', (e) => { if (e.lengthComputable) { const percent = (e.loaded / e.total) * 100; setProgress(percent); } });e.lengthComputable这个判断不能省。有些服务器不返回Content-Length，这时候e.total是 0，除出来是Infinity，进度条会直接跳到 100% 或者报错。
2.6 进度条实操中的几个坑
坑一：宽度过渡动画和实际进度更新冲突。.progress-bar默认有transition: width .6s ease。如果你的进度更新频率很高（比如每 100ms 一次），过渡动画会一直被打断，看起来反而卡顿。解决办法是高频更新时把transition关掉，或者降低更新频率。
坑二：进度条在 flex 容器里宽度异常。如果.progress的父元素是 flex 容器，.progress可能会被压缩。这时候给.progress加flex: 1或者width: 100%。
坑三：条纹动画在 Safari 上的性能问题。老版本 Safari 对background-position动画的优化不好，条纹动画会掉帧。如果目标用户里有较多 Safari，建议用 CSStransform自己实现流动效果，或者干脆不用动画。
坑四：进度条颜色和背景对比度不足。.bg-warning是黄色，在白色背景上对比度很低，文字几乎看不清。用黄色进度条时，文字建议用深色，或者干脆不放文字。
3. 滚动监控组件：让导航跟着页面走
3.1 滚动监控到底在监控什么
滚动监控（Scrollspy）的作用一句话说清楚：当页面滚动到某个区域时，自动高亮对应的导航项。它监控的是“当前视口里显示的是哪一块内容”，然后把结果反映到导航上。
这个组件最适合的场景是单页文档或者长页面导航。比如一个产品介绍页，分成“功能”“价格”“案例”“FAQ”几个区块，右侧或顶部有一个导航，用户滚动到哪个区块，导航就高亮哪一项。没有这个组件，用户就得自己判断“我现在看到的是第几部分”，体验差很多。
Bootstrap 5 的滚动监控和 4.x 有一个重要区别：5.x 移除了对 jQuery 的依赖，改用原生 JS 的IntersectionObserver或者滚动事件。这意味着初始化方式变了，但 HTML 结构基本一致。
3.2 滚动监控的 HTML 结构约定
滚动监控对 HTML 结构有明确要求，不是随便写就能生效的。核心约定有三条：
第一，导航容器要有一个id，并且加上.nav或.list-group之类的类。这个id会在初始化时用到。
第二，导航链接的href必须指向对应区块的id，格式是#区块id。
第三，被监控的区块必须有id，而且这个id要和导航链接的href对应。
一个典型结构：
<nav id="pageNav" class="nav flex-column"> <a class="nav-link" href="#section1">第一部分</a> <a class="nav-link" href="#section2">第二部分</a> <a class="nav-link" href="#section3">第三部分</a> </nav> <div>// 如果导航栏高度是动态的，可以这样算 const navHeight = document.querySelector('.navbar').offsetHeight; const spyElement = document.querySelector('[data-bs-spy="scroll"]'); spyElement.setAttribute('data-bs-offset', navHeight + 16);这里有个坑：如果页面里同时有多个固定元素（比如顶部导航 + 侧边栏），偏移量要按最高的那个算，或者用 JS 动态计算。我见过有人设了 50px，结果导航栏实际高度是 72px，导致高亮总是慢半拍。
3.4 用 JS 初始化和用 data 属性初始化的区别
滚动监控有两种初始化方式：data 属性和JS 手动初始化。
data 属性方式就是上面那种，在容器上写>const spy = new bootstrap.ScrollSpy(document.body, { target: '#pageNav', offset: 80, rootMargin: '0px 0px -40% 0px' });
JS 方式的好处是可以拿到实例，后续调用spy.refresh()重新计算，或者在配置里用rootMargin做更精细的控制。rootMargin是 Bootstrap 5.2 之后支持的配置，它基于IntersectionObserver，比单纯用 offset 更准确。
我的建议是：简单页面用 data 属性，复杂页面用 JS 初始化。因为复杂页面往往需要动态调整，data 属性改起来很麻烦。
3.5 滚动监控和锚点跳转的配合
滚动监控经常和锚点跳转一起用。点击导航项，页面平滑滚动到对应区块，同时导航项高亮。这里有两个细节：
第一，平滑滚动。Bootstrap 5 没有内置平滑滚动，需要自己加 CSS：
html { scroll-behavior: smooth; }但要注意，scroll-behavior: smooth会影响所有滚动行为，包括用户手动滚动。如果只想让锚点跳转平滑，可以用 JS 的scrollIntoView({ behavior: 'smooth' })。
第二，跳转后的偏移。点击锚点跳转时，固定导航栏同样会挡住区块顶部。解决办法是给被监控的区块加scroll-margin-top：
section[id] { scroll-margin-top: 80px; }这个属性和>const spy = bootstrap.ScrollSpy.getInstance(document.body); spy.refresh();
refresh()会重新计算所有被监控区块的位置。什么时候调用？在动态内容渲染完成之后。我一般会在数据渲染的回调里调一次，或者在window.resize时也调一次，因为窗口大小变化会影响区块位置。
这里有个坑：频繁调用refresh()会有性能问题，因为它会强制重排。如果内容是流式加载的，建议用防抖，比如 200ms 内只调一次。
4. 两个组件结合使用的实战场景
4.1 场景一：带进度反馈的长文档阅读器
设想一个长文档阅读页面，顶部有阅读进度条，右侧有章节导航（滚动监控）。用户滚动时，进度条显示“已读百分比”，导航高亮当前章节。这个场景把两个组件都用上了。
进度条的计算逻辑是：
window.addEventListener('scroll', () => { const scrollTop = window.scrollY; const docHeight = document.documentElement.scrollHeight - window.innerHeight; const percent = (scrollTop / docHeight) * 100; setProgress(percent); });这里要注意：docHeight是文档总高度减去视口高度，因为滚动到底部时scrollY等于docHeight，这样算出来才是 100%。如果直接用scrollHeight，永远到不了 100%。
滚动监控用 data 属性初始化，offset 设为顶部导航栏高度。两个组件互不干扰，但视觉上形成了一套完整的阅读反馈系统。
4.2 场景二：多步骤表单的进度指示
多步骤表单里，进度条表示“完成了多少步”，滚动监控其实用不上，但可以用类似的思路做步骤导航的高亮。不过这里更值得说的是进度条的状态管理。
多步骤表单的进度条通常有两种表达：按步骤数（第 3 步 / 共 5 步 = 60%）或者按字段完成度（已填 12 个 / 共 20 个 = 60%）。我倾向于按步骤数，因为用户对“第几步”的感知更直观。
进度条的颜色可以随步骤变化：前几步用蓝色，中间用黄色提示“还有未完成项”，最后一步用绿色。这种颜色变化不需要额外逻辑，就是切换.bg-*类。
4.3 场景三：数据看板里的任务状态分布
数据看板里经常需要展示“一批任务的状态分布”。这时候用多段进度条最合适：
<div class="progress" style="height: 24px;"> <div class="progress-bar bg-success" style="width: 62%">成功 62%</div> <div class="progress-bar bg-warning" style="width: 23%">进行中 23%</div> <div class="progress-bar bg-danger" style="width: 15%">失败 15%</div> </div>这个场景里，滚动监控用不上，但进度条的多段能力被充分利用了。如果任务数量很多，还可以在进度条下方加一个图例，用颜色对应状态。
4.4 两个组件的性能注意事项
进度条的性能问题主要出在高频更新和动画上。滚动事件触发频率很高，如果每次滚动都更新进度条宽度，会造成大量重排。解决办法是用requestAnimationFrame节流：
let ticking = false; window.addEventListener('scroll', () => { if (!ticking) { requestAnimationFrame(() => { updateProgress(); ticking = false; }); ticking = true; } });滚动监控的性能问题主要出在区块数量多和频繁 refresh上。如果页面有几十个被监控区块，IntersectionObserver的开销会明显上升。这时候可以考虑只监控当前视口附近的几个区块，或者用虚拟滚动的思路。
两个组件同时使用时，注意不要在一个滚动事件里同时做太多事。我的做法是：进度条更新用requestAnimationFrame，滚动监控交给 Bootstrap 自己处理，两者互不干扰。
5. 常见问题与排查技巧实录
5.1 进度条不显示或宽度为 0
这是最常见的问题。排查顺序是：
- 检查
.progress容器是否存在，且没有被display: none隐藏。 - 检查
.progress-bar的style.width是否设置，值是否是百分比。 - 检查
.progress的父元素是否有宽度。如果父元素宽度是 0，进度条也撑不开。 - 检查是否有 CSS 覆盖了
.progress的overflow或.progress-bar的width。
我遇到过一次，进度条在 flex 容器里宽度为 0，原因是.progress没有设flex: 1，被其他元素挤没了。加上flex: 1就好了。
5.2 滚动监控不生效
排查顺序：
- 检查
>
