Simple novice guide

一个简单的新手引导库。

安装

npm i simple-novice-guide

使用

import SimpleNoviceGuide from 'simple-novice-guide'

new SimpleNoviceGuide({
    steps: [
        {
            element: '#id',
            title: '我是标题',
            text: '我是信息',
            img: '我是图片'
        }
    ]
}).start()

如果要使用umd格式的文件，可以安装完后在node_modules/simple-novice-guide/dist/目录里选择使用dist.js或dist.min.js文件。

本地开发

1.开启ts编译

npm run tsc

2.开启打包编译

npm run build

3.开启页面服务

npx http-server -e js -c-1

访问[ip][port]/index.html。

然后就可以愉快的修改代码了，不过没有热更新功能哦，所以记得修改后要刷新页面。

文档

创建实例

const noviceGuide = new SimpleNoviceGuide(options)

参数options

对象类型，可以传递以下选项：

| 属性 | 类型 | 默认值 | 描述 | | ---------------- | -------- | ------------------ | ------------------------------------------------------------ | | steps | array | | 步骤数据，必填，信息数据见下表 | | padding | number | 10 | 高亮元素和信息框元素的内边距，单位px | | margin | number | 10 | 高亮元素和信息框元素之间的间距，单位px | | boxShadowColor | string | rgba(0, 0, 0, 0.5) | 高亮元素的box-shadow颜色 | | transition | string | all 0.3s ease-out | 高亮元素过渡效果 | | borderRadius | string | 5px | 高亮元素和信息框元素的圆角 | | highlightElClass | string | | 要添加到高亮元素上的css类名 | | backgroundColor | string | #fff | 信息框元素的背景颜色 | | infoElClass | string | | 要添加到信息框元素上的css类名 | | prevText | string | 上一步 | 上一步按钮的文字 | | nextText | string | 下一步 | 下一步按钮的文字 | | completeText | string | 完成 | 完成按钮的文字 | | showIndicator | boolean | true | 是否显示信息框内的指示器 | | zIndex | number | 9999 | 高亮元素和信息框的z-index | | useCustomInfo | boolean | false | 是否使用自定义的信息框，如果开启，需要传递getCustomInfoEl选项 | | getCustomInfoEl | function | null | 返回自定义信息框元素 |

options.steps属性

options.steps属性值需为一个对象数组，对象的结构如下：

| 属性 | 类型 | 默认值 | 描述 | | ------- | --------------------- | ------ | ------------------------------------------------------------ | | element | HTMLElement | string | | 该步骤需要高亮的html元素，可以是一个选择器，也可以是dom节点对象，如果当前步骤不需要高亮元素，也可以不传 | | title | string | number | | 当前步骤的标题 | | text | string | number | | 当前步骤的信息 | | img | string | | 当前步骤的图片 |

实例属性

noviceGuide.options

选项对象。

noviceGuide.steps

步骤列表数据。

noviceGuide.currentStepIndex

当前所在步骤的索引。

实例方法

noviceGuide.start()

开始。

noviceGuide.next()

下一步。

noviceGuide.prev()

上一步。

noviceGuide.jump(stepIndex: number)

跳转到指定步骤。

noviceGuide.done()

结束。

noviceGuide.isFirstStep()

是否是第一步。

noviceGuide.isLastStep()

是否是最后一步。

noviceGuide.on(eventName, (...args) => {})

监听事件。

事件发送继承的是eventemitter3，详细文档可以参考它的文档。

实例会发出的事件如下：

| 事件名 | 回调参数 | 描述 | | ------------------ | ------------------------- | ------------ | | before-step-change | stepIndex（当前步骤索引） | 即将切换步骤 | | after-step-change | stepIndex（当前步骤索引） | 步骤切换完毕 | | done | | 新手引导结束 |

noviceGuide.emit(eventName, ...args)

发送事件。

noviceGuide.off(eventName, fn?)

解除监听事件。

自定义信息框

如果内置的信息框无法满足你的需求，也可以自定义信息框，首先实例化时需要传递以下两个参数：

const noviceGuide = new SimpleNoviceGuide({
    useCustomInfo: true,
    getCustomInfoEl: async (step) => {
        return document.querySelector('.customInfoBox')
    }
})

getCustomInfoEl方法需要返回你自定义的信息框的节点，考虑到可能有异步的操作，所以统一返回一个Promise。

注意你自定义的信息框元素需要设置绝对定位，z-index也是必不可少的：

.customInfoBox {
    position: absolute;
    z-index: 99999;
}

然后需要在你的信息框中创建相应的上一步、下一步、完成的按钮，然后手动调用下列方法：

noviceGuide.prev()

noviceGuide.next()

noviceGuide.done()

通常还需要监听done事件来删除或隐藏你的自定义信息框：

noviceGuide.on('done', () => {
    customInfoBoxEl.style.display = 'none'
})