【react.js + hooks】useGuide 创建用户引导视图

有的时候用户可能对网站上的一些操作流程感到困惑，这时候我们需要为用户创建引导视图。为了插入指引而专门去更改组件的渲染函数，显然是不合逻辑的，创建指引视图应该是一种对源代码低侵入的行为，我们可以遵循某一套约定，使之变成一种类插件化的机制。

useGuide 设计思路

为需要引导的网页元素指定唯一的 id，当引导开始时，创建一个全屏的遮罩，当引导到该元素时，高亮该元素，并创建一个辅助元素挂载到具有唯一 id 的该目标元素上，当指引切换或结束时，移除辅助元素。

要实现这个思路，我们需要以下数据：

获取每一步的目标元素 id 和辅助元素
记录当前的步数
记录每次高亮的元素 id，之后取消高亮

useGuide 准备工作

createRoot 工具函数：

import ReactDOM from "react-dom";let createRoot = (targetDocument: Element) => {return {render: (element: JSX.Element) => {ReactDOM.render(element, targetDocument);},};
};if ("createRoot" in ReactDOM) {// Adapt to React 18createRoot = ReactDOM.createRoot as typeof createRoot;
}

ReactDOM 的 createRoot 方法，在 React 18 + 处于 deprecated

useGuide

代码实现

定义 useGuide 传参和返回

传参：
- steps - 数组，每个元素代表指引的每一步对应的所有目标元素id，这一步的名字，data为这一步搭载的可能需要的数据，renders为每一个目标元素各自的辅助元素的渲染函数
- callback - 指引步变化时的回调函数
- config - 配置项
  - containerStyle - 为辅助元素套的一层 div，指定该 div 的样式
  - containerClassName - 指定该辅助元素的套壳 div 的 css 类名
  - maskConfig - 指定当前步时，遮罩层的一些属性
返回（数组）：
- [0] number - 当前步
- [1] Guider - 对一些引导行为封装的对象

function useGuide(steps: Step[],callback?: StepCallback,config?: {containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;maskConfig?: MaskConfig;}
): [number, Guider]export type Render = {id: string;render: (id: string,name: string,data: any,ids: string[]) => React.ReactNode;containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;
};export type Step = {ids?: string[];name?: string;data?: any;renders?: Render[];
};export interface Guider {start: () => void;stop: () => void;next: () => void;last: () => void;go: (step: number) => void;
}export type MaskConfig = {backgroundColor?: string;opacity?: number;zIndex?: number;pointerEvents?:| "none !important"| "auto"| React.CSSProperties["pointerEvents"];
};export type StepCallback = (step: number, stepConfig: Step) => void;

创建遮罩层

先定义一个 ref 来保存遮罩层元素的 dom

  const maskRef = useRef<HTMLDivElement | null>(null);

定义一个创建遮罩mask的函数，传入遮罩层配置

const createMask = (config?: MaskConfig) => {const mask = document.createElement("div");mask.style.position = "fixed";mask.style.top = "0";mask.style.right = "0";mask.style.bottom = "0";mask.style.left = "0";mask.style.backgroundColor = "rgba(0, 0, 0, 0.5)";mask.style.zIndex = "999";mask.style.cursor = "default";mask.style.userSelect = "none";mask.style.webkitUserSelect = "none";mask.style.pointerEvents = "none !important";const maskConfig = config;if (maskConfig) {if (maskConfig.backgroundColor) {mask.style.backgroundColor = maskConfig.backgroundColor;}if (maskConfig.opacity) {mask.style.opacity = maskConfig.opacity.toString();}if (maskConfig.zIndex) {mask.style.zIndex = maskConfig.zIndex.toString();}}return mask;
};

其中，默认设置遮罩层的鼠标时间为绝对 none，图层高度为 999。

渲染辅助元素

记录当前步：

const [step, setStep] = useState(-1);

检测当前步，并挑选出对应的辅助元素渲染器，并渲染：

useEffect(() => {const currentStep = steps[step];const rootDom = document.body;const mask = createMask(config?.maskConfig);if (currentStep && rootDom) {rootDom.appendChild(mask);maskRef.current = mask;}currentStep?.ids?.forEach((id) => {const element = document.getElementById(id);if (element) {element.style.zIndex = "1000";}});const renders = currentStep?.renders?.map(({ id, render, containerStyle, containerClassName }) => {const target = document.getElementById(id);const container = document.createElement("div");container.style.zIndex = "1001";container.style.position = "relative";if (config?.containerStyle) {Object.keys(config.containerStyle).forEach((key) => {// @ts-ignorecontainer.style[key] = config.containerStyle[key];});}if (containerStyle) {Object.keys(containerStyle).forEach((key) => {// @ts-ignorecontainer.style[key] = containerStyle[key];});}if (config?.containerClassName) {container.className = config.containerClassName;}if (containerClassName) {container.className = containerClassName;}// 默认挂载到目标元素上target?.appendChild(container);if (container && target) {// @ts-ignorecreateRoot(container).render(// @ts-ignorerender(id, currentStep.name, currentStep.data, currentStep.ids));return container;}});callback?.(step, currentStep);return () => {if (currentStep && rootDom && maskRef.current) {rootDom.removeChild(mask);maskRef.current = null;}renders?.forEach((elem) => elem?.remove());};}, [step, steps]);

其中，每次渲染，我们需要获取到目标元素，并创建一个包装容器 div，借助 createRoot 渲染并挂载辅助元素到目标元素上。(为什么要包装？辅助render可能返回一个被 Pure 元素包裹的组件)

函数返回

return [step,{start,stop,next,last,go,},];

封装引导行为

封装常用的开始（约定step数组是顺序的，索引 -1 时不处于引导中），结束，上一步，下一步和跳转某步的操作。

const start = useCallback(() => setStep(0), []);const stop = useCallback(() => setStep(-1), []);const next = useCallback(() => setStep((prev) => Math.min(prev + 1, steps.length - 1)),[steps]);const last = useCallback(() => setStep((prev) => Math.max(prev - 1, 0)), []);const go = useCallback((step: number) => setStep(Math.max(0, Math.min(step, steps.length - 1))),[steps]);

高亮目标元素

我们需要存储元素被高亮前的 zIndex，后续恢复它们

const zIndexes = useRef<Map<string, string>>(new Map());

在渲染前拉高 zIndex，并记录原zIndex，渲染结束或组件卸载后恢复

// 监测当前步的那个副作用
useEffect(()=>{//...currentStep?.ids?.forEach((id) => {const element = document.getElementById(id);if (element) {zIndexes.current.set(id, element.style.zIndex); // 记录原值element.style.zIndex = "1000"; //拉高图层以实现高亮}});return () => {//...renders?.forEach((elem) => elem?.remove());// 当不再需要引导元素时，恢复原始的 zIndexzIndexes.current.forEach((zIndex, id) => {const element = document.getElementById(id);if (element) {element.style.zIndex = zIndex;}});zIndexes.current.clear();}
}, [step, steps])

对目标元素的包装模式

上面采取了用 createRoot 和原生 js 插入辅助元素的方案，接下来我们引入另一种方案，创建一个高阶的Pure组件（Target组件）包裹目标组件，将辅助元素通过 createPortal 挂载在下面：

拓展 Guider：
暴露 step, 传参的config，register 和 unregister，后两个 api 是让 Target 向 guider 注册自己，告诉 guider 某个 id 归它管了，你不需要渲染辅助元素了。

export interface Guider {start: () => void;stop: () => void;next: () => void;last: () => void;go: (step: number) => void;// Not for user to usestep: number;options?: {steps?: Step[];callback?: StepCallback;config?: {containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;maskConfig?: MaskConfig;};};register: (id: string) => void;unregister: (id: string) => void;
}

Target，用于包裹目标组件

interface TargetProps {id: string;guider: Guider;children: React.ReactNode;
}export const Target: React.FC<TargetProps> = ({ id, guider, children }) => {const [guide, setGuide] = useState<React.ReactNode>(null);const { step, options } = guider;const { steps } = options || {};const currentStep = steps?.[step];useEffect(() => {guider.register(id);const render = currentStep?.renders?.find((r) => r.id === id)?.render;if (render) {// @ts-ignoresetGuide(render(id, currentStep.name, currentStep.data, currentStep.ids));} else {setGuide(null);}return () => {guider.unregister(id);};}, [id, currentStep]);const element = document.getElementById(id);return (<>{children}{element && ReactDOM.createPortal(guide, element)}</>);
};

useGuide 内部需要存储被 Target 注册的 id：

const registered = useRef<Set<string>>(new Set());
const register = useCallback((id: string) => {registered.current.add(id);
}, []);const unregister = useCallback((id: string) => {registered.current.delete(id);
}, []);return [step,{start,stop,next,last,go,step,options: { steps, callback, config },register,unregister,},];

在 useGuide 渲染时跳过注册的 id :

const renders = currentStep?.renders?.map(({ id, render, containerStyle, containerClassName }) => {if (registered.current.has(id)) {// 如果已经注册，跳过渲染步骤return;}//...

useGuide 完整代码

import React, { useState, useEffect, useCallback, useRef } from "react";
import ReactDOM from "react-dom";let createRoot = (targetDocument: Element) => {return {render: (element: JSX.Element) => {ReactDOM.render(element, targetDocument);},};
};if ("createRoot" in ReactDOM) {// Adapt to React 18createRoot = ReactDOM.createRoot as typeof createRoot;
}export type Render = {id: string;render: (id: string,name: string,data: any,ids: string[]) => React.ReactNode;containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;
};export type Step = {ids?: string[];name?: string;data?: any;renders?: Render[];
};export interface Guider {start: () => void;stop: () => void;next: () => void;last: () => void;go: (step: number) => void;// Not for user to usestep: number;options?: {steps?: Step[];callback?: StepCallback;config?: {containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;maskConfig?: MaskConfig;};};register: (id: string) => void;unregister: (id: string) => void;
}export type MaskConfig = {backgroundColor?: string;opacity?: number;zIndex?: number;pointerEvents?:| "none !important"| "auto"| React.CSSProperties["pointerEvents"];
};export type StepCallback = (step: number, stepConfig: Step) => void;const createMask = (config?: MaskConfig) => {const mask = document.createElement("div");mask.style.position = "fixed";mask.style.top = "0";mask.style.right = "0";mask.style.bottom = "0";mask.style.left = "0";mask.style.backgroundColor = "rgba(0, 0, 0, 0.5)";mask.style.zIndex = "999";mask.style.cursor = "default";mask.style.userSelect = "none";mask.style.webkitUserSelect = "none";mask.style.pointerEvents = "none !important";const maskConfig = config;if (maskConfig) {if (maskConfig.backgroundColor) {mask.style.backgroundColor = maskConfig.backgroundColor;}if (maskConfig.opacity) {mask.style.opacity = maskConfig.opacity.toString();}if (maskConfig.zIndex) {mask.style.zIndex = maskConfig.zIndex.toString();}}return mask;
};function useGuide(steps: Step[],callback?: StepCallback,config?: {containerStyle?: Partial<CSSStyleDeclaration>;containerClassName?: string;maskConfig?: MaskConfig;}
): [number, Guider] {const [step, setStep] = useState(-1);const maskRef = useRef<HTMLDivElement | null>(null);const zIndexes = useRef<Map<string, string>>(new Map());const registered = useRef<Set<string>>(new Set());const register = useCallback((id: string) => {registered.current.add(id);}, []);const unregister = useCallback((id: string) => {registered.current.delete(id);}, []);useEffect(() => {const currentStep = steps[step];const rootDom = document.body;const mask = createMask(config?.maskConfig);if (currentStep && rootDom) {rootDom.appendChild(mask);maskRef.current = mask;}currentStep?.ids?.forEach((id) => {const element = document.getElementById(id);if (element) {zIndexes.current.set(id, element.style.zIndex);element.style.zIndex = "1000";}});const renders = currentStep?.renders?.map(({ id, render, containerStyle, containerClassName }) => {if (registered.current.has(id)) {// 如果已经注册，跳过渲染步骤return;}const target = document.getElementById(id);const container = document.createElement("div");container.style.zIndex = "1001";container.style.position = "relative";if (config?.containerStyle) {Object.keys(config.containerStyle).forEach((key) => {// @ts-ignorecontainer.style[key] = config.containerStyle[key];});}if (containerStyle) {Object.keys(containerStyle).forEach((key) => {// @ts-ignorecontainer.style[key] = containerStyle[key];});}if (config?.containerClassName) {container.className = config.containerClassName;}if (containerClassName) {container.className = containerClassName;}// 默认位于父元素的最后target?.appendChild(container);if (container && target) {// @ts-ignorecreateRoot(container).render(// @ts-ignorerender(id, currentStep.name, currentStep.data, currentStep.ids));return container;}});callback?.(step, currentStep);return () => {if (currentStep && rootDom && maskRef.current) {rootDom.removeChild(mask);maskRef.current = null;}renders?.forEach((elem) => elem?.remove());// 当不再需要引导元素时，恢复原始的 zIndexzIndexes.current.forEach((zIndex, id) => {const element = document.getElementById(id);if (element) {element.style.zIndex = zIndex;}});zIndexes.current.clear();};}, [step, steps]);const start = useCallback(() => setStep(0), []);const stop = useCallback(() => setStep(-1), []);const next = useCallback(() => setStep((prev) => Math.min(prev + 1, steps.length - 1)),[steps]);const last = useCallback(() => setStep((prev) => Math.max(prev - 1, 0)), []);const go = useCallback((step: number) => setStep(Math.max(0, Math.min(step, steps.length - 1))),[steps]);return [step,{start,stop,next,last,go,step,options: { steps, callback, config },register,unregister,},];
}export default useGuide;interface TargetProps {id: string;guider: Guider;children: React.ReactNode;
}export const Target: React.FC<TargetProps> = ({ id, guider, children }) => {const [guide, setGuide] = useState<React.ReactNode>(null);const { step, options } = guider;const { steps } = options || {};const currentStep = steps?.[step];useEffect(() => {guider.register(id);const render = currentStep?.renders?.find((r) => r.id === id)?.render;if (render) {// @ts-ignoresetGuide(render(id, currentStep.name, currentStep.data, currentStep.ids));} else {setGuide(null);}return () => {guider.unregister(id);};}, [id, currentStep]);const element = document.getElementById(id);return (<>{children}{element && ReactDOM.createPortal(guide, element)}</>);
};

useGuide 使用示例

以下代码创建了一个九宫格引导视图（$css 是全局注册的 @emotion）

import useGuide from "@hooks/useGuide";const View = () => {const [currentStep, guider] = useGuide(Array.from({ length: 9 }, (_, i) => i + 1).map((i) => ({ids: [`s${i}`],name: `Step ${i}`,data: {},renders: [{id: `s${i}`,render(id, name, data, ids) {console.log(id, name, data, ids);const onClick = i === 9 ? guider.stop : guider.next;return (<divcss={$css`display: flex;align-items: center;width: fit-content; position: absolute;background: #fff;padding: 4px 20px;border-radius: 6px;transform: translate(-50%, 50%);`}><div css={$css`width: 60px;`}>{name}</div><divcss={$css`padding: 4px 12px; &:hover { cursor: pointer; background: #eee;  border-radius: 4px;}`}onClick={onClick}>{i === 9 ? "End" : "Next"}</div></div>);},},],})));return (<div css={style.containerCss}><div id="s1" css={style.boxCss("red")} onClick={guider.start}>Start</div><div id="s2" css={style.boxCss("green")}>2</div><div id="s3" css={style.boxCss("blue")}>3</div><div id="s4" css={style.boxCss("black")}>4</div><div id="s5" css={style.boxCss("purple")}>5</div><div id="s6" css={style.boxCss("pink")}>6</div><div id="s7" css={style.boxCss("cyan")}>7</div><div id="s8" css={style.boxCss("magenta")}>8</div><div id="s9" css={style.boxCss("orange")}>9</div></div>);
};module style {export const containerCss = $css`
display: grid;
grid-template-columns: 1fr 1fr 1fr;
grid-template-rows: 1fr 1fr 1fr;
gap: 10px;
width: 300px;
height: 300px;
`;export const boxCss = (color: string) => $css`
color: ${color};
display: flex;
justify-content: center;
align-items: center;
border-radius: 6px;
cursor: pointer;
`;
}

效果演示： useGuide九宫格引导视图
Bingo ! 一个实用的 useGuide 就这样实现了！需要注意的是，使用 Target 包裹目标元素和不使用将导致最终渲染结果的一定差异，因为 Target 不再创建 div 包裹辅助元素，因此不建议混用 Target 和无 Target。