@neosjs/intro
轻量级、无依赖的新手引导插件,提供类似 driver.js 的分步引导能力:通过遮罩(overlay)压暗页面、高亮(highlight)目标元素,并在旁边弹出说明层(popover)带领用户熟悉页面功能。零依赖、TypeScript 编写。
安装
sh
pnpm add @neosjs/introsh
npm i @neosjs/introsh
yarn add @neosjs/intro引入样式
插件样式以独立 CSS 文件提供,使用前需要额外引入:
ts
import '@neosjs/intro/dist/intro.css'快速上手
调用默认导出的 intro() 函数,传入 steps 定义引导步骤,每个步骤通过 element 指定要高亮的元素(支持选择器字符串或 DOM 元素),popover 定义标题与描述:
ts
import intro from '@neosjs/intro'
import '@neosjs/intro/dist/intro.css'
const introInstance = intro({
steps: [
{
element: '#step-one',
popover: {
title: '第一步',
description: '这里是第一步的引导说明'
}
},
{
element: '#step-two',
popover: {
title: '第二步',
description: '这里演示第二步,支持上一步 / 下一步切换'
}
}
]
})
introInstance.start() // 从第 0 步开始引导引导过程中:
- 点击遮罩空白处或按
Esc可关闭引导(可通过allowClose: false禁用) - 支持键盘左右方向键切换步骤
- 弹层底部自带「上一步 / 下一步」按钮,最后一步按钮文字变为完成文案(
doneBtnText,默认Done) - 可通过
showProgress+progressText显示「第 x 步 / 共 n 步」进度
API
实例方法
intro(config) 返回引导实例:
| 方法 | 说明 |
|---|---|
start(stepIndex?) | 开始引导,可传入起始步骤下标(默认 0) |
destroy() | 销毁引导,移除遮罩与弹层并清理状态 |
moveNext() / movePrevious() | 切换到下一步 / 上一步,无对应步骤时销毁 |
moveTo(index) | 跳转到指定步骤,无对应步骤时销毁 |
highlight(step) | 高亮单个元素(不走步骤流程) |
refresh() | 目标元素位置变化后刷新高亮区域位置 |
setConfig(config) / getConfig() | 更新 / 读取配置 |
setSteps(steps) | 重置状态并更新步骤列表 |
getState() | 读取内部状态 |
isActive() | 引导是否处于激活状态 |
getActiveIndex() / getActiveStep() / getActiveElement() | 当前步骤下标 / 步骤配置 / 高亮元素 |
getPreviousStep() / getPreviousElement() | 上一步配置 / 上一个高亮元素 |
isFirstStep() / isLastStep() | 是否为第一步 / 最后一步 |
hasNextStep() / hasPreviousStep() | 是否存在下一步 / 上一步 |
配置项(Config)
| 参数 | 说明 | 类型 |
|---|---|---|
steps | 引导步骤列表 | IntroStep[] |
animate | 是否开启动画 | boolean |
overlayColor | 遮罩颜色 | string |
overlayOpacity | 遮罩透明度 | number |
smoothScroll | 是否平滑滚动到目标元素 | boolean |
allowClose | 是否允许点击遮罩 / 按 Esc 关闭 | boolean |
stagePadding | 高亮区域内边距 | number |
stageRadius | 高亮区域圆角 | number |
disableActiveInteraction | 是否禁止与高亮元素交互 | boolean |
allowKeyboardControl | 是否允许键盘控制 | boolean |
popoverClass | 弹层自定义类名 | string |
popoverOffset | 弹层与高亮元素的偏移 | number |
showButtons | 显示的按钮 | ('next' | 'previous' | 'close')[] |
disableButtons | 禁用的按钮 | ('next' | 'previous' | 'close')[] |
showProgress | 是否显示进度 | boolean |
progressText | 进度文案模板,如 of | string |
nextBtnText / prevBtnText / doneBtnText / startBtnText | 各按钮文案 | string |
onPopoverRender | 弹层渲染后的回调,可拿到弹层 DOM | (popover: PopoverDOM, opts) => void |
onHighlightStarted / onHighlighted / onDeselected | 元素高亮开始 / 完成 / 取消选中时回调 | IntroHook |
onDestroyStarted / onDestroyed | 引导销毁前 / 销毁后回调 | IntroHook |
onNextClick / onPrevClick / onCloseClick | 按钮点击回调(可拦截默认行为) | IntroHook |
步骤(IntroStep)
| 参数 | 说明 | 类型 |
|---|---|---|
element | 要高亮的元素,选择器字符串或 DOM 元素 | string | Element |
popover | 该步骤的弹层配置 | Popover |
onHighlightStarted / onHighlighted / onDeselected | 步骤级高亮回调 | IntroHook |
弹层(Popover)
| 参数 | 说明 | 类型 |
|---|---|---|
title | 标题 | string |
description | 描述内容 | string |
side | 弹层相对元素的方向 | 'top' | 'right' | 'bottom' | 'left' | 'over' |
align | 弹层对齐方式 | 'start' | 'center' | 'end' |
showButtons / disableButtons | 覆盖全局的按钮显示 / 禁用配置 | AllowedButtons[] |
showProgress / progressText | 覆盖全局的进度配置 | boolean / string |
popoverClass | 自定义类名 | string |
doneBtnText / nextBtnText / prevBtnText / startBtnText | 覆盖全局的按钮文案 | string |
onPopoverRender | 弹层渲染后回调 | (popover: PopoverDOM, opts) => void |
onNextClick / onPrevClick / onCloseClick | 按钮点击回调 | IntroHook |
高亮单个元素
不走分步流程,只高亮一个元素时,可以使用 highlight:
ts
introInstance.highlight({
element: '.logo',
popover: {
title: 'Logo',
description: '这是站点 Logo'
}
})