新手引导 plugin-driver

约 970 字大约 3 分钟

...

2026-09-28

插件说明

设计器新手引导插件：基于 driver.js 在设计器挂载后分步高亮界面，引导用户熟悉布局与功能入口；引导进度带缓存，走完不再弹出。

核心能力：

通过 steps 数据化描述引导流程，步骤支持静态对象或返回 DriveStep 的函数（可异步，便于动态定位 DOM）
cacheKey 版本号管理：升级引导内容时改 key 即可重新触达老用户
通过 sv-print 的 preferences（localStorage）持久化「已引导过」标记
在 designerUtils 上挂载运行时 API，可在任意位置触发/重置引导

依赖 driver.js（插件自带样式，必须引入样式文件）。要求 sv-print >= 0.2.0。安装：

npm install @sv-print/plugin-driver

示例代码

import '@sv-print/plugin-driver/dist/style.css'; // 必须引入样式
import pluginDriver from '@sv-print/plugin-driver';

await hiprint.register({
  // 需 await 注册；init 不收插件数组
  plugins: [
    pluginDriver({
      // 缓存 key，判断某个版本的 steps 是否需要执行
      cacheKey: 'driver:DesignGuidance-v1', // 升级引导内容时需同步更新版本号
      // 是否自动开启引导（默认 true）
      autoStart: true,
      // 引导步骤
      steps: [
        {
          element: '.svp-header',
          popover: { title: '这是菜单栏', description: '菜单栏支持插槽，也可以完全自定义' },
        },
        {
          // 也支持函数式 element，可结合页面状态动态定位
          element: () => document.querySelector('.previewBox')?.closest('.svp-modal-box'),
          onHighlightStarted: () => {
            // 高亮开始时回调，如先打开预览弹窗
          },
          popover: {
            title: '这是预览弹窗',
            description: '可浏览器打印、静默打印、导出图片、导出 pdf',
          },
        },
      ],
      // 透传给 driver.js 的全局配置
      driverOptions: {
        showProgress: true,
        nextBtnText: '下一步',
        prevBtnText: '上一步',
        doneBtnText: '我知道了',
      },
      // 引导走完回调
      onComplete: () => {},
      // 用户中途关闭 / 跳过时回调
      onSkip: () => {},
    }),
  ],
});

高级用法

config 参数

参数	类型	默认值	说明
steps	`GuideStep[]`	-	引导步骤；`GuideStep = DriveStep \| (() => DriveStep \| Promise<DriveStep>)`
cacheKey	string	`plugin-driver:default`	写入 preferences 的缓存 key
driverOptions	`Partial<driver.Config>`	-	透传 driver.js 全局配置（按钮文案、进度、动画等）
autoStart	boolean	`true`	设计器挂载后是否自动开启引导
onComplete	() => void	-	引导走完最后一步时回调
onSkip	() => void	-	用户中途关闭 / 跳过时回调

步骤可直接复用 driver.js 的 DriveStep 能力：元素定位、onHighlightStarted / onDeselected 等生命周期钩子、popover.title / description / side / align 等气泡外观。

运行时 API

插件在 onDesigned 时把以下方法挂到 designerUtils 上：

方法	说明
`designerUtils.startGuide(force?)`	立即开启引导；`force=true` 时忽略已读缓存强制开启
`designerUtils.resetGuide()`	清除已读标记并立刻开启引导
`designerUtils.getGuideCacheKey()`	取得当前插件使用的缓存 key

// 例如：用户点击"再看一次引导"按钮
button.onclick = () => designerUtils.resetGuide?.();

缓存机制

写入位置：sv-print 的 preferences store（底层是 localStorage 上的 sv-print-preferences）
写入时机：用户走完最后一步点击 Done 时
中途点击关闭按钮或遮罩不会写入缓存，下次挂载会自动重新开启
升级引导文案 / 增减步骤时，建议同步更新 cacheKey 版本号（如 v1 → v2），否则老用户无法感知新版引导

注意事项

必须引入 @sv-print/plugin-driver/dist/style.css
driver.js 执行时会滚动居中显示目标元素，必要时在 onComplete / onDeselected 中重置容器滚动条，避免样式错乱

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)