StepsGuide: a component like a worm-DevUI

DevUI is an open source front-end solution for enterprise middle and back-end products. It advocates immersion, flexibility, and design values. It encourages designers to serve real needs and serve the design of most people, rejecting grandstanding. Eye-pleasing design. If you are developing ToB of tools products, DevUI would be a very good choice!

introduction

Recently, the work item search/filter function of the ProjectMan business has been optimized. The CategorySearch component newly launched by the DevUI component library replaces the previous complicated and cumbersome interaction methods, and realizes the integration of the three functions of search, filtering, and filter condition display. Can effectively improve the user's operating efficiency and experience.

The following is a comparison of the effects of the old and new filters:

Legacy filter

New filter

From the comparison of the new and old filters, it can be seen that there is a big difference between the two. This old version of the filter has been running online for many years, and users have become accustomed to this kind of interaction. If you rush to add something that is almost brand new, it will definitely challenge users. Even if the new version of the filter has many advantages such as simple and easy to use, high operating efficiency, and good experience.

Due to the need to change user habits, some users may still be rejected and resisted in the early stage. In order to make the transition to the new version of the filter as smooth as possible for users, a simple user guide needs to be added, allowing users to quickly understand through a few simple steps. How to use the new filter.

1 One-step user guide

The user guide should be a more general scenario, first go to the component library to find out if there are any components that can be used directly.

1.1 Find the right component

Open the component overview page of DevUI official website:

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

First try to search for the 🔍keyword guide and find an operation guide component:

Click to enter the details page of the StepsGuide

The usage scenarios of this component are written in when to use:

When the business launches new features, or complex business logic needs to guide users to use.

The scene is the same as ours, so let's use it directly.

1.2 Look at the component Demo to understand the basic usage of the component

Let's take a look at the first demo of basic usage:

<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>

From this Demo, we can roughly get a glimpse of its usage:

• Use in the form of instructions ( dStepsGuide )
• On which element the instruction is placed, a guide box is displayed on it
• dStepsGuidePosition attribute should control the position of the guide frame
• steps should be the data source for the configuration guide step
• stepIndex should indicate which step is the current element
• pageName I don't know what's the use for the time being
• operateChange is an event, I don’t know what it is for

After reading the HTML file, look at the TS file:

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); /* 设置当前序列显示步骤为第一个步骤 */
  }
  ...
}

From the TS file, you can see the structure of the steps data source. Steps is an array of objects. Each array item represents a guide step, which contains the title and content of the step.

Some logic is written in the component initialization event, which is a bit complicated, so let's not look at it first.

According to the existing knowledge, it should be able to be used first.

1.3 Let's use it first

For example, I want to add a guideline to the following search box elements:

The general effect is as follows:

1.3.1 The first step is to introduce component modules

import { StepsGuideModule } from 'ng-devui';

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

1.3.2 Then add the dStepsGuide instruction and the corresponding attributes

Try adding only one steps first:

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

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

Found no effect.

1.3.3 Adjust the parameters to achieve the effect we want

Looking back at the component Demo, some things were done when the component was initialized:

  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); /* 设置当前序列显示步骤为第一个步骤 */
  }

The last line of code seems to be used to control which step guide is displayed:

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

Let's add this line and try.

import { StepsGuideService } from 'ng-devui';

constructor(
  private stepService: StepsGuideService,
) {}

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

Found that still to no avail.

Add the line that calls the setSteps method to try:

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

Still not working, try adding the stepIndex property:

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

Finally there is an effect:

However, the default position is displayed above the element and is blocked. You can set the dStepsGuidePosition property to adjust the position of the next guide:

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

This time it's normal.

The effect is exactly the same as what we want:

1.3.4 Summary

To recap, in order to implement the single-step user guidance, we used the three parameters of dStepsGuide

• steps The step array is an object array, which contains the title and content of the step
• stepIndex shows the first few steps
• dStepsGuidePosition display position (a total of 8 positions)

In order to set the current step as the first step, we call two methods of stepService:

• setSteps(this.steps) Set the step data to the content of the first sequence
• setCurrentIndex(0) Set the current step as the first step

This is all you need to know to implement a single-step user guide.

2 Multi-step guide

At this time, the product says that one step is not enough, and one needs to be added. There are two main requirements:

• Click Next in the first step to skip to the next step
• The second step has a button to return to the previous step

In order to implement multi-step guidance, we don't need to learn any redundant APIs, just simply add a step to steps and set the stepIndex of the second step to 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>
    `,
  },
];

The effect is as follows:

Is it very simple?

3 Follow effect

There will be a problem with the above implementation:

If the target element of the step changes dynamically, such as its position and width and height, the guidelines will not change accordingly.

The effect is as follows:

At this time, another API of the StepsGuide component is needed: observerDom

This API will make the guide step a follower in seconds:

Where the target element is, the guiding steps follow.

The API document uses a large paragraph of text to describe observerDom , which is actually to turn the floating frame that guides the steps into a "follower" 😄

<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);
}

The effect is as follows:

Not only the width of the search box changes, but also changes in the position of the search box caused by other changes will also trigger the follow-up of the step guide:

Is it very interesting?

Next, let's take a look at what other capabilities this simple but interesting "follower" component has.

4 Other APIs of the StepsGuide component

Pay attention to the introduction of the StepsGuide component, nothing is written more clearly API document

It has a total of 12 attribute APIs and one event API.

Property API:

• steps steps array
• stepIndex current step index
• dStepsGuidePosition guide the position of the step
• observerDom follow effect
• pageName is used to identify the operation guide, it will be used when crossing pages (or routing)
• leftFix position fix
• topFix position fix
• zIndex to guide the level of steps
• targetElement specifies the target element, which is used when you need to add guidelines for dynamically generated elements
• scrollElement guides the information to follow the scroll positioning of the container element
• scrollToTargetSwitch Whether to automatically scroll the page to the position where the guidance information is displayed
• extraConfig extended configuration, used to hide the previous step button and step dot icon

Event API:

• operateChange button event in the guide step, it will be used when you need to customize the next action

The specific usage of these APIs is detailed in the Demo of the StepsGuide component:

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

If there are new features to be released in your business and you need to add user guidance, you might as well try this interesting follower component😜!

Also welcome to use DevUI's newly released DevUI Admin system, out of the box, build a beautiful and atmospheric background management system in 10 minutes!

join us

We are the DevUI team, welcome to come here to build an elegant and efficient man-machine design/development system with us. Recruitment email: [e-mail].

Text/DevUI Kagol

Recommendations of previous articles

"Practice of Quill Rich Text Editor"

"How to solve the problem of data errors caused by the uneven speed of asynchronous interface requests? 》

"Extra nickname!" DevUI Admin V1.0 is released! 》

"CategorySearch category search component first experience"

"Let's build the Vue DevUI project together! 》