Shepherd.js 中 tour.getCurrentStep() 方法在步骤切换时的异常行为解析

Shepherd.js 是一个流行的网页导览库，它允许开发者创建交互式的用户引导流程。在使用过程中，部分开发者反馈在监听步骤切换事件时，getCurrentStep() 方法存在返回值异常的情况。本文将深入分析该问题的成因，并提供可靠的解决方案。

问题现象

当开发者尝试通过事件监听机制获取当前步骤信息时，会遇到以下异常表现：

1. 导览开始时，首个步骤显示阶段调用 getCurrentStep() 返回 null
2. 切换到后续步骤时，该方法返回的是前一个步骤对象而非当前步骤
3. 这种时序问题导致基于当前步骤计算的进度条等功能无法正常工作

技术原理分析

通过源码分析可以发现，这个问题本质上是事件触发时序与状态更新时序的竞态条件：

1. 事件触发机制：Shepherd.js 的 show 事件是在步骤即将展示时触发的，此时新的步骤对象尚未被设置为当前活跃步骤
2. 状态更新时机：currentStep 属性的更新操作发生在步骤实际完成渲染之后
3. 方法调用差异：直接访问 activeTour 属性可以获取正确值，因为它是实时状态引用

解决方案

推荐方案：使用 when 钩子

Shepherd.js 官方推荐的做法是使用步骤配置中的 when 钩子来处理步骤相关逻辑：

steps: [
  {
    // 步骤配置...
    when: {
      show() {
        // 此处可以正确获取当前步骤上下文
        const currentStep = this;
        // 计算进度逻辑...
      }
    }
  }
]

替代方案：延迟获取

如果必须使用事件监听模式，可以通过微任务队列延迟获取：

tour.on('show', () => {
  setTimeout(() => {
    const activeStep = tour.getCurrentStep();
    // 此时可以获取正确的当前步骤
  }, 0);
});

最佳实践建议

1. 遵循官方模式：尽量使用步骤配置中的 when 钩子而非全局事件监听
2. 状态管理：对于复杂的导览逻辑，考虑维护独立的状态管理
3. 错误处理：始终对 getCurrentStep() 的返回值进行空值检查
4. 性能考量：避免在步骤切换时执行耗时操作，以免影响用户体验

总结

Shepherd.js 作为成熟的导览库，其设计哲学强调声明式配置优先。理解其内部的事件时序机制对于开发复杂导览流程至关重要。通过采用正确的模式，开发者可以构建出稳定可靠的用户引导体验。

对于需要精确控制步骤状态的场景，建议深入理解 Shepherd.js 的生命周期模型，并合理利用其提供的各种钩子函数，而非依赖可能存在时序问题的全局事件监听。