🔥 强烈推荐 react-joyride 开发新手引导

前言

最近调研 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 协议,不购买它的商业协议在企业应用使用,要开放相关源码,使用时要很注意 📢

零、快速上手 🚀

第一步、导入

js 复制代码
import React from 'react';
import Joyride from 'react-joyride';

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

第二步、定义引导步骤

js 复制代码
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 为例

js 复制代码
  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、自定义指引组件

jsx 复制代码
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 组件

功能实现代码介绍:

tsx 复制代码
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

四、参考资料


本文到这里就结束了 Thanks♪(・ω・)ノ

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

相关推荐
中微子5 小时前
🔥 React Context 面试必考!从源码到实战的完整攻略 | 99%的人都不知道的性能陷阱
前端·react.js
中微子6 小时前
React 状态管理 源码深度解析
前端·react.js
lichenyang4538 小时前
React移动端开发项目优化
前端·react.js·前端框架
天若有情6738 小时前
React、Vue、Angular的性能优化与源码解析概述
vue.js·react.js·angular.js
小和尚同志9 小时前
全网影视一网打尽!8.2K Star 的 LibreTV 让你甩开追剧烦恼
开源·github
说私域9 小时前
开源链动2+1模式与AI智能名片融合下的S2B2C商城小程序源码:重构大零售时代新生态
人工智能·重构·开源
国服第二切图仔10 小时前
基于文心开源大模型ERNIE-4.5-0.3B-Paddle私有化部署并构建一个企业智能客服系统
百度·开源·智能客服·知识库·文心大模型·paddle·gitcode
当牛作馬12 小时前
React——ant-design组件库使用问题记录
前端·react.js·前端框架
码字的字节12 小时前
阿里开源WebSailor:超越闭源模型的网络智能体新星
开源·阿里·websailor·网络智能体
CCF ODC12 小时前
第三届CCF夜莺开源创新论坛成功举办,夜莺V8正式发布
开源