如何使用jQuery实现支持多页面的Joy Ride Tour网站导览插件

核心实现思路 #

多页面导览最核心的问题是要实现跨页面的导览进度持久化，不需要依赖后端存储，直接用前端localStorage/sessionStorage记录当前步骤、导览开启状态即可，再配合全局统一的导览步骤配置，每个步骤绑定对应页面标识，页面加载时自动匹配当前步骤对应的页面，自动跳转或渲染对应提示框。

具体实现步骤 #

• 第一步：定义全局统一导览配置，给每个步骤增加所属页面的标识字段

// 全网站导览步骤统一配置
const tourConfig = [
  {
    pagePath: '/home', // 步骤所属页面的路径，hash路由可改为hash值
    target: '#home-banner', // 要高亮的目标元素jQuery选择器
    title: '首页活动区',
    content: '这里会展示网站最新的活动和公告',
    position: 'bottom' // 提示框相对于目标元素的位置
  },
  {
    pagePath: '/product-list',
    target: '#filter-area',
    title: '筛选栏',
    content: '你可以通过这里的筛选条件快速找到需要的商品',
    position: 'right'
  },
  {
    pagePath: '/user-center',
    target: '#points-entry',
    title: '积分入口',
    content: '点击这里可以查看你的积分和兑换权益',
    position: 'top'
  }
]

• 第二步：封装jQuery依赖的导览核心类，内置状态管理、步骤匹配、提示框渲染、跨页跳转逻辑

class JoyRideTour {
  constructor(config) {
    this.config = config
    // 从本地存储读取导览进度和状态
    this.currentStep = +localStorage.getItem('tour_current_step') || 0
    this.tourActive = localStorage.getItem('tour_active') === 'true'
    this.init()
  }

  init() {
    if (!this.tourActive) return
    const currentStepConf = this.config[this.currentStep]
    // 当前步骤不属于当前页面，自动跳转到对应页面
    if (currentStepConf.pagePath !== window.location.pathname) {
      window.location.href = currentStepConf.pagePath
      return
    }
    // 页面加载完成后渲染当前步骤的提示框
    $(document).ready(() => {
      this.renderTooltip(currentStepConf)
    })
  }

  renderTooltip(step) {
    // 移除已存在的提示框避免重复渲染
    $('.joyride-tooltip').remove()
    // 生成提示框DOM结构
    const tooltip = $(`
      <div class="joyride-tooltip">
        <h4>${step.title}</h4>
        <p>${step.content}</p>
        <div class="joyride-actions">
          <button class="joyride-prev" ${this.currentStep === 0 ? 'disabled' : ''}>上一步</button>
          <button class="joyride-next">${this.currentStep === this.config.length - 1 ? '完成' : '下一步'}</button>
          <button class="joyride-close">关闭</button>
        </div>
      </div>
    `)
    // 计算提示框位置，追加到页面
    const $target = $(step.target)
    const targetOffset = $target.offset()
    // 可根据step的position字段扩展位置计算逻辑，这里以bottom位置为例
    tooltip.css({
      position: 'absolute',
      top: targetOffset.top + $target.outerHeight() + 12 + 'px',
      left: targetOffset.left + 'px',
      zIndex: 99999
    }).appendTo('body')
    // 高亮目标元素
    $target.css({
      position: 'relative',
      zIndex: 100000
    })
    // 绑定按钮操作事件
    this.bindActionEvents()
  }

  bindActionEvents() {
    // 下一步/完成按钮事件
    $('.joyride-next').on('click', () => {
      if (this.currentStep === this.config.length - 1) {
        this.endTour()
        return
      }
      this.currentStep++
      localStorage.setItem('tour_current_step', this.currentStep)
      this.init()
    })
    // 上一步按钮事件
    $('.joyride-prev').on('click', () => {
      this.currentStep--
      localStorage.setItem('tour_current_step', this.currentStep)
      this.init()
    })
    // 关闭导览按钮事件
    $('.joyride-close').on('click', () => {
      this.endTour()
    })
  }

  endTour() {
    this.tourActive = false
    localStorage.removeItem('tour_current_step')
    localStorage.setItem('tour_active', 'false')
    $('.joyride-tooltip').remove()
    // 清除所有目标元素的高亮样式
    this.config.forEach(step => {
      $(step.target).css({
        position: 'static',
        zIndex: 'auto'
      })
    })
  }

  // 对外暴露的手动开启导览方法
  start() {
    this.currentStep = 0
    this.tourActive = true
    localStorage.setItem('tour_current_step', 0)
    localStorage.setItem('tour_active', 'true')
    this.init()
  }
}

• 第三步：全局引入导览代码，在所有页面加载该JS文件，需要触发导览时调用启动方法即可

// 初始化导览实例
const siteTour = new JoyRideTour(tourConfig)
// 示例：用户首次登录时自动开启导览
if (localStorage.getItem('is_first_login') === 'true') {
  siteTour.start()
  localStorage.removeItem('is_first_login')
}

• 第四步：补充基础样式，可根据业务需求自定义样式细节

.joyride-tooltip {
  width: 300px;
  padding: 15px;
  background: #fff;
  border-radius: 6px;
  box-shadow: 0 2px 12px rgba(0,0,0,0.15);
}
.joyride-actions {
  display: flex;
  gap: 8px;
  justify-content: flex-end;
  margin-top: 10px;
}
.joyride-actions button {
  padding: 5px 12px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
.joyride-next {
  background: #409eff;
  color: #fff;
}

扩展优化说明 #

• 如果网站使用hash路由，只需要把路径匹配逻辑里的window.location.pathname替换为window.location.hash即可
• 可以根据需求增加蒙层、步骤进度显示、跳过整个导览等功能，扩展配置项和渲染逻辑即可
• 如果需要支持用户中途关闭后下次进入继续导览，关闭导览时不清除tour_current_step字段即可，下次启动时会自动从上次中断的步骤继续

内容的提问来源于stack exchange，提问作者vijay s