Preview Updated 2026-05-10

Tour

Step-by-step highlight of key UI elements with explanation popovers. Use it to onboard users when shipping new features.

Basic usage

Each entry in steps is { target, title, description, placement }. target is a CSS selector for the element to highlight; placement is the popover side relative to the target.

背景视口

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

Prop	Type	Default	Description
`steps`	`TourStep[]`	`—`	Tour steps
`open` / `modelValue`	`boolean`	`—`	Controlled visibility
`defaultOpen` / `defaultValue`	`boolean`	`false`	Uncontrolled initial visibility
`current`	`number`	`—`	Controlled current step index
`defaultCurrent`	`number`	`0`	Uncontrolled initial step

Events: onOpenChange(open) / onCurrentChange(n) / onFinish() / onClose().

TourStep

Field	Type	Description
`target`	`string`	CSS selector to locate the highlight target
`title`	`string`	Popover title
`description`	`string`	Popover description (optional)
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	Popover side relative to target, default `'bottom'`