# 漫游式引导

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/tour
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

用于分步引导用户了解产品功能的气泡组件。


## 何时使用 {#when-to-use}

常用于引导用户了解产品功能。

## 代码演示 {#examples}


- 基本 · `basic`
- 非模态 · `non-modal`
- 位置 · `placement`
- 自定义遮罩样式 · `mask`
- 自定义指示器 · `indicator`
- 自定义操作按钮 · `actions-render`
- 自定义高亮区域的样式 · `gap`
- 自定义语义结构的样式和类 · `style-class`


## API

通用属性参考：[通用属性](#jguang-common-props)

### Tour

| 属性 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| arrow | 是否显示箭头，包含是否指向元素中心的配置 | `boolean` \| `{ pointAtCenter: boolean}` | `true` |  | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| closeIcon | 自定义关闭按钮 | `React.ReactNode` | `true` | 5.9.0 | 5.14.0 |
| disabledInteraction | 禁用高亮区域交互 | `boolean` | `false` | 5.13.0 | × |
| gap | 控制高亮区域的圆角边框和显示间距 | `{ offset?: number \| [number, number]; radius?: number }` | `{ offset?: 6 ; radius?: 2 }` | 5.0.0 (数组类型的 `offset`: 5.9.0 ) | × |
| keyboard | 是否启用键盘快捷行为 | boolean | true | 6.2.0 | × |
| placement | 引导卡片相对于目标元素的位置 | `center` `left` `leftTop` `leftBottom` `right` `rightTop` `rightBottom` `top` `topLeft` `topRight` `bottom` `bottomLeft` `bottomRight` | `bottom` |  | × |
| onClose | 关闭引导时的回调函数 | `Function` | - |  | × |
| onFinish | 引导完成时的回调 | `Function` | - |  | × |
| mask | 是否启用蒙层，也可传入配置改变蒙层样式和填充色 | `boolean \| { style?: React.CSSProperties; color?: string; }` | `true` |  | × |
| type | 类型，影响底色与文字颜色 | `default` \| `primary` | `default` |  | × |
| open | 打开引导 | `boolean` | - |  | × |
| onChange | 步骤改变时的回调，current 为当前的步骤 | `(current: number) => void` | - |  | × |
| current | 当前处于哪一步 | `number` | - |  | × |
| scrollIntoViewOptions | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数 | `boolean \| ScrollIntoViewOptions` | `true` | 5.2.0 | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 6.0.0 |
| indicatorsRender | 自定义指示器 | `(current: number, total: number) => ReactNode` | - | 5.2.0 | × |
| actionsRender | 自定义操作按钮 | `(originNode: ReactNode, info: { current: number, total: number }) => ReactNode` | - | 5.25.0 | × |
| zIndex | Tour 的层级 | number | 1001 | 5.3.0 | × |
| getPopupContainer | 设置 Tour 浮层的渲染节点，默认是 body | `(node: HTMLElement) => HTMLElement` | body | 5.12.0 | × |

### TourStep 引导步骤卡片 {#tourstep}

| 属性 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| target | 获取引导卡片指向的元素，为空时居中于屏幕 | `() => HTMLElement` \| `HTMLElement` | - |  |
| arrow | 是否显示箭头，包含是否指向元素中心的配置 | `boolean` \| `{ pointAtCenter: boolean}` | `true` |  |
| closeIcon | 自定义关闭按钮 | `React.ReactNode` | `true` | 5.9.0 |
| cover | 展示的图片或者视频 | `ReactNode` | - |  |
| title | 标题 | `ReactNode` | - |  |
| description | 主要描述部分 | `ReactNode` | - |  |
| placement | 引导卡片相对于目标元素的位置 | `center` `left` `leftTop` `leftBottom` `right` `rightTop` `rightBottom` `top` `topLeft` `topRight` `bottom` `bottomLeft` `bottomRight` | `bottom` |  |
| onClose | 关闭引导时的回调函数 | `Function` | - |  |
| mask | 是否启用蒙层，也可传入配置改变蒙层样式和填充色，默认跟随 Tour 的 `mask` 属性 | `boolean \| { style?: React.CSSProperties; color?: string; }` | `true` |  |
| type | 类型，影响底色与文字颜色 | `default` \| `primary` | `default` |  |
| nextButtonProps | 下一步按钮的属性 | `{ children: ReactNode; onClick: Function }` | - |  |
| prevButtonProps | 上一步按钮的属性 | `{ children: ReactNode; onClick: Function }` | - |  |
| scrollIntoViewOptions | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数，默认跟随 Tour 的 `scrollIntoViewOptions` 属性 | `boolean \| ScrollIntoViewOptions` | `true` | 5.2.0 |

## Semantic DOM

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 引导根容器，设置绝对定位、层级控制、最大宽度、可见性、箭头背景色变量、主题样式等容器样式 | 6.0.0 |
| `mask` | 遮罩层元素，设置固定定位、全屏覆盖、层级、指针事件、过渡动画等遮罩样式 | 6.0.0 |
| `section` | 卡片主要内容区域，设置文本对齐、边框圆角、盒阴影、相对定位、背景色、边框、背景裁剪等卡片样式 | 6.0.0 |
| `cover` | 卡片封面区域，设置文本居中对齐、内边距、图片宽度等图片展示样式 | 6.0.0 |
| `close` | 关闭按钮元素，设置绝对定位、尺寸、颜色、悬浮态和交互反馈等关闭按钮样式 | 6.4.0 |
| `header` | 卡片头部区域，设置内边距、宽度计算、词汇换行等头部容器样式 | 6.0.0 |
| `title` | 引导标题文字，设置字体粗细等标题文本样式 | 6.0.0 |
| `description` | 引导描述文字，设置内边距、词汇换行等描述文本样式 | 6.0.0 |
| `footer` | 卡片底部操作区域，设置内边距、文本右对齐、边框圆角、Flex布局等底部容器样式 | 6.0.0 |
| `actions` | 操作按钮组容器，设置左侧自动外边距、按钮间距等按钮组布局样式 | 6.0.0 |
| `indicators` | 指示器组容器，设置行内块显示等指示器容器样式 | 6.0.0 |
| `indicator` | 单个指示器元素，设置宽高尺寸、行内块显示、圆角、背景色、右外边距、激活状态等圆点样式 | 6.0.0 |

语义说明来源: `vendor/components/tour/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `zIndexPopup` | `number` | 弹层 z-index |
| `closeBtnSize` | `number` | 关闭按钮尺寸 |
| `primaryPrevBtnBg` | `string` | Primary 模式上一步按钮背景色 |
| `primaryNextBtnHoverBg` | `string` | Primary 模式下一步按钮悬浮背景色 |

声明来源: `vendor/components/tour/style/index.ts`

```ts
import { unit } from '@ant-design/cssinjs';

import { FastColor } from '@ant-design/fast-color';

import { genFocusStyle, resetComponent } from '../../style';

import type { ArrowOffsetToken } from '../../style/placementArrow';

import getArrowStyle, {
  getArrowOffsetToken,
  MAX_VERTICAL_CONTENT_RADIUS,
} from '../../style/placementArrow';

import type { ArrowToken } from '../../style/roundedArrow';

import { getArrowToken } from '../../style/roundedArrow';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

export interface ComponentToken extends ArrowOffsetToken, ArrowToken {
  /**
   * @desc 弹层 z-index
   * @descEN Tour popup z-index
   */
  zIndexPopup: number;
  /**
   * @desc 关闭按钮尺寸
   * @descEN Close button size
   */
  closeBtnSize: number;
  /**
   * @desc Primary 模式上一步按钮背景色
   * @descEN Background color of previous button in primary type
   */
  primaryPrevBtnBg: string;
  /**
   * @desc Primary 模式下一步按钮悬浮背景色
   * @descEN Hover background color of next button in primary type
   */
  primaryNextBtnHoverBg: string;
}

interface TourToken extends FullToken<'Tour'> {
  indicatorWidth: number | string;
  indicatorHeight: number | string;
  tourBorderRadius: number;
}
```


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/tour/PurePanel.tsx`
- `vendor/components/tour/interface.ts`
- `vendor/components/tour/panelRender.tsx`
- `vendor/components/tour/style/index.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt