Bootstrap Tour API 详解：打造完美的页面引导功能

Bootstrap Tour 是一个基于 Bootstrap 的 JavaScript 库，用于创建用户引导流程。它通过一系列步骤引导用户了解网站功能，提升用户体验。本文将深入解析 Bootstrap Tour 的 API，帮助开发者全面掌握其使用方法。

全局配置选项

创建 Tour 实例时，可以传入一个配置对象来自定义引导流程的行为：

var tour = new Tour({
  // 配置选项
});

核心配置项

1. name (字符串)

   • 用于构建存储项的键名
   • 只能包含字母数字、下划线和连字符
   • 默认值：'tour'

2. steps (数组)

   • 包含引导步骤的对象数组
   • 默认值：[]

3. container (字符串)

   • 指定步骤弹窗附加到的元素
   • 默认值：'body'

4. autoscroll (布尔值)

   • 当步骤弹窗超出视图时自动滚动窗口
   • 默认值：true

5. keyboard (布尔值)

   • 启用左右箭头键导航
   • 默认值：true

存储相关配置

1. storage (对象)

   • 指定使用的存储系统
   • 可设置为 window.localStorage、window.sessionStorage 或自定义对象
   • 设为 false 可禁用存储持久化
   • 默认值：window.localStorage

2. afterGetState/afterSetState/afterRemoveState (函数)

   • 在读取/写入/删除状态后执行的回调函数
   • 接收参数：key (状态键名) 和 value (状态值)

视觉相关配置

1. backdrop (布尔值)

   • 在弹窗和元素后显示深色背景，突出当前步骤
   • 默认值：false

2. backdropContainer (字符串)

   • 指定背景显示在哪个HTML元素上
   • 默认值：'body'

3. backdropPadding (数字|对象)

   • 为背景元素添加内边距
   • 可以是数字或包含 top、right、bottom、left 的对象
   • 默认值：0

高级功能配置

1. duration (布尔值|数字)

   • 设置步骤的过期时间(毫秒)
   • 过期后自动显示下一步
   • 默认值：false

2. delay (布尔值|数字|对象)

   • 设置显示和隐藏步骤的延迟时间
   • 可以是数字或包含 show 和 hide 属性的对象
   • 默认值：0

3. template (字符串|函数)

   • 弹窗的HTML模板
   • 如果是函数，接收参数：i (步骤索引) 和 step (步骤对象)

步骤配置选项

每个步骤可以单独配置，以下是最常用的选项：

tour.addStep({
  // 步骤配置
});

基本配置

1. path (字符串或正则表达式)

   • 指定步骤应显示的页面路径
   • 支持多页面引导流程
   • 默认值：''

2. host (字符串或正则表达式)

   • 指定步骤应显示的子域名
   • 默认值：''

3. element (字符串)

   • 指定弹窗应显示在哪个HTML元素上
   • 默认值：''

4. placement (字符串|函数)

   • 弹窗位置：'top'、'bottom'、'left'、'right'、'auto'
   • 默认值：'right'

内容配置

1. title (字符串|函数)

   • 步骤标题
   • 默认值：''

2. content (字符串|函数)

   • 步骤内容
   • 默认值：''

3. next/prev (整数)

   • 指定下一步/上一步的索引
   • -1 表示不显示相应链接
   • 默认值：0

交互配置

1. reflex (布尔值)

   • 点击元素时自动进入下一步
   • 默认值：false

2. orphan (布尔值|字符串|函数)

   • 允许在没有元素或元素不可见时显示步骤
   • 步骤将固定在页面中央
   • 默认值：false

事件回调函数

Bootstrap Tour 提供了丰富的事件回调，可以在引导流程的不同阶段执行自定义逻辑：

全局事件

1. onStart/onEnd

   • 引导开始/结束时触发

2. onShow/onShown

   • 步骤显示前/后触发

3. onHide/onHidden

   • 步骤隐藏前/后触发

4. onNext/onPrev

   • 进入下一步/上一步时触发

5. onPause/onResume

   • 引导暂停/恢复时触发
   • 接收剩余时间参数

步骤事件

每个步骤也可以定义自己的事件回调，优先级高于全局回调：

tour.addStep({
  onShow: function(tour) {
    // 步骤特定的显示前逻辑
  },
  // 其他回调...
});

最佳实践

1. 多页面引导：利用 path 和 host 选项创建跨页面的引导流程

2. 自定义模板：通过 template 选项完全控制弹窗的外观和行为

3. 状态持久化：使用 storage 选项确保用户进度被保存

4. 响应式设计：使用 placement: 'auto' 让弹窗自动适应不同屏幕尺寸

5. 无障碍访问：确保引导内容对屏幕阅读器等辅助技术友好

通过合理配置这些选项，您可以创建出既美观又实用的用户引导流程，显著提升产品的用户体验。