前言

最近调研 React 新手引导常用开源库，对比发现 react-joyride 可自定义程度最高，适合深度使用。

react-joyride 官方 Demo 效果：

Demo 地址：github.com/gilbarbara/…

过去一年下载量前几名的新手引导开源库

以 2024.3.31 作为统计日

开源库	Star	npm 日下载	开源协议
react-joyride	6.4k	249k	MIT
shepherd.js	11.8k	91k	MIT
driver.js	20.4k	44k	MIT
intro.js	22.6k	85k	GPL
reactour	3.7k	45k	MIT

• 从 npm 日下载量看 react-joyride 遥遥领先，下载量是第二名 shepherd.js 的 2.5 倍以上。
• intro.js 是 GPL 协议，不购买它的商业协议在企业应用使用，要开放相关源码，使用时要很注意 📢

零、快速上手 🚀

第一步、导入

import React from 'react';
import Joyride from 'react-joyride';

export default function App() {
  return (
     <Joyride steps={steps} />
  );
}

第二步、定义引导步骤

const steps = [
  {
    target: '.my-first-step', // 可以指定Class或ID，或直接传入Dom元素
    content: 'This is my awesome feature!',
  },
  {
    target: '.my-other-step',
    content: 'This another awesome feature!',
  },
];

<Joyride steps={steps} />

一、React 与 TypeScript 支持度 🏡

• react-joyride 源码使用 React 和 TypeScript 实现，支持度最高的

  

• intro.js 源码使用 TypeScript 实现，未使用 React

  

• shepherd.js 源码使用 React 和 JavaScript 实现，不支持 TypeScript，也没有导出声明文件

• reactour ⽀持 React Hooks，源码⽤ JavaScript 实现，支持 TypeScript 类型声明

• driver.js 源码使用 TypeScript 实现，未使用 React

二、自定义样式 🌺

自定义样式是上面新手引导库的标配，都是支持的。以 react-joyride 为例

  const customOptions = {
    arrowColor: 'rgb(251 196 131)', // 定义箭头颜色
    backgroundColor: 'rgb(251 244 174)', // 定义背景颜色
    beaconSize: 20, // 光亮图标
    overlayColor: 'rgba(0, 0, 0, 0.8)', // 遮罩颜色
    primaryColor: 'red', // 主色调
    spotlightShadow: '0 0 15px rgba(0, 0, 0, 0.5)', // spotlight 高亮阴影
    textColor: 'blue', // 文本颜色
    width: undefined, // 宽度
    zIndex: 100, // zIndex
  };

  <Joyride
    callback={handleJoyrideCallback}
    continuous
    hideCloseButton
    run={run}
    scrollToFirstStep
    showProgress
    showSkipButton
    steps={steps}
    styles={{
      options: customOptions,
    }}
  />

三、自定义引导组件 🔧

自定义 React 组件是 react-joyride 独特功能，其他库都不具备的。

shepherd.js 和 driver.js 支持 JavaScript 操作 HTML 元素和覆盖 CSS Class 样式，开发难度高，不易维护 (从 MVVM 时代退回到 HTML+JS+CSS 时代 →→)

1、自定义指引组件

import Joyride, { BeaconRenderProps, TooltipRenderProps } from 'react-joyride';

// 1. 设置引导组件 keyframes CSS 动画
const pulse = keyframes`
  0% {
    transform: scale(1);
  }

  55% {
    background-color: rgba(255, 100, 100, 0.9);
    transform: scale(1.6);
  }
`;
// 2. 设置引导组件CSS样式，背景色、宽高、圆角等
const Beacon = styled.span`
  animation: ${pulse} 1s ease-in-out infinite;
  background-color: rgba(255, 27, 14, 0.6);
  border-radius: 50%;
  display: inline-block;
  height: 3rem;
  width: 3rem;
`;

// 3. 定义引导组件
const BeaconComponent = forwardRef<HTMLButtonElement, BeaconRenderProps>((props, ref) => {
  return <BeaconButton ref={ref} {...props} />;
});

export () => (
  <div>
    <ReactJoyride
      // 引入引导组件
      beaconComponent={BeaconComponent}
      // beaconComponent={BeaconComponent as React.ElementType<BeaconRenderProps>} for TS
      ...
    />
  </div>
);

详细代码地址: react-joyride.com/custom

2、自定义 Tooltip 组件

默认 Tooltip 组件

自定义 Tooltip 组件

功能实现代码介绍:

import Joyride, {
  TooltipRenderProps,
} from 'react-joyride';

function Tooltip({
  backProps, // 返回参数
  continuous, // 是否持续
  index, // 第几步
  isLastStep, // 是否最后一步
  primaryProps, // 主要按钮默认参数
  skipProps, // 忽略按钮默认参数
  step, // step 对象
  tooltipProps, // tooltipProps 默认参数
}: TooltipRenderProps) {
  return (
    <div
      {...tooltipProps}
      // 自定义 Tooltip 组件容器样式
      style={{
        backgroundColor: 'white',
        maxWidth: 420,
        minWidth: 290,
        borderRadius: 20,
      }}
    >
      <div style={{ padding: 20 }}>
        {/* Tooltip 标题 */}
        {step.title && <h3 style={{ color: 'primary', padding: 0 }}>{step.title}</h3>}
        {/* Tooltip 展示内容 */}
        {step.content && <div>{step.content}</div>}
      </div>
      {/* Tooltip 底部按钮容器 */}
      <div
        style={{
          backgroundColor: 'lightskyblue',
          padding: 10,
          borderBottomLeftRadius: 20,
          borderBottomRightRadius: 20,
        }}
      >
        <div style={{ display: 'flex', justifyContent: 'space-between' }}>
          {/* 不是最后一步，支持跳过引导 */}
          {!isLastStep && (
            <Button {...skipProps} size="sm">
              <FormattedMessage id="skip" />
            </Button>
          )}
          <div>
            {/* 不是第一步，支持返回 */}
            {index > 0 && (
              <Button {...backProps} size="sm">
                <FormattedMessage id="back" />
              </Button>
            )}
            {/* 如果后面还有引导，展示为 next，否则展示为 close */}
            <Button {...primaryProps} size="sm">
              <FormattedMessage id={continuous ? 'next' : 'close'} />
            </Button>
          </div>
        </div>
      </div>
    </div>
  );
}

  <Joyride
    beaconComponent={BeaconComponent}
    callback={handleJoyrideCallback}
    showSkipButton
    steps={steps}
    // 自定义 tooltip 组件
    tooltipComponent={Tooltip}
  />

详细代码地址: react-joyride CustomComponents by NeoYu

四、参考资料

• docs.react-joyride.com/ react-joyride 官方文档
• github.com/gilbarbara/… react-joyride github 地址
• github.com/shepherd-pr…
• github.com/kamranahmed…
• github.com/usablica/in…
• github.com/elrumordela…

---

本文到这里就结束了 Thanks♪(･ω･)ﾉ

react-joyride 使用细节上还有可深入讨论的技术点，比如只有一个回调函数，使用上如何进行封装，如何获取当前在引导状态的第几步等问题，感兴趣的小伙伴欢迎评论，一起学习 📚 ！