E-guide NPM | npm.io

e-guide

介绍

用于用户导航的高亮组件

特性

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

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	boolean
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

guide tour

@babel/runtime use-jsx

@everything-registry/sub-chunk-1544 @zalastax/nolb-e-

2 years ago

2 years ago

2 years ago

2 years ago