Barba.js搭配Wordpress时scrollRestoration滚动位置还原异常问题

核心原因 #

当前配置仅禁用了浏览器默认的滚动位置恢复机制，但未主动在新页面进入时触发滚动位置重置，同时barba钩子执行顺序、WordPress主题的DOM结构特性也可能导致滚动重置逻辑失效。

具体修复步骤 #

• 调整滚动重置逻辑的触发时机，将主动重置逻辑放在beforeEnter钩子中执行，确保新内容渲染前就完成滚动位置复位
• 补充barba的基础容器配置，避免WordPress主题默认的DOM结构导致内容替换逻辑异常
• 在after钩子中加一层滚动重置的兜底逻辑，覆盖部分浏览器内核的兼容问题

修正后的完整代码 #

// 初始化前就设置滚动恢复模式，优先级更高
if (history.scrollRestoration) {
  history.scrollRestoration = 'manual';
}

barba.init({
  debug: true,
  // 可根据你WordPress主题的实际DOM结构调整容器选择器
  containers: ['[data-barba="container"]'],
  transitions: [{
    name: 'projet-transition',
    from: {
      namespace: [
        'home'
      ]
    },
    to: {
      namespace: [
        'projet'
      ]
    },
    beforeEnter: () => {
      // 主动重置滚动位置到顶部
      window.scrollTo(0, 0);
      // 如果你用的是自定义滚动容器，替换为对应元素的scrollTop设置即可：document.querySelector('.主内容区选择器').scrollTop = 0
    },
    enter(data) {
        console.log(data)
    },
    leave(data) {
      console.log(data)
    },
  }]
});

// 兜底逻辑：所有过渡完成后再校验一次滚动位置
barba.hooks.after(() => {
  if (window.scrollY !== 0) {
    window.scrollTo(0, 0);
  }
});

WordPress适配的同类方案参考 #

如果觉得barba.js的命名空间、配置规则适配WordPress主题比较麻烦，可以改用pjax+anime.js的轻量组合：

• 只需要指定需要替换的内容容器（比如大部分主题默认的主内容区#primary），不需要额外的命名空间标注
• 可以直接对接WordPress原生的wp_enqueue_script机制加载依赖，和现有主题的兼容性更好，不需要大范围修改主题的DOM结构

额外排查点 #

如果配置后问题仍然存在，检查你的WordPress主题是否自带自定义滚动监听、平滑滚动组件，这类组件会覆盖你设置的scrollTo逻辑，需要在过渡执行前临时禁用这类组件的滚动锁定逻辑。

内容的提问来源于stack exchange，提问作者Beatles BOB