React项目中Hopscotch多页面引导无法正常工作的问题咨询

我来帮你搞定Hopscotch跨页面引导的重复流程问题——核心原因就是页面间没正确传递和读取引导的进度状态，结合官方依赖sessionStorage/cookies的特性，下面是第一页和第二页的具体配置步骤：

第一页（引导启动页）配置 #

• 初始化引导时启用持久化：创建tour实例时，必须指定唯一的tourId并开启persist: true，这是Hopscotch在页面间保存进度的基础。示例代码：

import hopscotch from 'hopscotch';

// 在组件的useEffect或componentDidMount中初始化
useEffect(() => {
  const multiPageTour = {
    id: 'my-react-multi-tour', // 这个ID要和第二页完全一致
    persist: true,
    steps: [
      {
        target: '#first-page-step1',
        title: '第一步',
        content: '这是第一页的第一个引导步骤'
      },
      {
        target: '#first-page-step2',
        title: '准备跳转',
        content: '点击下一步跳转到第二页',
        // 处理跳转逻辑的关键回调
        onNext: () => {
          // 手动保存当前进度（Hopscotch会自动存，但手动写更稳妥）
          sessionStorage.setItem('hopscotch_current_step', hopscotch.getCurrStepNum());
          // React路由跳转，这里根据你的路由库调整，比如react-router的navigate
          navigate('/second-page');
        }
      }
    ]
  };
  hopscotch.registerTour(multiPageTour);
  
  // 启动引导（如果是首次进入）
  if (!sessionStorage.getItem('hopscotch_current_step')) {
    hopscotch.startTour(multiPageTour);
  }
}, [navigate]);

• 关键注意点：跳转前确保进度已写入sessionStorage，不要依赖自动保存的延迟，手动调用setItem能避免页面跳转时状态还没同步的问题。

第二页（引导续页）配置 #

• 复用相同的tourId并读取进度：第二页的tour配置必须和第一页用同一个id，并在组件挂载时读取保存的进度，从对应步骤启动引导：

import hopscotch from 'hopscotch';

useEffect(() => {
  const multiPageTour = {
    id: 'my-react-multi-tour', // 和第一页完全一致的ID
    persist: true,
    steps: [
      // 这里可以只写第二页的步骤，或者保留完整的步骤数组（Hopscotch会自动识别当前位置）
      {
        target: '#second-page-step3',
        title: '第二页第一步',
        content: '从第一页跳转后，直接进入这里'
      },
      {
        target: '#second-page-step4',
        title: '完成引导',
        content: '整个跨页面引导结束'
      }
    ]
  };
  hopscotch.registerTour(multiPageTour);
  
  // 读取保存的进度并启动对应步骤
  const savedStep = sessionStorage.getItem('hopscotch_current_step');
  if (savedStep) {
    // 从保存的步骤的下一个步骤开始（因为第一页最后一步是跳转，所以要+1）
    hopscotch.startTour(multiPageTour, parseInt(savedStep) + 1);
    // 也可以用Hopscotch内置的状态读取：hopscotch.getState('my-react-multi-tour').currentStep
  }
}, []);

• 额外处理：如果引导完成后需要清除状态，可以在最后一步的onEnd回调里执行：

onEnd: () => {
  sessionStorage.removeItem('hopscotch_current_step');
  hopscotch.resetState('my-react-multi-tour');
}

通用注意事项 #

• 确保两个页面的Hopscotch库版本一致，避免兼容性问题。
• 同域下sessionStorage才能正常共享，如果是子域名，需要配置cookie（Hopscotch支持cookieOptions参数）。
• 测试前先清除浏览器的sessionStorage，避免旧的引导状态干扰。

内容的提问来源于stack exchange，提问作者Shaheen Shaikh