[RFC] New Component: Tour 漫游式引导

[MadCcc]

Summary

新增 Tour（漫游式引导）组件。

Motivation

对于拥有复杂功能的网页，或者推出新功能的网站，引导用户认识新的特性并学习新功能的用法非常重要。因此 Tour（漫游式引导）组件应运而生，主要用于引导用户认识网页中的某个或某些部分具有什么样的功能。

API

Tour

属性	类型	默认值	说明
steps	TourStepProps[]	-	引导步骤
open	boolean	-	受控打开引导（与 current 受控分开）
current	number	-	受控当前处于哪一步
onChange	(current: number) => void	-	步骤改变时的回调，current为改变前的步骤，next为改变后的步骤
onClose	(current: number) => void	-	关闭引导时的回调
onFinish	() => void	-	完成引导时的回调
mask	boolean	true	整体是否启用蒙层
arrow	boolean| { pointAtCenter: boolean}	true	整体是否显示箭头，包含是否指向元素中心的配置
type	default| primary	default	整体类型，影响底色与文字颜色

TourStep 引导步骤卡片

属性	类型	默认值	说明
target	() => HTMLElement| HTMLElement	-	获取引导卡片指向的元素
arrow	boolean| { pointAtCenter: boolean}	true	是否显示箭头，包含是否指向元素中心的配置
cover	ReactNode	-	展示的图片或者视频
title	ReactNode	-	标题
description	ReactNode	-	主要描述部分
placement	left| leftTop | leftBottom | right| rightTop| rightBottom| top| topLeft| topRight| bottom | bottomLeft| bottomRight	bottom	引导卡片相对于目标元素的位置
onClose	Function	-	关闭引导时的回调函数
mask	boolean	true	是否启用蒙层，默认跟随 Tour 的 mask 属性
type	default| primary	default	类型，影响底色与文字颜色
nextButtonProps	{ children: ReactNode; onClick: Function }	{ children: '下一步' }	下一步按钮的属性
prevButtonProps	{ children: ReactNode; onClick: Function }	{ children: '上一步' }	上一步按钮的属性
className	string	-	-
style	React.CSSProperties	-	-

Basic Example

基础用法

import React, { useRef } from React;
import { Button, Tour } from 'antd';
import { LinkOutlined } from '@ant-design/icons';

export default () => {
  const createRef = useRef<HTMLButtonElement>(null);
  const updateRef = useRef<HTMLButtonElement>(null);
  const deleteRef = useRef<HTMLButtonElement>(null);
  
  return (
    <div>
      <Button type="primary" ref={createRef}>Create</Button>
      <Button ref={updateRef}>Update</Button>
      <Button danger ref={deleteRef}>Delete</Button>
      <Tour
        steps={[
          {
            title: '创建',
            description: '创建一条数据',
            target: () => createRef.current,
          },
          {
            title: '更新',
            cover: <img src="example.com" />,
            description: (
              <div>
                <span>更新一条数据</span>
                <Button type="link">
                  帮助文档
                  <LinkOutlined />
                </Button>
              </div>
            ),
            target: () => updateRef.current,
          },
          {
            title: '删除',
            cover: <video src="example.com" />,
            description: (
              <div>
                <span>危险操作：删除一条数据</span>
                <Button type="link">
                  帮助文档
                  <LinkOutlined />
                </Button>
              </div>
            ),
            target: () => deleteRef.current,
          },
        ]}  
      />
    </div>
  );
}

Detailed Design

模态与非模态

• 模态模式
  • 打开时自带一层蒙层，可通过 maskClosable 控制是否可点击蒙层关闭 Tour。打开时其他元素不可点击。
  • 引导卡片默认白色底，黑色字，在黑色蒙层上较为突出。

• 非模态模式
  • 打开时没有蒙层，所有页面上的元素均可点击，不阻断。
  • 引导卡片默认信息色底，白色字，在原本的背景上较为突出。

引导卡片的各个区域对应的 API

1. cover；
2. title；
3. description；
4. description；
5. 无，内置组件，用于指示当前处于哪一步和总共多少步；
6. next button 和 prev button；
7. close button，onClose 可以赋予关闭时回调；
8. arrow;
9. 目标元素，通过 target指定；
10. 蒙层，模态模式特有，可以通过 mask={false} 关闭蒙层。

目标元素不在视窗内时

通过 scrollIntoView 拉到视窗内

实现任意定位

TourStep 的 placement只提供相对于 target的相对定位，如果需要自定义位置，比如绝对定位位于屏幕中央，可以通过 style自定义 position和位置来实现。





另外如果不指定 target，引导卡片会自动位于屏幕中央。

How we teach this

1. 在 React-Component 中新增 tour 组件，利用 rc-trigger 等底层组件实现功能；
2. 在 antd v5 中引入 rc-tour 并添加样式。

Drawbacks

No obvious drawbacks yet.

Bonus

Tour

属性	类型	默认值	说明
renderStep	(current: number) => ReactNode	-	自定义步骤进度显示

[zombieJ]

onChange 这个应该是先目标，剩下才是先前。感觉现在是暂时不用提供先前的 arg

[zombieJ]

nonModal 拆一下，一个是 mask，另一个是 type

[zombieJ]

nextButtonText 这类看看能不能合成一个属性，nextButtonProps。Modal 里因为是先有的 okText 后有的 okButtonProps 其实挺怪异的

[zombieJ]

onNext 这个具体一些是怎么回调的？看起来是点击？
onNext => onNextClick?

[MadCcc]

目前看只有点击会触发，可以改成 onNextClick

[hanwenbo]

一个页面有多个亮点需要考虑，比如高亮多个checkbox，属于一组，目前市面上的引导都很难改造出来

[MadCcc]

多个亮点怎么确定卡片的指向？

[kiner-tang]

感觉同一组的值考虑一个亮点就好了吧，如果有多个亮点，大概率说明想要介绍的点本身就有区别，为何不拆成多个步骤呢？

[kiner-tang]

分页指示器只需要支持指示点吗？不用支持分页按钮模式么？

[SignDawn]

或许设计两种？
或者留个 render prop ?

[kiner-tang]

恩恩，如果操作指引步骤比较多的时候，感觉还是这种分页指示器或者是形如：3/15这样的显示会更友好，用户能够明确知道，当前是第几个，总共有几个。

[kiner-tang]

或许我们可以使用pagination属性指定dot、index、number风格类型的内置指示器，并允许使用渲染函数覆盖内置指示器实现自定义。
pagination: false | 'dot' | 'index' | 'number' | ((idx: number, action: ActionGuideAction) => ReactNode)，
若未指定该属性，使用默认的dot风格指示器

[heiyu4585]

需要支持第一步点击跳转到第三步么

[kiner-tang]

可以提供一个go: (idx: number) => void;类似这样的api跳转目标步

[kiner-tang]

感觉除了上一步、下一步按钮之外，是不是还需要提供一个跳过的按钮，用户可能在当前浏览器看过了操作指引，当因为一些原因，清理了本地缓存或更换浏览器甚至更换电脑，此时可以允许用户直接跳过操作指引，免得每次更换宿主环境都要强制重看一遍。
可以增加一个属性：canSkip?: boolean

[heiyu4585]

点击关闭按钮能满足么

[kiner-tang]

关闭按钮应该也是可以满足的，但是否有一些情况，强制用户必须看完操作指引，不能跳过的情况呢？是不是额外增加一个closable?: boolean的配置，默认为true，如果某些场景不允许关闭的场景可以设置为false

[gabschne]

Looks great so far! Just my two cents on this:

另外如果找不到 target，引导卡片会自动位于屏幕中央。

I'm not sure if the translation I got is correct, as my Chinese is a bit rusty (lol), but it sounds like a troubleshooting mode when a target is specified but cannot be found. However, I think specifying one should be optional by design.
A modal-like step would be very useful for an introduction step or the end of the tour, for example. There could also be some information or steps in between that just don't belong to a target:

Also, I would suggest two more APIs for the TourStep component: onStepEnter and onStepExit (...haven't thought much about the names, so there might exist better ones...). The first would be executed when/before a step is displayed, the other when/before it is closed or exited. They would be helpful for steps where it is necessary to perform tasks, such as opening a menu and closing it afterwards. Sometimes such simple actions would be too much noise as own steps in the tour, so you want to do it automatically.

This can also be implemented using the onChange prop, but these interfaces would improve the developer experience. In addition, refactorings and reordering steps wouldn't require further changes and are likely to be less bug-prone than relying on indicies.

[MadCcc]

Could you provide more real use case for onStepEnter and onStepExit, which we may call beforeChange and afterChange?

[gabschne]

Based of the names you suggested and to clarify it: I suggested the APIs for the TourStep component, NOT the parent Tour one.

As examples, practically every (UI) component can be cited here that has to be brought from state A to state B when entering or leaving a step:

• opening or closing drawer
• expanding an expandable,
• inserting text into a search field,
• etc.

As I've already written in my first post, this can be implemented using the onChange API, but the developer experience isn't great at all, because you'll have to use the indicies and a switch..case or if..else if statement:

<Tour steps={steps} onChange={(current: number, next: number) => {
    switch (current) {
        case 1:
        [...]
        case 2:
        [...]
        case 3:
        [...]
        case 4:
        [...]
    }
    switch (next) {
        case 1:
        [...]
        case 2:
        [...]
        case 3:
        [...]
        case 4:
        [...]
    }
} />

Changing the order of the steps will require adjusting the indicies in the onChange method. However, the code readability is bad and this location is likely a bug factory.

Giving the TourStep prop a key property, like other components already have (e.g. Menu), would be an improvement:

<Tour steps={steps} onChange={(current: string, next: string) => {
    switch (current) {
        case "step-foo":
        [...]
        case "step-bar":
        [...]
        case "step-hello":
        [...]
        case "step-world":
        [...]
    }
    switch (next) {
        case "step-foo":
        [...]
        case "step-bar":
        [...]
        case "step-hello":
        [...]
        case "step-world":
        [...]
    }
} />

Changing the order of the steps wouldn't require an adjustment of the onChange method anymore. In addition, the readability is way higher because a step can be identified with it's key (name).
Nevertheless, I'm not a big fan of this solution tbh. There's no protection at coding or compile time against using the same key multiple times. You might even not notice it directly at runtime.

Although the APIs I suggested may add some overhead to the code, they solve the mentioned drawbacks above:

const steps = [
    {
        [...]
        onEnter: () => { [...] },
        onExit: () => { [...] }
    },
    {
        [...]
        onEnter: openMenu,
        onExit: closeMenu
    },
    {
        [...]
        onEnter: openDrawer
    },
    {
        [...]
        onEnter: enterTextIntoSearchField
    }
];

[...]

<Tour steps={steps} onChange={(current: number, next: number) => {[...]}} />

Every method is directly connected to the corresponding step and reordering the steps will include the onEnter and onExit actions. Note that the proposed APIs are not intended to replace the global onChange API.

[0529bill]

有可以设定target在视窗中center的选项吗?

[0529bill]

我想要設定的是，讓target element scroll到視窗中間

[0529bill]

因為目前default的 scrollIntoView是 start，有參數可以設定scrollIntoView的值讓target element至中嗎

[kiner-tang]

目前暂时是不支持配置的，不过感觉可以加一下，@MadCcc，你看看是否要提个PR支持一下自定义scrollIntoView参数呢？

[kiner-tang]

#39980 5.2.0将会支持自定义 @0529bill

[0529bill]

@kiner-tang thanks!!

[jiesia]

遇到没有办法在一个组件内声明 steps 的情形：无法在一个组件内获取子组件中需要标记 ref 进行引导的子组件，steps 中的 target 能否更灵活一些，直接 document.getElementById

[MadCcc]

ref 只是举的例子，target 只需要能够提供 HTMLElement 就行，无所谓方法。

[jiesia]

仔细看了下文档的类型说明确实可以，是否可以在案例中也说明一下

[wulisensen]

话说 为啥只限制在 Button元素上呢？我想挂在 Input上，报错了，有啥解决办法吗？ @MadCcc

[MadCcc]

需要提供 DOM 元素而不是 react 组件。

[jasonhungg]

請問被導覽的地方 要如何移除 旁邊被包圍的的白色區塊呢