Tour 引导

带有聚光灯高亮和步骤导航的引导式导览。

导入

import { Tour } from 'asterui'

示例

基础导览

带有多个步骤的简单引导式导览。

import { Tour, Button, Input, Card } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const searchRef = useRef<HTMLInputElement>(null);
  const profileRef = useRef<HTMLButtonElement>(null);
  const settingsRef = useRef<HTMLButtonElement>(null);
  
  const steps = [
    {
      target: searchRef,
      title: 'Search',
      description: 'Use the search bar to find content quickly.',
      placement: 'bottom' as const,
    },
    {
      target: profileRef,
      title: 'Profile',
      description: 'Click here to view and edit your profile.',
      placement: 'bottom' as const,
    },
    {
      target: settingsRef,
      title: 'Settings',
      description: 'Customize your experience in settings.',
      placement: 'left' as const,
    },
  ];
  
  return (
      <Card className="p-4">
        <div className="flex gap-4 items-center mb-4">
          <Input ref={searchRef} placeholder="Search..." className="flex-1" />
          <Button ref={profileRef}>Profile</Button>
          <Button ref={settingsRef}>Settings</Button>
        </div>
        <Button color="primary" onClick={() => setOpen(true)}>
          Start Tour
        </Button>
        <Tour
          open={open}
          steps={steps}
          onClose={() => setOpen(false)}
          onFinish={() => setOpen(false)}
        />
      </Card>
    )
}

export default App

无目标导览

没有目标的步骤出现在屏幕中央。

import { Tour, Button } from 'asterui'
import { useState } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  
  const steps = [
    {
      title: 'Welcome!',
      description: 'This tour will guide you through the main features.',
    },
    {
      title: 'Getting Started',
      description: 'Follow along to learn how to use this application.',
    },
    {
      title: 'All Done!',
      description: 'You are ready to start using the app.',
    },
  ];
  
  return (
      <Button color="primary" onClick={() => setOpen(true)}>
        Start Intro
      </Button>
      <Tour
        open={open}
        steps={steps}
        onClose={() => setOpen(false)}
        type="primary"
      />
    )
}

export default App

带封面图片

在步骤标题上方添加图片或自定义内容。

import { Tour, Button } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const buttonRef = useRef<HTMLButtonElement>(null);
  
  const steps = [
    {
      target: buttonRef,
      title: 'New Feature',
      description: 'Check out this amazing new feature we just added!',
      cover: (
        <img
          src="https://picsum.photos/320/160"
          alt="Feature preview"
          className="w-full h-40 object-cover"
        />
      ),
      placement: 'right' as const,
    },
  ];
  
  return (
      <Button ref={buttonRef} color="primary" onClick={() => setOpen(true)}>
        View Feature
      </Button>
      <Tour
        open={open}
        steps={steps}
        onClose={() => setOpen(false)}
        showSkip={false}
      />
    )
}

export default App

位置

控制气泡相对于目标出现的位置。

Target

import { Tour, Button, Space } from 'asterui'
import { useState, useRef } from 'react'

function App() {
  const [open, setOpen] = useState(false);
  const targetRef = useRef<HTMLDivElement>(null);
  const placements = ['top', 'right', 'bottom', 'left'] as const;
  const [placementIndex, setPlacementIndex] = useState(0);
  
  const steps = [
    {
      target: targetRef,
      title: `Placement: ${placements[placementIndex]}`,
      description: 'The popover can appear on any side of the target.',
      placement: placements[placementIndex],
    },
  ];
  
  return (
      <div className="flex flex-col items-center gap-4">
        <div
          ref={targetRef}
          className="w-24 h-24 bg-primary text-primary-content flex items-center justify-center rounded-lg"
        >
          Target
        </div>
        <Space>
          <Button onClick={() => setPlacementIndex((i) => (i + 1) % 4)}>
            Change Placement
          </Button>
          <Button color="primary" onClick={() => setOpen(true)}>
            Show Tour
          </Button>
        </Space>
        <Tour
          open={open}
          steps={steps}
          onClose={() => setOpen(false)}
          showIndicators={false}
        />
      </div>
    )
}

export default App

API

`Tour`

属性	描述	类型	默认值
`open`	导览是否可见	`boolean`	`false`
`steps`	导览步骤配置	`TourStepProps[]`	`-`
`current`	当前步骤索引(受控)	`number`	`-`
`onChange`	步骤更改时的回调	`(current: number) => void`	`-`
`onClose`	导览关闭时的回调	`() => void`	`-`
`onFinish`	导览完成时的回调	`() => void`	`-`
`mask`	显示带有聚光灯的遮罩覆盖层	`boolean`	`true`
`type`	按钮样式类型	`'default' \| 'primary'`	`'default'`
`gap`	聚光灯与目标之间的间隙 [半径, 偏移] 或数字	`number \| [number, number]`	`8`
`showSkip`	显示跳过按钮	`boolean`	`true`
`showIndicators`	显示步骤指示器	`boolean`	`true`
`closeOnMaskClick`	点击遮罩时关闭	`boolean`	`true`
`closeOnEscape`	按 Escape 键时关闭	`boolean`	`true`
`scrollIntoView`	将目标滚动到视图中	`boolean`	`true`
`prevButtonText`	上一步按钮的文本	`React.ReactNode`	`'Previous'`
`nextButtonText`	下一步按钮的文本	`React.ReactNode`	`'Next'`
`finishButtonText`	完成按钮的文本	`React.ReactNode`	`'Finish'`
`skipButtonText`	跳过按钮的文本	`React.ReactNode`	`'Skip'`
`zIndex`	导览覆盖层的 z-index	`number`	`1000`

`TourStepProps`

属性	描述	类型	默认值
`target`	目标元素 ref 或返回元素的函数	`RefObject<HTMLElement> \| (() => HTMLElement \| null) \| null`	`-`
`title`	步骤标题	`React.ReactNode`	`-`
`description`	步骤描述	`React.ReactNode`	`-`
`cover`	标题上方的封面图片或内容	`React.ReactNode`	`-`
`placement`	气泡相对于目标的位置	`TourPlacement`	`'bottom'`
`className`	步骤气泡的自定义类	`string`	`-`
`onOpen`	步骤变为活动状态时调用	`() => void`	`-`
`onClose`	离开步骤时调用	`() => void`	`-`

可访问性

导览对话框具有 role=“dialog” 和 aria-modal=“true”
箭头键在步骤之间导航
Escape 键关闭导览
步骤指示器可通过键盘访问
打开时焦点被困在导览内