开发预览更新于 2026-05-10

Tour 新手引导

分步高亮关键 UI 元素 + 解释气泡，新功能上线时引导用户。

基础用法

steps 每一项 { target, title, description, placement }。target 是 CSS 选择器，对应页面里需要被高亮的元素；placement 控制气泡相对目标的方位。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfTour, CfButton, type TourStep } from '@chufix-design/vue';

const open = ref(false);

const steps: TourStep[] = [
  {
    target: '#tour-step-1',
    title: '欢迎使用',
    description: '这是引导的第一步，会高亮当前操作目标。',
    placement: 'bottom',
  },
  {
    target: '#tour-step-2',
    title: '关键功能',
    description: '点击这里可以创建一份新的资源。',
    placement: 'bottom',
  },
  {
    target: '#tour-step-3',
    title: '设置入口',
    description: '在这里配置全局偏好，随时可改。',
    placement: 'bottom',
  },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start;">
    <div style="display: flex; gap: 8px;">
      <CfButton id="tour-step-1" variant="secondary" size="sm">资源列表</CfButton>
      <CfButton id="tour-step-2" variant="primary" size="sm">+ 新建</CfButton>
      <CfButton id="tour-step-3" variant="ghost" size="sm">⚙ 设置</CfButton>
    </div>
    <CfButton size="sm" @click="open = true">开始引导</CfButton>
    <CfTour v-model="open" :steps="steps" />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CfTour, CfButton } from '@chufix-design/vue';

const open = ref(false);

const steps= [
  {
    target: '#tour-step-1',
    title: '欢迎使用',
    description: '这是引导的第一步，会高亮当前操作目标。',
    placement: 'bottom',
  },
  {
    target: '#tour-step-2',
    title: '关键功能',
    description: '点击这里可以创建一份新的资源。',
    placement: 'bottom',
  },
  {
    target: '#tour-step-3',
    title: '设置入口',
    description: '在这里配置全局偏好，随时可改。',
    placement: 'bottom',
  },
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start;">
    <div style="display: flex; gap: 8px;">
      <CfButton id="tour-step-1" variant="secondary" size="sm">资源列表</CfButton>
      <CfButton id="tour-step-2" variant="primary" size="sm">+ 新建</CfButton>
      <CfButton id="tour-step-3" variant="ghost" size="sm">⚙ 设置</CfButton>
    </div>
    <CfButton size="sm" @click="open = true">开始引导</CfButton>
    <CfTour v-model="open" :steps="steps" />
  </div>
</template>

<CfTour open={open} onOpenChange={setOpen} steps={steps} />

<CfTour open={open} onOpenChange={setOpen} steps={steps} />

API

属性	类型	默认值	说明
`steps`	`TourStep[]`	`—`	引导步骤列表
`open` / `modelValue`	`boolean`	`—`	受控显示状态
`defaultOpen` / `defaultValue`	`boolean`	`false`	非受控初始状态
`current`	`number`	`—`	受控当前步索引
`defaultCurrent`	`number`	`0`	非受控初始步

事件：onOpenChange(open) / onCurrentChange(n) / onFinish() / onClose()。

TourStep

字段	类型	说明
`target`	`string`	CSS 选择器，定位高亮目标
`title`	`string`	气泡标题
`description`	`string`	气泡描述（可选）
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	气泡相对目标的方位，默认 `'bottom'`