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

Tour 新手引导

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

基础用法

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

背景视口

src/App.vue

<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>

import { useState } from 'react';
import { CfButton, CfTour } from '@chufix-design/react';

export default function Demo() {
  const [open, setOpen] = useState(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',
    },
  ];
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 16, alignItems: "flex-start" }}>
          <div style={{ display: "flex", gap: 8 }}>
            <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" onClick={() => setOpen(true)}>开始引导</CfButton>
          <CfTour value={open} onChange={setOpen} steps={steps} />
        </div>
    </>
  );
}

import { useState } from 'react';
import { CfButton, CfTour } from '@chufix-design/react';

export default function Demo() {
  const [open, setOpen] = useState(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',
    },
  ];
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 16, alignItems: "flex-start" }}>
          <div style={{ display: "flex", gap: 8 }}>
            <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" onClick={() => setOpen(true)}>开始引导</CfButton>
          <CfTour value={open} onChange={setOpen} steps={steps} />
        </div>
    </>
  );
}

API

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

Events

Vue 事件	React 回调	载荷类型	说明
`update:modelValue`	`onOpenChange`	`boolean`	显示状态变化时触发
`update:current`	`onCurrentChange`	`number`	当前步索引变化时触发
`finish`	`onFinish`	—	用户点击「完成」走完最后一步时触发
`close`	`onClose`	—	用户主动关闭（点击 × 或外部）时触发

TourStep

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