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团队，欢迎来这里和我们一起打造优雅高效的人机设计/研发体系。招聘邮箱：muyang2@huawei.com。
文/DevUI Kagol
往期文章推荐
- 点赞
- 收藏
- 关注作者
评论（0）