/e-guide

user guide

Primary LanguageTypeScriptMIT LicenseMIT

e-guide

介绍

用于用户导航的高亮组件

特性

  • 基于原生 JS
  • 只有一个主方法
  • 遮罩层和弹出层功能任意搭配

安装

# npm
npm install e-guide

# yarn
yarn install e-guide

# 直接使用CDN服务获取js文件，全局变量为Guide
<script src="https://cdn.jsdelivr.net/npm/e-guide"></script>
<script src="https://unpkg.com/e-guide"></script>

API

属性/方法 描述 类型 默认值
guide 导航高亮主函数 (target: string | Element | Array<{ element: string | Element; options?: Options }>, options: Options) => GuideReturn
target 导航高亮目标元素, 当为 string 时，该参数需要为元素选择器，当为 Element 时，需要为 DOM 元素， 当为数组时，开启导航步骤功能 string | Element | Array<{ element: string | Element; options?: Options }>Object
options 导航高亮配置, 分为遮罩层、弹出层及公共配置 { mask?: Mask, popover?: Popover, scrollDisabled?: boolean, beforeClose?: () => void }
options.mask 遮罩层配置 { closeable: boolean, bgColor: string, withAnimation: boolean, padding: number | [number, number ] } { padding: 10, withAnimation: true, closeable: true, bgColor: 'rgb(0, 0, 0)' }
options.mask.padding 目标元素高亮外边距，当为数组时，可配置上下边距和左右边距 number | [number, number ] 10
options.mask.closeable 遮罩层是否可关闭 boolean true
options.mask.highlightDisabled 高亮区域是否可以操作, 默认可以操作 boolean false
options.mask.bgColor 遮罩层背景颜色 string 'rgb(0, 0, 0)'
options.mask.withAnimation 是否开启动画 boolean true
options.popover 弹出层配置 { title: string, content: string, position: ''bottom' | 'bottomRight' | 'bottomLeft' | 'top' | 'topRight' | 'topLeft' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom'', closeable: boolean, withAnimation: boolean } { position: 'bottom', title: "", content: "", withAnimation: true, closeable: true }
options.popover.title 弹出层标题 string ""
options.popover.content 弹出层内容 string ""
options.popover.control 开启步骤时，是否开启内置控制前进后退的按钮 boolean true
options.popover.withAnimation 是否开启动画 boolean true
options.popover.closeable 弹出层是否可关闭, false 时不会有关闭按钮 boolean true
options.popover.position 弹出层定位, 支持 12 个方向 'bottom' | 'bottomRight' | 'bottomLeft' | 'top' | 'topRight' | 'topLeft' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom' 'bottom'
options.popover.showStepTip 步骤开启时，展示步骤进度提示信息钮 boolean true
options.scrollDisabled 弹出层及遮罩层是否禁用滚动 boolean false
options.beforeClose 弹出层及遮罩层关闭前回调，步骤模式下，外层 beforeClose 会覆盖内层 beforeClose，此时会传入当前步骤下标 (currentStepIndex?: number) => void
options.onNextStep 下一步回调，可执行异步操作 (currentStepIndex: number) => void
options.onPrevStep 上一步回调，可执行异步操作 (currentStepIndex: number) => void
options.stepGuideId 手动配置此次步骤演示的唯一 id string
options.showOnce 只展示一次，需要配置 stepGuideId，否则无效，guide内部会将该id进行本地缓存，若清空缓存，则会展示高亮导航 boolean false
options.noMoreShow 是否展示不再提示按钮，需要配置 stepGuideId，否则无效 boolean false
options.noMoreText 不再提示文案 string '不再提示'
GuideReturn 导航返回对象，该对象提供一些方法控制导航功能 object
GuideReturn.close 控制弹出层及遮罩层的关闭方法 () => void
GuideReturn.setStepTo 在步骤功能开启时返回，设置弹出层及遮罩层的当前步骤位置 (index: number, mathAdd: boolean) => void
GuideReturn.getCurrentStepIndex 获取当前步骤下标 () => number

例子

常规使用

import { guide } from 'e-guide'

// 只开启遮罩层
guide('#example', {
  mask: {
    withAnimation: true,
    padding: [20, 10],
  },
  popover: null,
})

// 只开启弹出层
guide('#example', {
  mask: null,
  popover: {
    title: '这是标题',
    content: '你好',
    closeable: false,
    position: 'top',
  },
})

// 同时开启遮罩层和弹出层
guide('#example', {
  mask: {
    withAnimation: true,
    padding: [20, 10],
  },
  popover: {
    title: '这是标题',
    content: '你好',
    closeable: false,
    position: 'top',
  },
})

// 目标DOM元素
guide(document.getElementById('example'), {
  mask: {
    withAnimation: true,
    padding: [20, 10],
  },
  popover: {
    title: '这是标题',
    content: '你好',
    closeable: false,
    position: 'top',
  },
})

// 使用步骤指引
guide([
  {
    element: '#example',
    options: {
      mask: {
        withAnimation: true,
        padding: [20, 10],
      },
      popover: {
        title: '这是标题',
        content: '你好',
        closeable: false,
        position: 'top',
      },
    },
  },
  {
    element: '#example1',
    options: {
      mask: {
        withAnimation: true,
        padding: 20,
      },
      popover: {
        title: '这是标题2',
        content: 'hello',
        closeable: false,
        position: 'bottom',
      },
    },
  },
  {
    element: '#example2',
    options: {
      mask: {
        withAnimation: true,
        padding: 20,
      },
      popover: {
        title: '这是标题3',
        content: 'guide',
        position: 'left',
      },
    },
  },
])

步骤控制

// 步骤上一步、下一步的回调控制, 支持异步操作
guide(
  [
    {
      element: '#example',
      options: {
        mask: {
          withAnimation: true,
          padding: [20, 10],
        },
        popover: {
          title: '这是标题',
          content: '你好',
          closeable: false,
          position: 'top',
        },
      },
    },
    {
      element: '#example2',
      options: {
        mask: {
          withAnimation: true,
          padding: 20,
        },
        popover: {
          title: '这是标题3',
          content: 'guide',
          position: 'left',
        },
      },
    },
  ],
  {
    onNextStep: async (currentStepIndex) => {
      if (currentStepIndex === 0) {
        await wait(1000)
      }
    },
    onPrevStep: async (currentStepIndex) => {
      if (currentStepIndex === 1) {
        await wait(1000)
      }
    },
  },
)

步骤只展示一次配置

guide(
  [
    {
      element: '#example',
      options: {
        mask: {
          withAnimation: true,
          padding: [20, 10],
        },
        popover: {
          title: '这是标题',
          content: '你好',
          closeable: false,
          position: 'top',
        },
      },
    },
    {
      element: '#example2',
      options: {
        mask: {
          withAnimation: true,
          padding: 20,
        },
        popover: {
          title: '这是标题3',
          content: 'guide',
          position: 'left',
        },
      },
    },
  ],
  {
    // 手动配置步骤id作为本次指引的唯一标识，用于只展示一次逻辑
    stepGuideId: 'guide-id',
    showOnce: true,
  },
)

不再提示配置

guide(
  [
    {
      element: '#example',
      options: {
        mask: {
          withAnimation: true,
          padding: [20, 10],
        },
        popover: {
          title: '这是标题',
          content: '你好',
          closeable: false,
          position: 'top',
        },
      },
    },
    {
      element: '#example2',
      options: {
        mask: {
          withAnimation: true,
          padding: 20,
        },
        popover: {
          title: '这是标题3',
          content: 'guide',
          position: 'left',
        },
      },
    },
  ],
  {
    // 手动配置步骤id作为本次指引的唯一标识，用于只展示一次逻辑
    stepGuideId: 'guide-id',
    noMoreShow: true,
    // 可配置文案
    noMoreText: '不再',
  },
)

在 React 中使用

// 可以使用ref获取到目标DOM，也可以使用选择器
import { guide } from 'e-guide'
import React, { useRef } from 'react'

function App() {
  const ref = useRef()

  const onClick = () => {
    guide(ref.current, {
      scrollDisabled: false,
      mask: {
        padding: [10, 20],
      },
    })
  }

  return (
    <button ref={ref} onClick={onClick}>
      指引
    </button>
  )
}

运行示例

git clone git@github.com:Jcanno/e-guide.git

// 使用vscode命令打开项目
code e-guide

// 优先使用pnpm安装依赖
pnpm install
// 也可以使用yarn
yarn install

// 运行项目示例
pnpm dev 或 yarn dev