Driver.js 使用指南零依赖的产品导览、功能引导与页面聚焦高亮库【免费下载链接】driver.jsA lightweight, dependency-free JavaScript library for guiding user focus across the page.项目地址: https://gitcode.com/gh_mirrors/dr/driver.jsDriver.js 是当前仓库packages/driver中的核心开源库一个用原生 TypeScript 编写、无任何外部依赖的轻量级 JavaScript 库用于在产品导览Product Tours和功能引导Feature Introductions场景下引导用户聚焦页面上的元素。本文以 packages/driver/readme.md 为骨架结合仓库内源码与测试完整讲解其定位、核心能力、配置项、事件钩子、键盘可访问性以及本地开发流程读完你可以独立完成一次多步骤产品导览、单元素高亮与页面提示Hints的接入与二次开发。项目定位它不止是一个导览库readme 开篇给出的定位是Powerful, highly customizable library for Product Tours and Feature Introductions强大、高度可定制用于产品导览和功能引导。其关键卖点包括Simple使用简单完全没有任何外部依赖Light-weightgzip 后仅约 5kbreadme 中同时提到同类库通常为 12kb此为项目自身声明Highly customizable提供强大的 API可按任意方式使用Highlight anything可以高亮页面上任何元素Feature introductions为 Web 应用创建强大的功能引导Focus shifters为用户提供焦点转移把注意力引导到某个组件上User friendly一切操作都可通过键盘完成TypeScript使用 TypeScript 编写Consistent behavior在所有主流浏览器中行为一致MIT Licensed个人与商用均免费。readme 特别强调So, yet another tour library? No, its more than a tour library.导览只是众多用例之一。凡是你需要在页面上盖一层遮罩的场景都可以使用它readme 列举的典型场景包括用户与页面组件交互时高亮该组件让用户保持专注提供上下文帮助例如用户填写表单时弹出带变暗背景的 popover 提示作为焦点转移工具把用户注意力带到页面上某个组件模拟视频网站上常见的 Turn off the Lights关灯小部件效果用作简单的模态框modal以及当然的——产品导览product tours。从源码结构看这一多功能定位体现在库被拆分为多个职责清晰的模块见 packages/driver/srcdriver.ts对外主入口与导览编排、context.ts实例级配置/状态/事件总线、overlay.tsSVG 遮罩层、highlight.ts高亮舞台、popover.ts气泡卡片渲染、position.ts定位计算、step.ts步骤解析、events.ts键盘与点击事件、click.ts点击处理以及独立的hints.ts页面提示信标。快速开始安装与引入Driver.js 发布在 npm 上包名为driver.js仓库内即 packages/driver/package.json当前版本 1.8.0。包同时提供 CJS、ESM 与类型声明通过exports字段暴露了主入口driver.js、独立子入口driver.js/hints以及两份独立样式文件driver.js/dist/driver.css与driver.js/dist/hints.css。在浏览器 / 前端项目中按如下方式引入示例出自 apps/docs/src/content/guides/basic-usage.mdximport { driver } from driver.js; import driver.js/dist/driver.css; const driverObj driver({ showProgress: true, steps: [ { element: .page-header, popover: { title: Title, description: Description } }, { element: .top-nav, popover: { title: Title, description: Description } }, { element: .sidebar, popover: { title: Title, description: Description } }, { element: .footer, popover: { title: Title, description: Description } }, ] }); driverObj.drive();注意样式文件必须引入driver.css否则遮罩层与 popover 无法正常渲染。三种核心用法1. 多步骤产品导览Tour如上例所示通过driver({ steps: [...] })创建实例后调用drive()即可启动导览。steps中的每一步都是一个DriveStep其类型定义在 packages/driver/src/driver.tsexport type DriveStep { element?: string | Element | (() Element); // 目标元素CSS 选择器 / 元素引用 / 返回元素的函数 onHighlightStarted?: DriverHook; // 高亮开始前 onHighlighted?: DriverHook; // 高亮完成后 onDeselected?: DriverHook; // 步骤取消选中后 popover?: Popover; // 气泡配置见下文 disableActiveInteraction?: boolean; // 禁止与高亮元素交互 advanceOnClick?: boolean; // 点击高亮元素时前进 skipMissingElement?: boolean; // 元素缺失时跳过该步骤 waitForElement?: number; // 等待元素出现的毫秒数 data?: Recordstring, any; // 任意自定义数据 };关键点element可省略。省略时该步骤会在屏幕中央渲染一个虚拟元素源码中称为driver-dummy-elementpopover 像模态框一样居中显示——这正是 readme 所说用作简单模态框的实现基础见 packages/driver/src/step.ts 中centered: element.id driver-dummy-element的判断。2. 单元素高亮Highlightreadme 提到的highlight方法用于只高亮单个元素import { driver } from driver.js; import driver.js/dist/driver.css; const driverObj driver(); driverObj.highlight({ element: #some-element, popover: { title: Title for the Popover, description: Description for it, }, });driver()不传steps也能直接调用highlight(step)。从 driver.ts 的实现看highlight会先执行初始化并把 popover 默认裁剪为无按钮、无进度条的形态非常适合高亮 轻提示的临时场景。3. 页面提示Hints驻留式脉冲信标除导览与高亮外库还内置了 Hints一种静静驻留在页面上、点击后展开 popover 的脉冲小圆点没有遮罩层、不阻塞任何操作。Hints 从独立入口driver.js/hints导出因此只用导览的用户不会加载到它的代码readme 与 package.json 的exports字段均体现了这一点import { hints } from driver.js/hints; import driver.js/dist/hints.css; const productHints hints({ hints: [ { element: #export-btn, popover: { title: Export your data, description: Download this report as CSV or PDF. } }, { element: #summary, popover: { title: Auto-generated summary, description: Written for you from the numbers. } }, ], }); productHints.show();Hints 的完整 API 定义在 packages/driver/src/hints.tsshow()、hide()、open(id)、close()、dismiss(id)、restore(id)、restoreAll()、setHints()、getHints()、getActive()、isVisible()、refresh()。每个 hint 支持稳定的id用于记住已关闭状态、beacon锚点配置side/align/animate/className/offsetX/offsetY还支持可选的overlay暗化模式。配置项详解来自源码的默认值readme 提到库highly customizable并provides hooks。全部配置项定义在 packages/driver/src/context.ts其默认值在configure()中集中给出见 context.ts配置项默认值说明steps[]导览步骤数组animatetrue是否启用过渡动画duration400动画时长毫秒通过 CSS 变量--driver-animation-duration作用于页面overlayColor#000遮罩颜色overlayOpacity0.7遮罩不透明度smoothScrollfalse高亮元素滚动到视口时是否平滑滚动allowClosetrue是否允许关闭导览影响关闭按钮与 EscallowScrolltrue导览期间是否允许页面滚动overlayClickBehaviorclose点击遮罩的行为close关闭、nextStep前进、或传入函数自定义stagePadding10高亮舞台镂空区域内边距像素stageRadius5镂空区域圆角半径像素disableActiveInteractionfalse禁止与当前高亮元素交互advanceOnClickfalse点击高亮元素时前进到下一步元素自身点击行为不会被阻止skipMissingElementfalse目标元素缺失时跳过该步骤无元素步骤是故意的居中步骤永远不会被跳过waitForElement0等待缺失元素出现的毫秒数超时后回落到常规缺失处理逻辑allowKeyboardControltrue是否允许键盘控制popoverClasspopover 自定义 CSS 类popoverOffset10popover 与高亮区域之间的间距像素showButtons[next,previous,close]显示哪些按钮disableButtons[]禁用哪些按钮showProgressfalse是否显示进度文本progressText{{current}} of {{total}}进度文本模板{{current}}/{{total}}会被替换为当前步数与总步数见 step.tsnextBtnText/prevBtnText/doneBtnTextNext/Previous/Done按钮文案onPopoverRender—popover 渲染完成后回调遮罩层实现原理readme 描述的 Turn off the Lights 效果其底层实现是 packages/driver/src/overlay.ts动态创建一个覆盖全屏的 SVGviewBox与窗口同尺寸通过stage.ts中的generateStageSvgPathString生成挖洞路径——即除高亮元素含stagePadding内边距与stageRadius圆角外全部变暗。步骤切换时遮罩通过transitionStage结合easeInOutQuad缓动函数做位置/尺寸的逐帧动画过渡窗口resize、页面scroll时则通过requireRefresh重新计算并刷新高亮见 packages/driver/src/events.ts。步骤内的 Popover 配置每个步骤的popover字段类型定义在 packages/driver/src/popover.tsexport type Popover { title?: string; description?: string; side?: Side; // top | right | bottom | left align?: Alignment; // start | center | end showButtons?: AllowedButtons[]; // next | previous | close showProgress?: boolean; disableButtons?: AllowedButtons[]; popoverClass?: string; progressText?: string; doneBtnText?: string; nextBtnText?: string; prevBtnText?: string; onPopoverRender?: (popover: PopoverDOM, opts: HookOpts) void; onNextClick?: DriverHook; onPrevClick?: DriverHook; onCloseClick?: DriverHook; onDoneClick?: DriverHook; };popover 默认渲染在元素下方、左对齐side: bottom、align: start见 step.ts 的定位解析并通过roledialog、aria-labelledby、aria-describedby等无障碍属性声明为对话框popover.ts。需要注意的解析规则均在 step.ts 中实现步骤级配置优先于全局配置其次才是内置默认值例如showProgress的优先级为步骤 popover 全局配置 false最后一步的Next按钮会自动变成Done按钮doneButton: true并追加driver-popover-done-btn样式类此时若配置了onDoneClick它优先于onNextClick被调用见resolveNextHook第一步会自动禁用 previous 按钮若allowClose为false关闭按钮会自动从按钮列表中剔除。事件钩子贯穿导览生命周期的回调readme 明确提到库provides you the hooks to manipulate the elements as they are highlighted, about to be highlighted, or deselected。这些钩子在Config中分为三类context.ts状态类回调状态变化时触发onHighlightStarted(element, step, opts)元素即将被高亮时onHighlighted(element, step, opts)元素高亮完成后onDeselected(element, step, opts)元素被取消选中时onDestroyStarted(element, step, opts)导览销毁流程开始时readme 文档中常用于退出前确认场景onDestroyed(element, step, opts)导览销毁完成后。事件类回调按钮/键盘触发onNextClick、onPrevClick、onCloseClick、onDoneClick。渲染类回调onPopoverRender(popover, opts)popover 渲染完成后可在此操作PopoverDOMwrapper、arrow、title、description、footer、progress、各按钮等见 popover.ts。钩子的解析顺序遵循步骤级钩子 全局钩子 默认行为例如点击下一步时先看当前步骤popover.onNextClick再看全局onNextClick都没有才走内置的drive(stepIndex 1)导航逻辑step.ts。每个钩子都会收到统一的HookOpts{ config, state, driver, index }让你能同时访问当前配置、运行时状态、Driver 实例与当前步骤索引。完整的公开 APIDriver 实例方法driver()工厂函数返回的Driver实例driver.ts提供以下方法方法作用drive(stepIndex?)启动导览可选从指定索引开始highlight(step)高亮单个元素不进入导览模式moveNext()/movePrevious()/moveTo(index)编程式前进 / 后退 / 跳转hasNextStep()/hasPreviousStep()是否存在可到达的下一步 / 上一步自动跳过被skipMissingElement跳过的步骤isActive()导览是否处于激活状态isFirstStep()/isLastStep()是否为首步 / 末步getActiveIndex()/getActiveStep()/getActiveElement()获取当前状态getPreviousStep()/getPreviousElement()/getNextStep()获取相邻步骤setConfig(config)/getConfig()动态修改 / 读取配置setSteps(steps)动态替换步骤列表getState(key?)读取运行时状态refresh()手动刷新高亮位置常用于布局变化后destroy()结束并清理导览注意hasNextStep/hasLastStep等判断会通过findReachableIndex基于实时 DOM跳过被跳过的步骤确保 Done 按钮与导览真实终点始终一致见 step.ts。键盘支持与焦点管理readme 声称Everything is controllable by keyboard其实现位于 packages/driver/src/events.tsEsc关闭导览受allowClose约束→/←前进 / 后退一步受allowKeyboardControl约束默认开启Tab/ShiftTab在 popover 与高亮元素之间做焦点陷阱focus trap把焦点限制在当前导览 UI 内避免用户 Tab 出导览区域trapFocus函数导览销毁时还会把焦点归还给导览前的活跃元素见 driver.ts。事件绑定统一在initEvents中注册、在destroyEvents中按引用精确解绑避免多次启动/销毁导致的事件泄漏。本地开发readme 推荐的运行流程readme 给出了在仓库内进行本地开发的完整流程。库的源码位于packages/driver/src/而playground/是一个 Astro 应用直接从源码导入库因此对源码的修改会即时热更新到示例页面pnpm install pnpm run playground:install pnpm dev每个示例独立存放在playground/src/examples/下并以独立页面出现在侧边栏中新增示例时在对应分组highlight.ts、popover.ts、tour.ts、api.ts中登记入口即可其余常用脚本pnpm build # 构建产物tsc tsdown postbuild 脚本 pnpm test # 运行 Vitest 测试套件仓库的测试位于 packages/driver/tests覆盖了点击前进click.test.ts、动画animation.test.ts、键盘keyboard.test.ts、生命周期lifecycle.test.ts、导航navigation.test.ts、定位placement.test.ts、跳过缺失元素skip-missing.test.ts、元素等待wait-for-element.test.ts、自定义按钮custom-buttons.test.ts、Hintshints.test.ts等维度是理解库行为边界的绝佳参考。结语综合 readme 与源码可以确认Driver.js 的核心价值在于一个 API、多种用法——产品导览、单元素高亮、聚焦转移、关灯效果、模态框、驻留式 Hints 提示全部建立在零依赖、约 5kb gzipped 的轻量实现之上体积数据为 readme 中的项目声明并通过完善的配置项、生命周期钩子与键盘可访问性保证了对各类业务场景的定制能力。若你想深入源码推荐从 packages/driver/src/driver.ts对外 API 编排→ packages/driver/src/context.ts配置/状态/事件核心→ packages/driver/src/step.ts步骤解析这条链路读起。【免费下载链接】driver.jsA lightweight, dependency-free JavaScript library for guiding user focus across the page.项目地址: https://gitcode.com/gh_mirrors/dr/driver.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考