From d86a69cec25ca031a002b25a881a18dec005c917 Mon Sep 17 00:00:00 2001
From: Charliechen114514 <725610365@qq.com>
Date: Sun, 5 Jul 2026 08:21:51 +0800
Subject: [PATCH] =?UTF-8?q?fix(site):=20mermaid=20=E8=B7=B3=E8=BD=AC?=
 =?UTF-8?q?=E5=90=8E=E4=B8=8D=E6=B8=B2=E6=9F=93=20=E2=80=94=20onAfterRoute?=
 =?UTF-8?q?Change=20=E6=94=B9=E8=AE=A2=E9=98=85=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ReadingProgress 与 mermaid 各自直接赋值 router.onAfterRouteChange
(单值属性,非事件订阅),后挂载的 ReadingProgress 覆盖了 mermaid 的
回调,导致 SPA 跳转进含 mermaid 的页面时图不渲染、需 F5(首屏走
onMounted 不受影响,所以现象是"直接访问 URL 正常、跳转不显示、
F5 又正常")。

新增 router-hooks.ts 提供 subscribeAfterRouteChange 订阅器(订阅者
集合 + 单 dispatcher,带 try/catch 隔离),mermaid-client 与
ReadingProgress 改用之。治本:未来再加路由切换逻辑不会再互覆盖。

自查:grep 确认全局仅 router-hooks.ts 一处 onAfterRouteChange 赋值;
vitepress dev 启动零 error;并行 build SUCCESS (34 task 全建)。

pre-commit update-translation-coverage hook 同步刷新了 README 翻译
覆盖率报告,一并纳入。
---
 README.md                                     |  2 +-
 .../theme/components/ReadingProgress.vue      |  7 ++---
 site/.vitepress/theme/mermaid-client.ts       |  8 +++---
 site/.vitepress/theme/router-hooks.ts         | 28 +++++++++++++++++++
 4 files changed, 36 insertions(+), 9 deletions(-)
 create mode 100644 site/.vitepress/theme/router-hooks.ts

diff --git a/README.md b/README.md
index 8a965bcf3..1f15c1578 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@
 ---
 
 <!-- COVERAGE_START -->
-![English Coverage](https://img.shields.io/badge/en_coverage-97%25-green.svg) 494/510 docs translated
+![English Coverage](https://img.shields.io/badge/en_coverage-84%25-green.svg) 494/588 docs translated
 <!-- COVERAGE_END -->
 
 ## 这是什么项目
diff --git a/site/.vitepress/theme/components/ReadingProgress.vue b/site/.vitepress/theme/components/ReadingProgress.vue
index 02fcf628b..938bbb9c2 100644
--- a/site/.vitepress/theme/components/ReadingProgress.vue
+++ b/site/.vitepress/theme/components/ReadingProgress.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
 import { ref, onMounted, onBeforeUnmount } from 'vue'
-import { useRouter } from 'vitepress'
+import { subscribeAfterRouteChange } from '../router-hooks'
 
 // 顶部阅读进度条：滚动时按 scrollTop / (scrollHeight - clientHeight) 算百分比。
 // brand 渐变 + 钢蓝微光，固定在视口顶部。路由切换 rAF+300ms 双重重算（短页归零坑）。
 // scroll/resize 用 rAF 合并，一帧最多算一次（比 anatomy 原版无节流更省，审计点名的性能债）。
 const progress = ref(0)
-const router = useRouter()
 let raf: number | null = null
 
 function update() {
@@ -28,11 +27,11 @@ onMounted(() => {
   window.addEventListener('resize', scheduleUpdate, { passive: true })
 })
 
-router.onAfterRouteChange = () => {
+subscribeAfterRouteChange(() => {
   // 路由切换：新页 DOM 立即可测 + 300ms 后（图片/mermaid 撑高）再补一次，防短页/异步内容归零失败
   requestAnimationFrame(update)
   setTimeout(update, 300)
-}
+})
 
 onBeforeUnmount(() => {
   if (raf !== null) cancelAnimationFrame(raf)
diff --git a/site/.vitepress/theme/mermaid-client.ts b/site/.vitepress/theme/mermaid-client.ts
index ccbb66717..a58a4238b 100644
--- a/site/.vitepress/theme/mermaid-client.ts
+++ b/site/.vitepress/theme/mermaid-client.ts
@@ -1,5 +1,5 @@
 import { nextTick, onMounted } from 'vue'
-import { useRouter } from 'vitepress'
+import { subscribeAfterRouteChange } from './router-hooks'
 
 // mermaid 的 API 形状(只取我们用到的两个方法),避免依赖整包类型
 type MermaidApi = {
@@ -79,9 +79,9 @@ function escapeHtml(s: string) {
 }
 
 export function setupMermaid() {
-  const router = useRouter()
-
+  // 用订阅器而非直接赋值 router.onAfterRouteChange:后者是单值属性,
+  // 会被 ReadingProgress 等组件覆盖,导致 SPA 跳转后 mermaid 不渲染。
   // .catch 治「静默失败」:之前 onMounted 调用没接住 reject,加载失败时图直接消失无痕。
   onMounted(() => renderMermaidDiagrams().catch((e) => console.error('[mermaid] onMounted 渲染失败', e)))
-  router.onAfterRouteChange = () => renderMermaidDiagrams().catch((e) => console.error('[mermaid] 路由切换渲染失败', e))
+  subscribeAfterRouteChange(() => renderMermaidDiagrams().catch((e) => console.error('[mermaid] 路由切换渲染失败', e)))
 }
diff --git a/site/.vitepress/theme/router-hooks.ts b/site/.vitepress/theme/router-hooks.ts
new file mode 100644
index 000000000..cfbdd5620
--- /dev/null
+++ b/site/.vitepress/theme/router-hooks.ts
@@ -0,0 +1,28 @@
+import { useRouter } from 'vitepress'
+
+// VitePress 的 router.onAfterRouteChange 是单值属性，不是事件订阅：
+// 任意组件再赋值就会覆盖前一个。曾经 ReadingProgress 和 mermaid 各自赋值，
+// 导致 SPA 跳转后 mermaid 不渲染（首屏 onMounted 路径正常，跳转路径被覆盖）。
+// 这里包一层订阅器：第一次订阅时安装一个 dispatcher，之后所有订阅者共享。
+type RouteHandler = (href: string) => void
+
+const subscribers = new Set<RouteHandler>()
+let installed = false
+
+export function subscribeAfterRouteChange(fn: RouteHandler): void {
+  subscribers.add(fn)
+  if (installed) return
+  // 必须在 setup 上下文调用（mermaid 的 setupMermaid / 各组件 setup 均满足）。
+  const router = useRouter()
+  router.onAfterRouteChange = (href: string) => {
+    for (const fn of subscribers) {
+      try {
+        fn(href)
+      } catch (e) {
+        // 单个订阅者抛错不能连累其它订阅者（否则 mermaid 渲染失败会让进度条也不更新）。
+        console.error('[router-hook] onAfterRouteChange 订阅者抛错', e)
+      }
+    }
+  }
+  installed = true
+}