添加完善说明文档#21
Merged
Merged
Conversation
endless-bot
added a commit
that referenced
this pull request
May 21, 2026
…ading（在 navbar 顶部增加 progress）让用户知道在加载中 Generated by Endless task #21. Co-authored-by: Huacnlee Li Huashun <huacnlee@longbridge-inc.com>
huacnlee
added a commit
that referenced
this pull request
May 21, 2026
🤖 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.