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

前言

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();            // 刷新当前步骤

迁移建议

1. 逐步替换：先替换导入和初始化方式，再逐个更新配置项
2. 事件处理：利用新版提供的丰富上下文信息重构事件处理逻辑
3. 定位系统：将复合的 position 值拆分为 side 和 align 组合
4. 测试验证：特别注意按钮控制和导航逻辑的变化

总结

Driver.js 1.x 版本通过更合理的 API 设计和增强的功能集，提供了更强大、更灵活的页面引导能力。虽然迁移需要一些工作，但新版本更好的可维护性和扩展性将使长期收益大于短期成本。建议开发者充分利用新版提供的自定义能力和细粒度控制特性，打造更出色的用户体验。