前端漫游式引导功能

背景

绝大多数项目在进行大版本迭代更新的时候，在用户第一次访问的时候会给一个引导提示的功能，告诉用户我们新增了哪些功能，或者说我们的网站应该怎么使用操作，通过下一步下一步的形式，引导用户了解整个网站的功能。

在web前端项目中，这种功能基本是必备的，我们日常进行前端项目开发用到的技术大多React+AntDesign。 以及Vue+Element，今天这里会给大家介绍一个适配任何技术体系的通用的漫游式引导功能的开发方案。

React方案

1、Ant Design V5及以上版本

如果这里你的项目采用的是蚂蚁金服 Ant Design 框架V5及以上的UI框架，那么在最新的AntD文档中，官网已经明确了V5的版本开始提供漫游式引导组件，可以在项目中直接使用。具体使用方法可参考官网文档。

2、Ant Design V5以下版本

如果你的项目使用的是蚂蚁金服 Ant Design 框架V5以下的版本，通过官网文档我们可以发现，官方在V5以下并没有提供漫游式引导组件的API，此时就可选择以下通用的技术方案。以下教程我们以Ant Design Pro脚手架创建的simple项目进行演示。UI框架版本为4版本。只要V5版本以下均适用。

2.1 介绍

React-Joyride 是一个适用于React技术研发的前端漫游式交互引导插件，通过极简API来实现绝大多数网页引导气泡式功能。

2.2 安装

在项目中进行插件安装

yarn add react-joyride --save-dev

// 或

npm install react-joyride --save-dev

2.3 开发

漫游式引导功能，一般作为整个项目全局公共使用模块，故在项目中，我们将其封装为一个独立的组件，便于在任何地方使用，同时也便于后期的集中维护。 在项目src/components下新建立Tour目录，里面为引导组件核心功能，写入index.tsx文件，内容如下：

import Joyride from 'react-joyride';
interface IProps {
  run: boolean;
  onSetStatus: any;
}

const Tour = (props: IProps) => {
  const { run = true, onSetStatus } = props;
  const steps = [
    {
      target: '.tour-first',
      content: '这里是操作的第一步！',
      disableBeacon: true,
      hideCloseButton: true,
    },
    {
      target: '.tour-second',
      content: '这里是操作的第二步！',
    },
  ];

  const handleJoyrideCallback = (data) => {
    const { action } = data;
    if (action == 'reset') {
      onSetStatus(false);
    }
  };

  return (
    <>
      <Joyride
        steps={steps}
        continuous={true}
        locale={{ back: '返回', close: '关闭', last: '结束', next: '下一步', skip: '跳过' }}
        styles={{
          options: {
            primaryColor: '#2F54EB',
            textColor: '#000',
          },
        }}
        showSkipButton={true}
        disableOverlayClose={true}
        run={run}
        callback={handleJoyrideCallback}
      />
    </>
  );
};

export default Tour;

部分常用属性参考如下：

属性	参考值
steps	[{ target: '.tour-first', //目标元素--通过类名指向目标元素 content: '这里是操作的第一步！', // 气泡填充内容 string		ReactDOM disableBeacon: true, // true代表自动执行（不展示操作引导按钮） hideCloseButton: true,//隐藏步骤中的关闭按钮（why？前面步骤如果不隐藏此按钮，点击后会自定光标到下一步 }]更多设置请参考插件API文档
continuous	true		false 是否自动开启下一步
showSkipButton	true		false 是否自动展示‘跳过’/skip 按钮
locale	{back: '返回', close: '关闭', last: '结束', next: '下一步', skip: '跳过'} 配置气泡操作按钮上的文案，默认为英文，可通过此配置变更为中文
disableOverlayClose	true		false 是否允许点击遮罩层关闭气泡
run	是否开启引导功能（一般通过此属性决定是否开启引导功能）
callback	function 当引导的动作发生变更触发此回调，可通过参数判断当前行为进行额外处理
styles	{ options: { primaryColor: '#2F54EB', textColor: '#000' } css样式设置，可设置按钮、文案颜色。 更多设置参考以下默认配置： const defaultOptions = { arrowColor: '#fff', backgroundColor: '#fff', beaconSize: 36, overlayColor: 'rgba(0, 0, 0, 0.5)', primaryColor: '#f04', spotlightShadow: '0 0 15px rgba(0, 0, 0, 0.5)', textColor: '#333', width: undefined, zIndex: 100, };

更多属性功能配置，请参考官网API文档

2.4 使用

在2.3完成组件开发后，我们可以直接使用该组件。 我们在src/pages目录下新建demo目录，写入index.tsx，并在config目录下routes.ts下写入该路径的路由配置。 index.tsx内容如下：

import { useState } from 'react';
import { Button, Row, Col } from 'antd';
import Tour from '@/components/Tour/index';

const Demo = () => {
  const [status, setStatus] = useState(false);

  const start = () => {
    setStatus(true);
  };

  const onSetStatus = (data: boolean) => {
    setStatus(data);
  };

  return (
    <Row>
      <Col span={8}>
        <Button type="primary" onClick={start}>
          开始
        </Button>
      </Col>
      <Col span={8}>
        <Button className="tour-first">第一步</Button>
      </Col>
      <Col span={8}>
        <Button className="tour-second">第二步</Button>
      </Col>

      <Tour run={status} onSetStatus={onSetStatus} />
    </Row>
  );
};

export default Demo;

此时刷新页面，访问demo页面，会看到如下界面

点击开始按钮，查看引导功能，正常执行

可根据文档API修改部分属性，进行查看效果。例如，此时我们展示引导步骤，新增如下属性配置：

showProgress={true}

到此适配React+AntDesign V5以下版本的漫游式引导功能就开发完成了。

Vue方案

1、通用方案

因为在ElementUI框架官网中，无论Vue3.x或者Vue2.x版本文档中，均为发现其提供漫游引导式功能组件，故这里我们直接提供适配于Vue+Element语言的漫游引导功能，以下教程示例项目采用vue cli 构建，语言采用vue2.0版本，供参考。

1.1 安装

npm install vue-tour
// 或者
yarn add vue-tour

1.2 引入

在main.js文件中引入相关插件，代码如下：

import Vue from 'vue'
import VueTour from 'vue-tour'

require('vue-tour/dist/vue-tour.css')

Vue.use(VueTour)

1.3 使用

在views中我们新建立一个demo页面，进行功能演示，代码如下：

<template>
  <div>
    <el-button type="primary" @click="start">开始</el-button>
    <el-button type="success" class="first_step">第一步</el-button>
    <el-button type="info" class="second_step">第二步</el-button>
    <el-button type="warning" class="third_step">第三步</el-button>
    <v-tour name="myTour" :steps="steps" :options="myOptions" :callbacks="myCallbacks"></v-tour>
  </div>
</template>

<script>
export default {
  name: "my-tour",
  data() {
    return {
      steps: [
        {
          target: ".first_step", // 目标元素
          header: {
            title: "Get Started" // 气泡标题
          },
          content: "这是第一步的引导!" //内容，可以使用模版组件
        },
        {
          target: ".second_step",
          content: "这是第2步的引导!"
        },
        {
          target: ".third_step",
          content: "这是第三步的引导！",
          params: {
            placement: "top",
            highlight: true // 高亮目标元素
          }
        }
      ],
      myOptions: {
        useKeyboardNavigation: false,
        labels: {
          buttonSkip: "跳过",
          buttonPrevious: "上一步",
          buttonNext: "下一步",
          buttonStop: "结束"
        }
      },
      myCallbacks: {
        onStart: this.isReady,
        onSkip: this.isOver,
        onFinish: this.isOver,
        onPreviousStep: this.onPreviousStep,
        onNextStep: this.onNextStep,
        onStop: this.onStop
      }
    };
  },
  methods: {
    start() {
      this.$tours["myTour"].start();
    },
    isReady() {},
    isOver() {},
    onPreviousStep() {},
    onNextStep() {},
    onStop() {}
  },
  mounted: function() {}
};
</script>

此时点击开始可以看到如下效果：

配置解释如下：

属性	参考值
name	自定义，例如：myTour，用于后面操作引导对象，参考如下： 启动引导功能：this.$tours["myTour"].start();
steps	引导步骤
options	配置，可以设置文案等
callbacks	操作回调，不同操作行为执行函数不同

更多属性配置，文档学习请参考官方API文档 到此适配Vue+Element 的漫游式引导功能就开发完成了。