Tour
分步骤引导用户认识界面。中文惯用名：漫游引导。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.tour |
| 名称 | Tour |
| 二级分类 | 反馈（feedback） |
| 用途 | 分步骤引导用户认识界面 |
| 描述 | 中文惯用名：漫游引导。 |
预览
静态结构：open=false 或 steps 为空时渲染 null；开启时经 createPortal 挂到 document.body——半透明遮罩（data-slot="tour-mask"，fixed inset-0 z-[90]）+ 当前步骤卡片（data-slot="tour-card"，fixed z-[100]、宽 w-72）：按当前步骤 target（CSS selector）找到元素后以其 getBoundingClientRect 定位在元素下方（bottom+8 / 左对齐）；选择器无匹配时卡片居中兜底（top/left 50% + translate，不抛错）。卡片内含标题（tour-title）+ 关闭按钮（tour-close，X 图标）+ 正文（tour-content）+ 底部「序号 n / 总数」与按钮组：非首步有 outline「上一步」，主按钮末步为「完成」、其余为「下一步」。
DSL 结构
{
"type": "Tour",
"props": {
"open": true,
"steps": [
{
"target": "#top-nav",
"title": "全局导航",
"content": "在这里切换资产库五大分类。"
},
{
"target": "#sidebar",
"title": "侧边导航",
"content": "分类内的子菜单与条目数。"
}
]
}
}何时用
何时使用
- 分步骤引导用户认识界面：新用户首次进入、重要改版后的功能导览。
- 步骤不多（3~5 步）、每步聚焦一个界面元素的引导任务。
- 需要用户主动开始 / 可随时关闭的轻引导（右上角关闭按钮 + 遮罩）。
何时不用
- 单个元素的补充说明：使用 Tooltip / Popover，Tour 是多步流程。
- 强制完成的任务教学或带校验的新手任务：Tour 无阻断校验能力，需自行组合 Dialog 等。
- 常驻帮助文档：使用帮助面板 / 文档页，Tour 是一次性引导。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 定位步骤 | 卡片吸附在 target 元素下方 | 指向具体功能入口的导览步骤 |
| 居中步骤（兜底） | target 缺省或无匹配时卡片屏幕居中 | 开场欢迎 / 收尾总结等无具体锚点的步骤 |
| 受控步骤 | current 由外部状态控制 | 需要与页面状态联动（如跳步、按条件分支）的引导 |
| 非受控步骤（默认） | 内部从 0 开始自维护步骤 | 常规线性导览；open 重新置 true 时步骤重置为 0 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
open | boolean | false | 是否开启引导；重新开启时非受控步骤重置为 0 |
steps | TourStep[] | [] | 步骤列表；每步 target（CSS selector，无匹配时卡片居中兜底）+ title + content |
current | number | — | 受控步骤序号（缺省内部从 0 开始）；越界时钳制到有效范围 |
onChange | (index: number) => void | — | 步骤切换事件：下一步 / 上一步触发，参数为目标序号 |
onClose | () => void | — | 完成（末步「完成」按钮）与关闭（右上角 X）事件 |
className | string | — | 通用：步骤卡片 class（与内置样式合并） |
style | CSSProperties | — | 通用：步骤卡片内联样式 |
使用规范
- steps.target 是 CSS selector：给被引导元素加稳定 data-* / id 选择器，不要用易变的类名或层级选择器。
- target 无匹配时卡片居中兜底、不抛错：但应监控兜底发生，及时修正失效选择器。
- 步骤控制在 3~5 步，每步一个焦点元素、一句标题 + 一段短说明；长教学拆成多次或改用帮助文档。
- open 受 state 控制：首次进入置 true，onClose（完成或关闭）时置 false 并记录「已引导」，避免每次进入重复弹出。
- 遮罩覆盖全屏（z-[90]）且卡片置顶（z-[100]）：引导期间页面操作被遮罩拦截，不要在其中要求用户操作被遮住的元素。
- 末步按钮固定为「完成」并触发 onClose：完成与中途关闭走同一事件，需区分时在 state 中记录当前步数。
正例
- ✓ 新用户导览：首步居中欢迎卡（不设 target），随后逐一定位「新建项目」「邀请成员」入口，末步「完成」。
- ✓ 改版功能导览：open 绑定「未看过该版本引导」标记，onClose 后落库标记。
- ✓ 受控联动：current 绑定 state，onChange 更新，按用户角色跳过管理员专属步骤。
反例
- ✕ target 使用 nth-child 等脆弱选择器，页面微调后引导错位（应使用稳定 data 属性）。
- ✕ 超过 7~8 步的长引导一口气弹完（用户流失，应拆分或改帮助文档）。
- ✕ 引导期间要求用户点击被遮罩覆盖的元素（操作被拦截，引导卡死）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。