Driver.js 从 0.x 迁移到 1.x 版本指南

余攀友

于 2025-06-01 09:06:41 发布

阅读量318

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00333/article/details/148361498

Driver.js 从 0.x 迁移到 1.x 版本指南

driver.js driver.js - 一个轻量级、无依赖的纯 JavaScript 库，用于控制用户在网页上的焦点移动，适用于需要实现网页交互和用户指引的前端开发者。项目地址: https://gitcode.com/gh_mirrors/dr/driver.js

前言

Driver.js 是一个轻量级的页面引导库，用于创建产品导览、功能提示和分步教程。1.x 版本是一次重大更新，带来了全新的 API 设计和架构改进。本文将详细介绍如何从 0.x 版本平滑迁移到 1.x 版本。

导入方式的变更

1.x 版本采用了更现代化的模块导入方式：

// 旧版导入方式
import Driver from 'driver.js';
import 'driver.js/dist/driver.min.css';

// 新版导入方式
import { driver } from 'driver.js';
import "driver.js/dist/driver.css";

主要变化：

从默认导出改为命名导出 driver 函数
CSS 文件路径移除了 .min 后缀（现代构建工具会自动处理压缩）

初始化方式重构

初始化方式从类实例化改为函数调用：

// 旧版初始化
const driverObj = new Driver(config);
driverObj.setSteps(steps);

// 新版初始化
const driverObj = driver({
  ...config,
  steps  // 步骤可以直接在构造函数中传递
});

这种改变使得 API 更加简洁，配置更加集中。

配置项重大变更

已移除的配置项

overlayClickNext: 完全移除，不再支持点击遮罩跳转下一步
closeBtnText: 关闭按钮现在使用图标而非文本
className: 改为 popoverClass 更语义化
padding: 改为 stagePadding 更明确作用范围

重命名的配置项

{
  // 旧版
  scrollIntoViewOptions: {}, 
  opacity: 0.75,
  keyboardControl: true,
  
  // 新版
  scrollIntoViewOptions: {}, // 改为 scrollIntoViewOptions
  overlayOpacity: 0.75,      // 更明确作用于遮罩
  allowKeyboardControl: true // 名称更语义化
}

按钮控制更灵活

// 旧版
showButtons: false, // 简单布尔值控制

// 新版
showButtons: ['next', 'prev', 'close'], // 数组精确控制显示哪些按钮
disableButtons: ["next", "prev", "close"] // 新增禁用特定按钮功能

事件系统增强

事件回调现在提供更丰富的上下文信息：

// 旧版
onHighlightStarted: (Element) {},
onReset: (Element) {},

// 新版
onHighlightStarted: (element, step, { config, state }) => void;
onDestroyStarted: (element, step, { config, state }) => void;
onDestroyed: (element, step, { config, state }) => void;

新增的事件包括：

onPopoverRender: 自定义弹出框渲染
onCloseClick: 专门处理关闭按钮点击
onNextClick/onPrevClick: 更细粒度的导航控制

步骤定义变更

弹出框定位系统重构

// 旧版 - 单一 position 属性
position: 'left', // 或 'left-center', 'left-bottom' 等组合值

// 新版 - 分离的 side 和 align 属性
side: "left",     // top/right/bottom/left
align: "center"   // start/center/end

这种改变使定位系统更加清晰和灵活。

新增功能

1.x 版本为每个步骤添加了多项新功能：

popover: {
  showProgress: true,      // 显示进度指示
  progressText: "{current} of {total}", // 自定义进度文本
  onPopoverRender: (popover, { config, state }) => void // 自定义渲染
}

API 方法变更

方法重命名

// 旧版
driverObj.start(0);
driverObj.reset();
driverObj.hasHighlightedElement();

// 新版
driverObj.drive(0);      // 启动导览
driverObj.destroy();     // 销毁实例
driverObj.getActiveElement(); // 获取当前激活元素

新增实用方法

1.x 版本添加了许多有用的新方法：

driverObj.moveTo(2);            // 跳转到指定步骤
driverObj.getActiveStep();      // 获取当前步骤定义
driverObj.isLastStep();         // 检查是否为最后一步
driverObj.getState();           // 获取当前状态
driverObj.setConfig(newConfig); // 动态更新配置
driverObj.refresh();            // 刷新当前步骤