在遇到网页内容有着较大调整的时候，往往需要一个导览功能去告诉用户，某某功能已经调整到另外一个位置。比较常规的办法是添加一个蒙层，高亮显示被调整的区域，然后通过文字介绍去完成引导。我们把这个功能称为“导览”，而 Smartour 则把这个导览的功能抽离出来，提供了一个开箱即用的解决方案。
项目地址：https://github.com/jrainlau/s...官方示例：https://jrainlau.github.io/sm...
安装
Smartour 被构建成了 umd 模块，允许用户通过不同的方式引入。
npm install smartour/* ES Modules */import Smartour from 'smartour'/* CommandJS */const Smartour = require('smartour')/* <script> */<script src="smartour/dist/index.js"></script>const tour = new Smartour().queue([{ el: '#id', slot: ` <p>Something you want to guide to the visitors</p> `}])tour.next()配置项
Smartour() 是一个构建函数，它接受一个 options 对象作为其配置项。
{ // `maskStyle` 为导览蒙层的样式 // 默认值将会和配置的值叠加，配置的内容可覆盖默认值 markStyle: ` position: fixed; box-shadow: 0 0 0 9999px rgba(0, 0, 0, .5); z-index: 9998; `, // 默认值 // `slotStyle` 是导览介绍内容的样式 // 默认值将会和配置的值叠加，配置的内容可覆盖默认值 slotStyle: ` position: fixed; z-index: 9999; }` // 默认值 // `maskPadding` 设置高亮区域的内边距 maskPadding: { vertical: 5, horizontal: 5 }, // 默认值（垂直、水平） // `slotPosition` 设置导览介绍内容的位置 // 可选项为：'top', 'top-right', 'top-left', 'bottom', 'bottom-right', 'bottom-left' slotPosition: 'bottom', // 默认值 // `maskEventType` 导览蒙层事件触发的方式 // 可选项为：'click', 'mouseon', 'mouseover', 'mousedown', 'mousemove', 'mouseup', 'touchstart', 'touchmove', 'touchend' maskEventType: 'click', // 默认值 // `maskEvent` 导览蒙层事件 maskEvent: () => {} // 默认值API
queue(TourList).queue()接受一个TourList参数, 这个参数是包含了一些列TourListItem的数组。[{ // `el` 为需要高亮的元素的CSS选择器 el: '#id-1', // `slot` 是导览内容的html字符串 slot: ` <p>This is a demo...<p> <button class="key-1">Cancel</button> <button class="key-2">OK</button> `, // `keyNodes` 定义了导览内容的 html 节点和其所绑定的事件 keyNodes: [{ el: '.key-1', eventType: 'click', event: (e) => { alert('Click "Cancel" button') } }, { el: '.key-2', eventType: 'mouseover', event: (e) => { alert('Hover "OK" button') } }]}]next().next()方法用于展示下一个导览。它返回一个包含了Smartour实例的 Promise。const tour = new Smartour().queue(TourList)await tour.next() // 展示第一个导览await sleep(2000) // 延时2秒await tour.next() // 展示第二个导览prev().prev()方法用于展示上一个导览。它返回一个包含了Smartour实例的 Promise。const tour = new Smartour().queue(TourList)await tour.next() // 展示第一个导览await sleep(2000) // 延时2秒await tour.next() // 展示第二个导览await sleep(2000) // 延时2秒await tour.prev() // 重新展示第一个导览over(smartourInstance).over(smartourInstance)用于移除所有的导览。const tour = new Smartour().queue(TourList)await tour.next() // 展示第一个导览await sleep(2000) // 延时2秒tour.over(tour) // 移除所有导览reset(options)为
Smartour实例重新设置配置项。const tour = new Smartour().queue(TourList)await tour.next() // 展示第一个导览await sleep(2000) // 延时2秒tour.reset({ maskStyle: ` border-radius: 5px; // 为高亮区域设置圆角 `})tour.next() // 展示下一个导览
使用例子
如 官方示例，其 Smartour 的用法如下：
<body> <main> <h1 class="title">Smartour</h1> <h3 class="desc">Makes website guiding easier</h3> <a class="link" href="https://github.com/jrainlau/smartour/blob/master/README.md#smartour">Document</a> </main></body>const tour = new Smartour({ slotPosition: 'top', maskStyle: `border-radius: 4px;`}).queue([{ el: '.title', slot: ` <div class="guide guide-1"> <p>This is my name!</p> <button class="btn btn-1">OK.</button> </div> `, keyNodes: [{ el: '.btn-1', event () { tour.reset({ slotPosition: 'bottom-right', maskStyle: `border-radius: 4px;` }) tour.next() } }]}, { el: '.desc', slot: ` <div class="guide guide-2"> <p>This is what my job is!</p> <button class="btn btn-2">Yeah.</button> </div> `, keyNodes: [{ el: '.btn-2', event () { tour.reset({ slotPosition: 'bottom', maskStyle: `border-radius: 4px;` }) tour.next() } }]}, { el: '.link', slot: ` <div class="guide guide-3"> <p>This is the document!</p> <button class="btn btn-3">Got it.</button> </div> `, keyNodes: [{ el: '.btn-3', event () { tour.over(tour) } }]}])tour.next()证书
MIT