企业官网建设流程全解析

Astryx Tour组件实战：三步搞定产品新手引导之旅

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx

Astryx 是一款完全可定制、面向 Agent 的开源设计系统，其中的 Tour 组件专为产品新手引导（Onboarding / NUX 引导）而生：它像一个"聚光灯控制器"，把用户一步步带到页面上的关键元素旁，配上方言式的提示气泡，让新用户 3 步就能上手你的产品。本文将带你快速学会如何用 Tour 组件搭建一个专业、简洁的产品引导之旅。

为什么用 Astryx Tour 做产品引导？

新手引导做不好，用户流失率会悄悄上升；做得太重，用户又会直接跳过。Astryx Tour 的官方定位是「引导式产品 tour（NUX / Onboarding）」，它自带三类实用能力 🎯：

• 聚光灯高亮（Spotlight）：当前步骤的目标元素保持"点亮"，其余区域变暗，用户视线被自然聚焦
• 轻量 Coachmark 模式：关闭背景遮罩后，只用光环圈住目标元素，适合单点功能提示
• 步骤控制与进度：自带 上一步 / 下一步 / 关闭 控件，可选显示「第 2 步 / 共 5 步」的进度文案

组件定义在 Tour.tsx 与 TourStep.tsx，属于 Astryx 的实验组件包（lab）——API 仍在快速迭代，适合在可接受 canary 版本的项目中尝试。

第一步：认识 Tour 与 TourStep 的协作关系

Tour 组件本身不渲染任何可见界面，它只是一个"控制器"：

• 管理当前激活的是哪一步
• 负责前进、后退、完成、关闭这些状态流转
• 通过 React Context 把状态共享给声明式嵌套在内部的 TourStep 子组件

而TourStep才是真正"看得见"的部分：它把高亮环画在一个独立覆盖层上（目标元素本身从不会被改动样式），并借助 Astryx 核心的 Popover / Layer 能力，把提示气泡锚定在目标元素旁边。

💡 这种"控制器 + 步骤"的分离设计意味着：步骤顺序直接由你在 JSX 里写的先后顺序决定，无需再维护一个容易和界面脱节的步骤数组。

第二步：三步写出一个可用的新手引导

核心只有三步，以 Storybook 示例 Tour.stories.tsx 为参照：

1️⃣ 用 ref 标记要引导的元素

const saveRef = useRef<HTMLButtonElement>(null); <Button ref={saveRef} label="Save" />

2️⃣ 用 Tour + TourStep 声明引导步骤

<Tour isActive={isActive} hasBackdrop isStepCountShown onDismiss={() => setIsActive(false)}> <TourStep targetRef={saveRef} heading="保存你的工作"> 改动会自动保存到云端。 </TourStep> <TourStep targetRef={shareRef} heading="与团队分享"> 从这里邀请队友并管理权限。 </TourStep> </Tour>

3️⃣ 用一个状态开关控制启停

isActive是受控属性：为false时什么都不渲染，且步骤会重置回第一步——下次开启即可从头再走一遍，天然适合"每个用户只引导一次"的场景。

关键属性速查表

让引导更专业的 4 个最佳实践

根据官方文档 Tour.doc.mjs 中的建议：

1. 保持简短：只放几个高价值步骤，长引导注定被跳过
2. 自己持久化"已看过"：组件只通过onDismiss上报结果，请在其中写入本地存储，避免用户每次访问都看一遍
3. 目标元素要稳定可见：确保某一步激活前，目标已在屏幕内
4. 不要用引导替代清晰的设计：关键信息应直接内联在界面上，引导只是补充

另外，Tour 完全跟随主题：高亮环的颜色取自当前主题的 accent 令牌，你可以在任意<Theme>作用域内获得与品牌一致的引导视觉 🎨

总结：何时该上 Tour 组件？

• ✅ 新功能上线，想让用户一眼注意到入口
• ✅ 新用户首次进入，需要用 3~5 步讲清核心流程
• ✅ 想用一个轻量的 coachmark 圈出某个按钮
• ⚠️ 它目前位于实验包 packages/lab，仅以@canary版本发布，请在可接受 canary 更新节奏的项目中使用

掌握 Tour 的"控制器 + 步骤"思路后，你的产品引导之旅只需要：标记目标 → 声明步骤 → 控制启停。三步之后，新用户就能被温柔地领到正确的位置。

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx