# 创建第一个 Tour

URL: https://caijiao.org/driver-js/02-basics/01-basic-tour
Source: docs/driver-js/02-basics/01-basic-tour.md
Description: 通过 steps 和 drive 方法创建 Driver.js 多步骤页面导览，讲解 element、popover、title、description、side、align 等常用配置。

Driver.js 的多步骤引导由两部分组成：

- `steps`：描述每一步高亮哪个元素、显示什么内容。
- `drive()`：启动引导流程。

## 准备页面元素

假设页面里有三个需要说明的区域：

```html
<header id="top-nav">顶部导航</header>
<button id="create-project">创建项目</button>
<section id="project-list">项目列表</section>
```

## 定义步骤并启动

```js
import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver({
  showProgress: true,
  steps: [
    {
      element: "#top-nav",
      popover: {
        title: "顶部导航",
        description: "这里可以切换工作区、搜索内容和打开个人设置。",
        side: "bottom",
        align: "start",
      },
    },
    {
      element: "#create-project",
      popover: {
        title: "创建项目",
        description: "点击这个按钮创建一个新的项目。",
        side: "left",
        align: "center",
      },
    },
    {
      element: "#project-list",
      popover: {
        title: "项目列表",
        description: "你创建或参与的项目会显示在这里。",
        side: "top",
        align: "start",
      },
    },
  ],
});

document.querySelector("#start-tour").addEventListener("click", () => {
  driverObj.drive();
});
```

## 代码演示

点击演示中的“开始引导”按钮，可以看到一个完整的多步骤页面导览。

[在线代码演示](/driver-js/demos/1-basic-tour.html)

## Step 的基本结构

一个 step 通常包含：

| 字段 | 说明 |
| --- | --- |
| `element` | 要高亮的元素，可以是 CSS 选择器，也可以是 DOM 元素 |
| `popover` | 弹层配置对象 |
| `popover.title` | 弹层标题 |
| `popover.description` | 弹层正文 |
| `popover.side` | 弹层相对目标元素的位置 |
| `popover.align` | 弹层在该方向上的对齐方式 |

`element` 也可以省略。没有目标元素的步骤会把弹层显示在页面中心，适合做欢迎语或总结页。

```js
const driverObj = driver({
  steps: [
    {
      popover: {
        title: "欢迎",
        description: "接下来用一分钟了解这个控制台。",
      },
    },
    {
      element: "#create-project",
      popover: {
        title: "创建项目",
        description: "从这里开始。",
      },
    },
  ],
});
```

## 何时启动 Tour

常见启动时机有三种：

| 时机 | 适合场景 |
| --- | --- |
| 用户点击帮助按钮 | 用户主动学习，不打扰正常操作 |
| 新用户首次进入页面 | 入门型后台、工作台、编辑器 |
| 新功能发布后 | 对新入口或重要变化做提示 |

首次自动启动时，建议用 `localStorage` 记录是否已经展示过：

```js
const TOUR_KEY = "dashboard-tour-shown";

if (!localStorage.getItem(TOUR_KEY)) {
  driverObj.drive();
  localStorage.setItem(TOUR_KEY, "1");
}
```

## 编写步骤的原则

- 每一步只解释一个元素。
- 标题尽量短，正文说明用户能做什么。
- 不要把完整帮助文档塞进弹层。
- 关键按钮或危险操作需要明确说明后果。
- 引导步骤通常控制在 3 到 6 步更容易读完。