Tour 新手引导

逐步引导式产品导览

逐步引导式产品导览覆盖层，带有聚焦高亮、导航和 localStorage 持久化。

何时使用

需要引导新用户了解产品功能时使用，支持聚焦高亮目标元素和步骤导航。

代码示例

基础用法

tsx

import { Tour } from "@chaos_team/chaos-ui/ui"

export function Basic() {
return (
  <Tour
    steps={[
      { target: "#dashboard", title: "Dashboard", description: "Your overview area" },
      { target: "#settings", title: "Settings", description: "Configure your preferences" },
    ]}
    onComplete={() => console.log("Tour completed")}
  />
)
}

受控模式

tsx

import { Tour } from "@chaos_team/chaos-ui/ui"
import { useState } from "react"

export function Controlled() {
const [open, setOpen] = useState(false)
return (
  <Tour
    open={open}
    onOpenChange={setOpen}
    steps={[{ target: "#help-btn", title: "Help", description: "Click for assistance" }]}
  />
)
}

API / Props

Tour

Prop	Type	Default	说明
`steps`	`TourStep[]`	—	Tour steps / 导览步骤 (required)
`open`	`boolean`	—	Controlled open state / 受控打开状态
`onOpenChange`	`(open: boolean) => void`	—	Open change callback / 打开变化回调
`onComplete`	`() => void`	—	Complete callback / 完成回调
`onSkip`	`() => void`	—	Skip callback / 跳过回调
`storageKey`	`string`	—	localStorage key for persistence / localStorage 持久化键

TourStep

Prop	Type	Default	说明
`target`	`string \| (() => HTMLElement \| null)`	—	CSS selector or element / CSS 选择器或元素 (required)
`title`	`string`	—	Step title / 步骤标题 (required)
`description`	`React.ReactNode`	—	Step description / 步骤描述
`placement`	`"top" \| "bottom" \| "left" \| "right"`	`bottom`	Popover placement / 弹出位置
`offset`	`number`	`8`	Offset from target / 与目标的偏移

注意事项

Client Component: 使用 "use client",依赖 React hooks/状态,需在客户端渲染。
localStorage: 设置 storageKey 后，完成的导览不会再次显示。

📘 完整交互式示例与控件属性请查看 Storybook 文档。