Hopscotch框架使用指南：构建交互式产品导览

什么是Hopscotch？

Hopscotch是一个轻量级的JavaScript框架，专门用于为网页添加产品导览功能。它通过接收JSON格式的导览配置对象，提供了一套完整的API来控制导览的显示和流程管理。这个框架非常适合需要引导用户熟悉产品功能或界面的Web应用。

核心特性

Hopscotch具有以下突出特点：

1. 事件回调机制：提供onStart、onEnd、onShow、onNext、onPrev、onClose、onError等多种事件回调
2. 多页面导览支持：支持跨页面的导览流程，使用HTML5 sessionStorage保存状态，兼容性回退到cookie
3. 国际化支持：可自定义导览控件的语言文本
4. 轻量级提示框：支持创建单实例的提示框

快速入门

基础集成

要开始使用Hopscotch，只需在页面中引入两个文件：

<link rel="stylesheet" href="css/hopscotch.css">
<script src="js/hopscotch.js"></script>

创建第一个导览

定义一个简单的导览JSON对象：

var tour = {
  id: "hello-hopscotch",
  steps: [
    {
      title: "页面标题",
      content: "这是页面的主要标题区域",
      target: "header",
      placement: "right"
    },
    {
      title: "内容区域",
      content: "这里显示页面的主要内容",
      target: document.querySelector("#content p"),
      placement: "bottom"
    }
  ]
};

然后启动导览：

hopscotch.startTour(tour);

导览配置详解

基本步骤选项

每个导览步骤最基本的配置包括：

• target：目标DOM元素(ID、CSS选择器或DOM对象)
• placement：提示框位置(top/bottom/right/left)
• title：步骤标题(可选)
• content：步骤内容(可选)

示例：

{
  id: "welcome_tour",
  steps: [
    {
      target: "header",
      placement: "bottom",
      title: "导航菜单",
      content: "使用这里的链接浏览网站内容！"
    }
  ]
}

完整步骤选项

Hopscotch提供了丰富的步骤配置选项：

布局控制：

• width：提示框宽度
• padding：内边距
• xOffset/yOffset：位置微调
• arrowOffset：箭头偏移量
• zindex：z-index值

行为控制：

• delay：显示延迟(毫秒)
• showNextButton/showPrevButton：显示导航按钮
• showCTAButton：显示行动号召按钮
• multipage：是否跨页面
• fixedElement：目标元素是否固定定位
• nextOnTargetClick：点击目标元素是否前进

回调函数：

• onPrev/onNext：前后导航回调
• onShow：显示时回调
• onCTA：行动号召按钮回调

导览全局选项

通过hopscotch.configure()可以设置全局选项：

hopscotch.configure({
  bubbleWidth: 300,  // 默认提示框宽度
  smoothScroll: true,  // 启用平滑滚动
  scrollDuration: 1000,  // 滚动动画时长
  showCloseButton: true,  // 显示关闭按钮
  i18n: {  // 国际化文本
    nextBtn: "下一步",
    prevBtn: "上一步"
  }
});

API参考

Hopscotch提供了一套完整的API来控制导览：

• startTour(tour, stepNum)：启动导览
• showStep(idx)：跳转到指定步骤
• prevStep()/nextStep()：前后导航
• endTour([clearCookie])：结束导览
• getCurrTour()/getCurrStepNum()：获取当前状态
• listen(eventName, callback)：事件监听
• registerHelper(id, fn)：注册辅助函数

回调函数设计

Hopscotch支持多种方式定义回调：

函数字面量

var tour = {
  id: 'myTour',
  steps: [{
    target: 'firststep',
    onNext: function() {
      $('#firststep').hide();
    }
  }],
  onStart: function() {
    $('#article').addClass('selected');
  }
};

回调助手

对于JSON配置的场景，可以预注册助手函数：

hopscotch.registerHelper('hideElement', function(id) {
  document.getElementById(id).style.display = 'none';
});

// 然后在JSON中引用
{
  "onNext": "hideElement('firststep')"
}

最佳实践

1. 安全性：避免直接使用用户生成内容作为导览文本，防止XSS攻击
2. 性能：对于复杂页面，考虑使用delay选项确保元素加载完成
3. 用户体验：
   • 保持导览步骤简洁
   • 合理使用多页面导览
   • 提供跳过选项
4. 无障碍：确保提示框内容对屏幕阅读器友好

Hopscotch框架通过其简洁的API和灵活的配置选项，为开发者提供了创建专业级产品导览的强大工具。无论是简单的功能引导还是复杂的多页面导览，都能轻松应对。