VitePress 顶部页面加载进度条组件

组件简介

这个组件用于在页面顶部展示一条细线式的加载进度条，适合放在 VitePress 博客、文档站或内容型站点中。它的目标不是精确反映真实网络进度，而是在页面初次进入和站内路由切换时，给用户一个更平滑、更明确的加载反馈。

对于内容站来说，页面切换时如果完全没有状态提示，用户容易误以为没有点击成功。顶部加载进度条的好处就在于它几乎不占空间，但能快速传达“页面正在处理”的状态。

核心功能

• 支持首次进入站点时播放一次轻量的入场加载动画
• 支持站内页面切换时显示顶部进度条
• 使用渐变高亮样式，视觉上比纯色细线更醒目
• 通过伪进度策略推进动画，避免进度条停在某个位置显得僵硬
• 页面切换完成后自动补满进度并淡出
• 支持 prefers-reduced-motion，在减少动画模式下降低动态效果
• 通过 CSS 变量暴露高度、层级、渐变和光晕等可配置项

实现思路

这个组件没有依赖第三方进度条库，而是基于 VitePress 自带的客户端路由能力自行实现。

整体思路可以拆成三步：

1. 在页面真正开始加载前，先让进度条出现，并把起始进度推到一个较小的值
2. 页面加载过程中，使用定时器不断推进“伪进度”，形成“快速起步、缓慢逼近”的视觉效果
3. 页面完成切换后，将进度条补到 100%，随后淡出并重置状态

这样做的好处是实现简单、依赖少，而且视觉体验会比固定时长的线性动画更自然。

主题接入方式

该组件是通过 VitePress 默认主题扩展 的方式接入的，而不是直接写在首页 Markdown 中。

接入方式的关键点有两个：

• 在 .vitepress/theme/index.ts 中继承默认主题
• 在自定义 Layout 中通过 layout-top 插槽注入进度条组件

这种做法有几个优点：

• 不需要修改首页 index.md
• 能做到全站生效，而不是只作用于某一篇页面
• 和默认主题耦合较低，后续维护更方便

路由触发逻辑

组件主要依赖 VitePress 路由对象上的两个时机：

• onBeforePageLoad
• onAfterRouteChange

在 onBeforePageLoad 阶段启动进度条，可以保证只有真正发生页面加载时才出现动画；像同页锚点跳转这类没有实际页面加载的场景，就不会频繁闪动。

在 onAfterRouteChange 阶段收尾，则可以让页面切换结束后统一完成补满、淡出和重置，整体节奏会更完整。

样式与可配置项

当前组件对外暴露了几组 CSS 变量，便于后续按博客主题继续调整：

• --blog-loading-bar-height
• --blog-loading-bar-z-index
• --blog-loading-bar-gradient
• --blog-loading-bar-glow

默认样式特点如下：

• 固定在页面最顶部，不占据文档流
• 使用细线样式，尽量减少对页面主体内容的干扰
• 使用渐变高亮和轻微光晕，让状态反馈更明显
• 通过 transform: scaleX() 驱动进度变化，减少不必要的布局抖动

如果后续想做品牌化调整，可以直接围绕渐变颜色和发光效果继续扩展。

适用场景

这个组件比较适合以下场景：

• 个人博客
• 技术文档站
• 内容较多、路由切换频繁的静态站点
• 希望增强页面反馈但又不想引入重量级 UI 库的项目

如果站点后续组件越来越多，也可以把这一类内容继续沉淀到“组件”栏目中，逐步形成自己的组件记录库。

后续优化方向

后续如果继续完善，可以考虑这些方向：

• 为不同页面类型提供可选开关，例如某些页面不显示进度条
• 让颜色风格和站点主题进一步联动
• 在文章中补充组件截图或动图，方便读者快速理解效果
• 将公共逻辑继续抽离，方便复用到其他全站提示组件中

总结

顶部加载进度条是一个体量不大、但体验收益很直接的组件。它通过主题扩展和路由钩子实现全站接入，既保留了 VitePress 默认主题的结构，又增强了页面切换时的状态反馈，是一个很适合博客项目持续迭代的小组件。