mirror of
https://github.com/longbridge/developers.git
synced 2026-09-19 03:34:09 +08:00
Endless
ba970ec583
🤖 Auto-generated by Endless task [#21](https://endless.longbridge-inc.com/projects/developers/tasks/21). Initiated by: Huacnlee Li Huashun ## 背景 VitePress 站点采用客户端单页导航（SPA），用户点击内部链接后，页面内容需要通过网络请求加载。在网速较慢的情况下，点击链接后会有一段时间页面没有任何视觉反馈，用户无法判断是否点击成功、是否正在加载。 这一问题在海外用户访问时尤为明显，因为服务器位于香港，部分地区的延迟可能达到数百毫秒到几秒。缺少加载指示会导致用户重复点击或误以为网站出现故障。 ## 摘要 - 解决的问题：VitePress 单页导航期间无加载反馈，网速较慢时用户体验差 - 做了什么： - 新增 `useProgressBar.ts` 组合式模块，封装进度条的响应式状态和 `startProgress`/`finishProgress` 控制函数 - 新增 `ProgressBar.vue` 组件，以 `position: fixed` 固定在视口顶部，使用主题品牌色渲染 2px 高度进度条 - 修改 `theme/index.ts`，在 VitePress 路由 `onBeforeRouteChange` 触发 `startProgress()`，在 `onAfterRouteChange` 触发 `finishProgress()` 并保留原有 `saveInviteCodeFromUrl` 逻辑 - 修改 `LayoutInner.vue`，在布局顶部引入并渲染 `<ProgressBar />` - 为什么这样做： - 未引入新的 npm 依赖（nprogress 等），避免增加 bundle 体积和版本维护成本；自定义实现仅约 25 行 - 使用模块级响应式状态，组件直接订阅，无需 `provide/inject`，且 SSR 阶段 `visible` 初始为 `false`，不会影响静态构建 - 几何缓动算法（`current + (85 - current) * 0.1`）使进度条在快速和慢速网络下均表现自然，与 GitHub、YouTube 等主流实现一致 - 如何验证： 1. 在 `code/developers/` 目录运行 `bun run dev` 2. 通过侧边栏在不同文档页面间导航，顶部应出现品牌色细进度条并在加载完成后消失 3. 切换 dark mode，验证进度条颜色跟随 `--vp-c-brand-1`/`--vp-c-brand-2` CSS 变量 4. 在系统/浏览器无障碍设置中开启「减少动态效果」，验证进度条仍可见但无过渡动画 ## 修改 | 文件 | 改动内容 | |---|---| | `docs/.vitepress/theme/composables/useProgressBar.ts` | 新增：模块级响应式状态和进度控制函数 | | `docs/.vitepress/theme/components/ProgressBar.vue` | 新增：固定定位进度条组件，支持 CSS Transition 淡出和 prefers-reduced-motion | | `docs/.vitepress/theme/index.ts` | 新增 `useProgressBar` 导入，将路由钩子替换为链式调用（进度条 + 原有 invite-code 逻辑） | | `docs/.vitepress/theme/layouts/LayoutInner.vue` | 引入并在 `layout-top` slot 后渲染 `<ProgressBar />` | ## 关键决策 不引入 nprogress 等第三方库——其核心逻辑与本实现等价，但需额外的 npm 依赖、类型声明和样式覆盖。自定义实现代码量极小，且可直接使用 VitePress 主题的 CSS 变量保持视觉一致性。 --------- Co-authored-by: Huacnlee Li Huashun <huacnlee@longbridge-inc.com> Co-authored-by: Jason Lee <huacnlee@gmail.com>