README

EasyGuide

一个简单，便捷，可维护的用户指导。

Why?

我想很多时候你可能都不需要 EasyGuide.js。因为市场上已经有很好用用户指导的组件了，比如：intro.js，而且它足够优秀！

但是为什么我还要写这个组件库？这是当你尝试了市场上的其他用户指导的组件以后，你会发现有一种试用场景：在不能更改需要指导的对象代码的前提下，它们没有办法实现。我写这个框架的目的也是基于这个初衷！没错，EasyGuide.js 不会入侵需要指导对象的目标代码。基于这个特性，对于我们嵌入不属于我们自己的页面，或者需要有大量的代码需要更改，还需要做引导的时候有着非常重要的意义！

How?

EasyGuide 设计理念：指导页面逻辑无关，根据用户的屏幕，页面定位，完成指导功能。因为跟页面没有逻辑关系，因此，EasyGuide 有两种模式：管理员模式 用户模式

管理员模式：管理员在页面维护需要指导用户的信息。需要后端辅助保存数据；
用户模式：在这个模式下只能查看管理员给你维护好的指导数据。

Live DEMO

线上 demo： http://www.abners.cn/easy-guide/demo

文档：http://www.abners.cn/easy-guide

Getting started

首先 npm 安装：

npm i easy-guide

然后 import 引入和初始化指导：

import EasyGuide from 'easy-guide';
import 'easy-guide/dist/easy-guide.css';

// 创建一个实例：
const guide = new EasyGuide({
  ...Config
})

Config

EasyGuide 配置：

参数	说明	类型	默认值
guideList	指导数据列表	array<guideItem>	`[]`
mode	指导当前所处的模式	'READ' \| 'MAINTAIN'	'READ'
currentIndex	查看模式下，当前指导对应的数组下标	number	0
beforeCreate	指导创建前（必须自己实现）	function(guideInstance, guideItem)	`null`
beforeNext	`下一步` 前	function(oldIndex, newIndex, guideList)	`null`
afterNext	`下一步` 后	function(oldIndex, newIndex, guideList)	`null`
beforePrev	`上一步` 前	function(oldIndex, newIndex, guideList)	`null`
afterPrev	`上一步` 后	function(oldIndex, newIndex, guideList)	`null`
guildClose	指导关闭	function(currentIndex, guideItem, guideList)	`null`
onGuideListChange	指导数据变化	function(action, guideItem, guideList)	`null`

action

onGuideListChange 派发的事件行为，是一个字符串的枚举类型：'create', 'modify', 'delete'

guideItem

每一项指导至少包含这些内容：

{
  id: String((new Date()).getTime()),
  content: '',
  width: 0.15,
  widthUtil: '%',
  height: 120,
  heightUtil: 'px',
  left: 0.5,
  leftUtil: '%',
  top: 200,
  topUtil: 'px',
  orderNumber: 1,
  fixFlag: 'N',
  contentPosition: '_eG_guide-1'
}

Api

EasyGuide.show(mode)

展示指导，需要传入展示对应的模式 action
EasyGuide.destroy()

销毁指导组件
EasyGuide.setGuideList(list)

设置指导的列表
EasyGuide.setGuideItem(guideItem)

更改指定 guideItem
EasyGuide.getGuideList()

获取全部指导数据
EasyGuide.getGuideItemById()

通过 ID 获取指导数据
EasyGuide.getConfig()

获取当前实例配置

Example

import EasyGuide from 'easy-guide';
import 'easy-guide/dist/easy-guide.css';

const guide = new EasyGuide({
  mode: 'READ', // 初始化进入查看模式
  guideList: [], // TODO: 放置远程拉取到的数据
  beforeCreate: async (guideInstance, guideItem) => {
    // 1. 把即将要创建的数据保存到后端
    const res = await fetch({
      url: 'http://www.xxx.com',
      method: 'POST',
      body: guideItem // 对象传递格式，依据后端接口而定
    })

    // 2. 后端返回成功以后，需要把数据返回给 EasyGuide 渲染.
    //    新的数据必须带 `id` 字段, 如果数据格式不同，需要自己实现转换
    return res.newGuideItem
  },
  onGuideListChange: async (action, data) => {
    if (action === 'modify') {
      await fetch({
        url: 'http://www.xxx.com',
        method: 'POST',
        body: guideItem
      })
    } else if (action === 'delete') {
      ...
    } else {
      ...
    }
  },
  ...
})

// 展示维护模式
guide.show('MAINTAIN');

// 展示查看模式
guide.show('READ')

// 销毁
guide.destroy()

Changelog

v0.0.8 (Feb 3, 2021): 完善文档
v0.0.7 (Feb 2, 2021): 组件支持配置；修复若干 Bugs
v0.0.1 (Jan 20, 2021): 初始化发布组件

License

EasyGuide is available under the MIT license.

Usage no npm install needed!