StepsGuide：一个像跟屁虫一样的组件 - DevUI

DevUI 是一款面向企业中后台产品的开源前端解决方案，它倡导沉浸、灵活、至简的设计价值观，提倡设计者为真实的需求服务，为多数人的设计，拒绝哗众取宠、取悦眼球的设计。如果你正在开发 ToB 的工具类产品，DevUI 将是一个很不错的选择！

引言

近期对 ProjectMan 业务的工作项搜索/过滤功能做了优化，用 DevUI 组件库新推出的 CategorySearch 组件替换了之前复杂繁琐的交互方式，实现了搜索、过滤、过滤条件显示3个功能的整合，能够有效提升用户的操作效率和体验。

以下是新旧过滤器的效果对比：

旧版过滤器

新版过滤器

从新旧过滤器的对比可以看出，两者相差很大，这个旧版的过滤器已经在线上运行多年，用户已经习惯了这种交互方式，如果贸然上一个几乎是全新的东西，势必会挑战用户的使用习惯，即使新版过滤器拥有简单易用、操作效率高、体验好等众多优点。

由于要改变用户习惯，前期很可能还是会受到部分用户的排斥和抵触，为了尽可能让用户平滑过渡到新版过滤器，需要增加一个简单的用户指引，让用户通过几个简单的步骤，快速了解新版过滤器的使用方式。

1 单步骤用户指引

用户指引应该是一个比较通用的场景，先到组件库里找下有没有可以直接用的组件。

1.1 寻找合适的组件

打开DevUI官网的组件总览页面：

https://devui.design/components/zh-cn/overview

先尝试搜索🔍关键字指引，找到一个操作指引组件：

点击进入StepsGuide组件的详情页面：

何时使用里写了该组件的使用场景：

业务推出新特性，或复杂的业务逻辑需要指引用户时使用。

和我们的场景是一样的，直接拿来用吧。

1.2 看组件Demo，了解组件基本用法

先看下第一个基本用法的Demo：

<d-button
  bsStyle="common"
  dStepsGuide
  [pageName]="'step-basic-demo'"
  [steps]="steps"
  [stepIndex]="0"
  [dStepsGuidePosition]="'top'"
  (operateChange)="operateChange($event)"
  (click)="reset(0)"
>
  Step 1
</d-button>

从这个Demo，我们大致可以一窥其使用方式：

• 以指令（dStepsGuide）的方式使用
• 指令放在哪个元素上，就在它上面展示一个指引框
• dStepsGuidePosition属性应该是控制指引框的位置
• steps应该是配置指引步骤数据源
• stepIndex应该是表示当前的元素是第几个步骤
• pageName暂时还不知道有什么用
• operateChange是一个事件，还不知道有什么用

看完HTML文件，再看下TS文件：

export class BasicComponent implements OnInit {
  ...
  steps = [
      {
        title: 'Step 1',
        content: 'Guide Content',
      },
      {
        title: 'Step 2',
        content: 'Guide Content',
      },
      {
        title: 'Step 3',
        content: 'Guide Content',
      },
  ];
  constructor(private stepService: StepsGuideService) {}

  ngOnInit() {
    this.stepService.currentIndex.subscribe((index) => (this.currentStep = index));
    /* 由于整个demo是在一个页面内显示多个操作指引序列，因此需要在初始化时重置显示状态 */
    localStorage.setItem('devui_guide_step-position-demo', '0');
    localStorage.setItem('devui_guide_step-custom-demo', '0'); /* 设置第二个序列为不显示状态 */
    localStorage.removeItem('devui_guide_step-basic-demo'); /* 设置第一个序列为显示状态 */
    this.stepService.setSteps(this.steps); /* 将步骤数据设置为第一个序列的内容 */
    this.stepService.setCurrentIndex(0); /* 设置当前序列显示步骤为第一个步骤 */
  }
  ...
}

从TS文件里可以看到steps步骤数据源的结构，steps是一个对象数组，每一个数组项表示一个指引步骤，里面包含该步骤的标题和内容。

组件初始化事件里面写了一些逻辑，有点复杂，我们先不看。

根据现有的知识，应该能先用起来。

1.3 先用起来再说

比如我想给下面的搜索框元素加一个指引：

大致效果如下：

1.3.1 第一步是先引入组件模块

import { StepsGuideModule } from 'ng-devui';

@NgModule({
  ...
  imports: [
    ...
    StepsGuideModule,
  ],
  ...
})
export class MainContentHeadModule { }

1.3.2 然后加上dStepsGuide指令和相应的属性

先只加一个steps试试看：

<d-search 
  dStepsGuide
  [steps]="steps"
></d-search>

steps = [
  {
    title: '新功能介绍：搜索框',
    content: `
      <p>1、过滤功能迁移至搜索框中啦</p>
      <p>2、在搜索框中，您可输入关键词或添加筛选条件查询所需要的工作项</p>
    `,
  },
];

发现什么效果都没有。

1.3.3 调整参数，达到我们想要的效果

回过头来看组件Demo，组件初始化时做了一些事情：

  ngOnInit() {
    this.stepService.currentIndex.subscribe((index) => (this.currentStep = index));
    /* 由于整个demo是在一个页面内显示多个操作指引序列，因此需要在初始化时重置显示状态 */
    localStorage.setItem('devui_guide_step-position-demo', '0');
    localStorage.setItem('devui_guide_step-custom-demo', '0'); /* 设置第二个序列为不显示状态 */
    localStorage.removeItem('devui_guide_step-basic-demo'); /* 设置第一个序列为显示状态 */
    this.stepService.setSteps(this.steps); /* 将步骤数据设置为第一个序列的内容 */
    this.stepService.setCurrentIndex(0); /* 设置当前序列显示步骤为第一个步骤 */
  }

最后一行代码似乎是用来控制显示哪一个步骤指引的：

this.stepService.setCurrentIndex(0); /* 设置当前序列显示步骤为第一个步骤 */

我们加上这一行试试看。

import { StepsGuideService } from 'ng-devui';

constructor(
  private stepService: StepsGuideService,
) {}

ngOnInit(): void {
  this.stepService.setCurrentIndex(0); /* 设置当前序列显示步骤为第一个步骤 */
}

发现还是没效果。

再加上调用setSteps方法那一行试试：

ngOnInit(): void {
  this.stepService.setSteps(this.steps); /* 将步骤数据设置为第一个序列的内容 */
  this.stepService.setCurrentIndex(0); /* 设置当前序列显示步骤为第一个步骤 */
}

还是不行，再试试加上stepIndex属性：

    <d-search 
      dStepsGuide
      [steps]="steps"
      [stepIndex]="0" // 新增的
    ></d-search>

终于有效果了：

不过默认位置显示在元素上方，被挡住了，可以设置下dStepsGuidePosition属性，调整下指引的位置：

    <d-search 
      dStepsGuide
      [steps]="steps"
      [stepIndex]="0"
      dStepsGuidePosition="bottom" // 新增的
    ></d-search>

这回正常了。

效果和我们想要的一模一样：

1.3.4 小结

回顾一下，为了实现单步骤用户指引，我们使用了dStepsGuide指令的三个参数：

• steps 步骤数组，是一个对象数组，里面包含步骤的标题（title）和内容（content）
• stepIndex 显示第几个步骤
• dStepsGuidePosition 显示位置（一共有8个方位）

为了设置当前步骤为第一个步骤，我们调用了stepService的两个方法：

• setSteps(this.steps) 将步骤数据设置为第一个序列的内容
• setCurrentIndex(0) 设置当前步骤为第一个步骤

这就是实现单步骤用户指引所需要知道的全部知识。

2 多步骤指引

这时产品说一个步骤不够，要加一个，主要有两个要求：

• 第一个步骤里面点击下一步，可以跳到下一个步骤
• 第二个步骤有一个返回上一步的按钮

为了实现多步骤指引，我们不需要学习任何多余的API，只需要简单地在steps中增加一个步骤，并设置第二个步骤的stepIndex为1即可。

<d-search 
  dStepsGuide
  dStepsGuidePosition="bottom"
  [steps]="steps"
  [stepIndex]="0"
></d-search>
<!--新增的步骤-->
<d-button
  dStepsGuide
  dStepsGuidePosition="bottom"
  [steps]="steps"
  [stepIndex]="1"
>新建项目</d-button>

steps = [
  {
    title: '新功能介绍：搜索框',
    content: `
      <p>1、过滤功能迁移至搜索框中啦</p>
      <p>2、在搜索框中，您可输入关键词或添加筛选条件查询所需要的工作项</p>
    `,
  },
  // 新增的步骤
  {
    title: '新功能介绍：新建项目',
    content: `
      <p>点击“新建项目”按钮，即可跳转到新建项目页面</p>
    `,
  },
];

效果如下：

是不是非常简单？

3 跟随效果

以上实现会有一个问题：

如果步骤的目标元素是动态变化的，比如它的位置变了，宽高变了，指引不会跟着变。

效果如下：

这时需要用到StepsGuide组件的另一个API：observerDom

这个API会让指引步骤秒变跟屁虫：

目标元素在哪儿，指引步骤就跟到哪儿。

API文档用了大段文字来描述这个observerDom的用途，其实就是把指引步骤的浮框变成“跟屁虫”😄

<d-search 
  dStepsGuide
  dStepsGuidePosition="bottom"
  [steps]="steps"
  [stepIndex]="0"
  [observerDom]="observerDom" // 新增的
></d-search>

observerDom;

ngOnInit(): void {
  // 新增的，把搜索框的外层元素设置成observerDom，这样只要它里面的任何元素发生变化，导致了搜索框位置发生变化，步骤指引的浮框都会跟着变化
  this.observerDom = document.querySelector('.main-content');
  
  this.stepService.setSteps(this.steps);
  this.stepService.setCurrentIndex(0);
}

效果如下：

不仅仅是搜索框宽度变化，其他变化导致的搜索框位置的变化也会触发步骤指引的跟随：

是不是非常有意思？

接下来我们就来看看这个简单却很有意思的“跟屁虫”组件还有哪些能力。

4 StepsGuide组件的其他API

关注StepsGuide组件的介绍，没有比它的API文档写得更清楚的了。

它一共有12个属性API，一个事件API。

属性API：

• steps 步骤数组
• stepIndex 当前步骤索引
• dStepsGuidePosition 指引步骤的位置
• observerDom 跟随效果
• pageName 用来标识操作指引，跨页面（或路由）时会用到
• leftFix 位置修复
• topFix 位置修复
• zIndex 指引步骤的层级
• targetElement 指定目标元素，当需要为动态生成的元素添加指引时会用到
• scrollElement 指引信息跟随滚动定位的容器元素
• scrollToTargetSwitch 是否自动滚动页面至指引信息显示的位置
• extraConfig 扩展配置，用于隐藏上一步按钮和步骤圆点图标

事件API：

• operateChange 指引步骤中的按钮事件，需要自定义下一步的动作时会用到

这些API的具体用法详见StepsGuide组件的Demo：

https://devui.design/components/zh-cn/steps-guide/demo

如果你的业务中也有新特性要发布，需要增加用户指引，不妨试试这个有趣的跟屁虫组件吧😜！

也欢迎使用DevUI新发布的DevUI Admin系统，开箱即用，10分钟搭建一个美观大气的后台管理系统！

加入我们

我们是DevUI团队，欢迎来这里和我们一起打造优雅高效的人机设计/研发体系。招聘邮箱：[e-mail]。

文/DevUI Kagol

往期文章推荐

《Quill富文本编辑器的实践》

《如何解决异步接口请求快慢不均导致的数据错误问题？》

《号外号外！DevUI Admin V1.0 发布啦！》

《CategorySearch分类搜索组件初体验》

《让我们一起建设 Vue DevUI 项目吧！》