如何快速掌握 smc.peering.tw：内置新手引导之旅完整拆解

smc.peering.tw 是一个展示台湾海底电缆（Submarine Cable）实时状态的交互地图看板，而它内置的「新手引导之旅」是帮助新手用户 3 分钟熟悉整站功能的最佳入口。本文完整拆解这个引导之旅的 11 个步骤、触发机制与底层实现，让你快速掌握这个海缆状态地图的每一处细节。

什么是内置新手引导之旅

对于第一次打开 smc.peering.tw 的用户，最直观的体验就是：

1. 首次访问会弹出一个「重要提醒」窗口，说明数据来源与免责声明；
2. 点击「我了解」后，新手引导自动开始，一步步高亮界面各区域并配上讲解气泡；
3. 之后随时可以点击侧边栏的「?」帮助按钮重新启动引导。

这套引导基于 driver.js（一个轻量级产品引导库）实现，配合 zustand 状态管理和 react-i18next 多语言方案，覆盖英文与繁体中文两种界面语言。

11 步引导之旅：逐站拆解

引导之旅共有11 个站点（steps），每一步都锚定界面上一个真实的 UI 元素。以下是完整路线：

💡 注意第 8 步的小心思：点击「下一步」时会自动打开拓扑视图弹窗，等拓扑图渲染完成后才前进到第 9 步，保证引导节奏与页面状态同步。

引导之旅是如何实现的：3 个核心模块

模块一：TourController.tsx —— 引导引擎

整个引导之旅的「总导演」。核心逻辑包括：

• 通过driver({ steps: [...] })定义 11 步引导，每步指定锚点元素、弹出方向与文案；
• 全局设置showProgress: true（显示进度）、overlayOpacity: 0.75（半透明遮罩聚焦当前元素）、allowClose: true（可随时关闭）；
• 用waitForElement轮询等待动态渲染的元素（如拓扑图），避免引导"跑空"；
• 引导结束后清理状态，防止重复触发。

步骤定义的结构非常简洁：

steps: [ { element: '[data-tour="counter"]', popover: { title: t("tour.counter.title"), description: t("tour.counter.body"), side: "right", // ... }, }, // ...共 11 步 ]

模块二：tour.ts —— 全局状态桥

用 zustand 维护引导的三块状态：startTour（启动函数引用）、tourActive（是否正在进行）、topologyTourOpen（拓扑弹窗是否因引导而打开）。这样侧边栏的帮助按钮、移动端抽屉、引导控制器之间可以互相通信。

模块三：Intro.tsx —— 首次访问入口

首次访问的「重要提醒」弹窗是引导之旅的触发器：用户点击「我了解」后，会将 localStorage 中的tourAutoStartAllowed置为true，随后 TourController.tsx 检测到「允许自动开始 + 尚未引导过」两个条件同时满足，立即启动引导。

两个关键的 localStorage 键决定了引导行为：

界面锚点：data-tour 是怎么工作的

引导能精准"指向"某个按钮或面板，靠的是散落在各组件上的data-tour属性。例如：

• 连线状态计数器：OutageCounter.tsx
• 地图图例：MapLegend.tsx
• 事件面板 / 模式切换 / 语言按钮 / 帮助按钮：Sidebar.tsx
• 海缆筛选器：App.tsx
• 拓扑图：Topology.tsx

data-tour只是普通 HTML 属性，对界面行为零侵入，引导库通过[data-tour="xxx"]选择器即可定位并高亮任意元素。

多语言引导文案在哪里

所有引导文案集中在 i18n 语言包的tour节点下：

• 繁体中文：zh-tw.json
• 英文：en.json

按钮文字（下一步 / 上一步 / 完成）和每一步的标题、正文全部走翻译函数，因此切换语言后引导会实时切换语言——这也是第 6 步"语言切换"引导站点的由来。

如何自己启动引导之旅：2 种方式

1. 首次访问自动启动：打开站点 → 语言选择后出现「重要提醒」→ 点击「我了解」→ 引导自动开始（全程约 1~2 分钟）；
2. 随时手动重启：点击侧边栏（移动端为底部抽屉右上角）的「?」帮助按钮即可重新开始完整引导，对应组件为 Sidebar.tsx。

引导过程中可以随时关闭遮罩跳过；移动端抽屉会自动展开到全屏并同步切换到对应标签页，保证引导内容可见。

写在最后

smc.peering.tw 用driver.js +>赞分享