Skip to content

@neosjs/intro ​

轻量级、无依赖的新手引导插件,提供类似 driver.js 的分步引导能力:通过遮罩(overlay)压暗页面、高亮(highlight)目标元素,并在旁边弹出说明层(popover)带领用户熟悉页面功能。零依赖、TypeScript 编写。

安装 ​

sh
pnpm add @neosjs/intro
sh
npm i @neosjs/intro
sh
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'
  }
})