如何利用`Vue Router`的`scrollBehavior`实现滚动行为？

Vue Router 中的滚动行为：打造流畅的用户体验

大家好，今天我们来深入探讨 Vue Router 中一个非常重要的特性：scrollBehavior。它可以帮助我们精细地控制页面跳转时的滚动行为，从而显著提升用户体验。

1. 为什么需要 scrollBehavior？

在单页应用(SPA)中，页面切换实际上是通过 JavaScript 动态地改变组件内容来实现的，而不是传统的多页面应用那样重新加载整个页面。这意味着浏览器默认的滚动行为可能不符合我们的预期。比如，从一个很长的页面跳转到另一个页面时，用户可能会期望页面回到顶部，或者定位到某个特定的元素。

如果没有 scrollBehavior，我们需要手动编写 JavaScript 代码来处理滚动位置，这不仅繁琐，而且容易出错。scrollBehavior 提供了一种声明式的方式来配置滚动行为，使我们能够更轻松地管理页面跳转时的滚动位置。

2. scrollBehavior 的基本用法

scrollBehavior 是 Vue Router 构造器选项中的一个函数。它接收 to (目标路由对象), from (来源路由对象), 和 savedPosition (如果存在，上次的滚动位置) 三个参数，并返回一个描述新滚动位置的对象。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    // 返回期望的滚动位置
  }
})

scrollBehavior 函数返回的对象可以有以下几种形式：

• { x: number, y: number }: 指定滚动条的横向和纵向位置（单位像素）。

• { selector: string }: 滚动到匹配选择器的元素。

• { selector: string, offset: { x: number, y: number } }: 滚动到匹配选择器的元素，并添加额外的偏移量。

• { el: Element }: 直接滚动到对应的DOM元素。

• undefined 或 null: 保持当前滚动位置。

3. 常见滚动行为的实现

3.1 回到页面顶部

这是最常见的需求，每次页面跳转都将滚动条重置到顶部。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    return { x: 0, y: 0 }
  }
})

3.2 保持滚动位置

如果用户在页面之间导航，并且我们希望保持之前的滚动位置，可以使用 savedPosition。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    if (savedPosition) {
      return savedPosition
    } else {
      return { x: 0, y: 0 } // 默认回到顶部
    }
  }
})

3.3 滚动到特定元素

有时候，我们希望在页面加载后自动滚动到某个特定的元素，例如锚点链接。

<template>
  <div>
    <h1>Page Content</h1>
    <a href="#section1">Go to Section 1</a>
    <div id="section1">
      <h2>Section 1</h2>
      <p>Content of section 1...</p>
    </div>
  </div>
</template>

<script>
export default {
  name: 'MyComponent',
  mounted() {
     if (this.$route.hash) {
        const el = document.getElementById(this.$route.hash.slice(1));
        if(el){
            el.scrollIntoView({ behavior: 'smooth' });
        }
     }
  }
}
</script>

对应的路由配置：

const router = new VueRouter({
  routes: [
    {
      path: '/page',
      component: MyComponent
    }
  ],
  scrollBehavior (to, from, savedPosition) {
     if (to.hash) {
        return {
            selector: to.hash,
            behavior: 'smooth'
        }
      } else {
        return { x: 0, y: 0 }
      }
  }
})

注意：to.hash 包含了 # 符号，我们需要使用 to.hash.slice(1) 来获取元素的 ID。 behavior: 'smooth' 可以让滚动更平滑。

3.4 使用 meta 字段进行动态配置

我们可以利用路由的 meta 字段，根据不同的路由配置不同的滚动行为。

const routes = [
  {
    path: '/page1',
    component: Page1,
    meta: { scrollToTop: true } // 设置 meta 字段
  },
  {
    path: '/page2',
    component: Page2,
    meta: { selector: '#special-element' }
  }
]

const router = new VueRouter({
  routes,
  scrollBehavior (to, from, savedPosition) {
    if (to.meta.scrollToTop) {
      return { x: 0, y: 0 }
    }
    if (to.meta.selector) {
      return { selector: to.meta.selector }
    }
    if (savedPosition) {
      return savedPosition
    }
    return { x: 0, y: 0 }
  }
})

3.5 结合过渡动画

在页面切换时，过渡动画可能会影响滚动行为。我们需要确保在过渡动画完成后再进行滚动。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    return new Promise((resolve, reject) => {
      setTimeout(() => { // 模拟过渡动画延迟
        if (to.hash) {
            resolve({ selector: to.hash, behavior: 'smooth' })
        } else if (savedPosition) {
          resolve(savedPosition)
        } else {
          resolve({ x: 0, y: 0 })
        }
      }, 500) // 延迟 500 毫秒
    })
  }
})

更优雅的做法是使用 nextTick 配合 Vue.transition 事件。

3.6 处理异步组件

如果路由组件是异步加载的，scrollBehavior 函数可能会在组件加载完成之前执行，导致无法找到目标元素。为了解决这个问题，我们可以使用 Vue.nextTick 来确保组件已经渲染到 DOM 中。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    return new Promise((resolve, reject) => {
      Vue.nextTick(() => {
        if (to.hash) {
          const element = document.querySelector(to.hash);
          if (element) {
              resolve({ el: element, behavior: 'smooth' });
          } else {
              resolve({ x: 0, y: 0 });
          }
        } else if (savedPosition) {
          resolve(savedPosition);
        } else {
          resolve({ x: 0, y: 0 });
        }
      });
    });
  }
});

3.7 动态计算偏移量

有时候我们需要根据一些动态因素来计算偏移量，比如固定头部的高度。

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    const headerHeight = document.querySelector('header').offsetHeight // 获取头部高度
    if (to.hash) {
      return {
        selector: to.hash,
        offset: { x: 0, y: -headerHeight } // 减去头部高度
      }
    } else if (savedPosition) {
      return savedPosition
    } else {
      return { x: 0, y: 0 }
    }
  }
})

4. 示例：一个更复杂的 scrollBehavior

下面是一个更复杂的例子，它结合了多种情况的处理：

const router = new VueRouter({
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    return new Promise((resolve, reject) => {
      // 1. 处理锚点链接
      if (to.hash) {
        Vue.nextTick(() => {
          const element = document.querySelector(to.hash);
          if (element) {
            const headerHeight = document.querySelector('header') ? document.querySelector('header').offsetHeight : 0;
            resolve({
                el: element,
                behavior: 'smooth',
                top: -headerHeight // 考虑固定头部
            });
          } else {
             resolve({ x: 0, y: 0 }); // 找不到元素回到顶部
          }
        });
      }
      // 2. 恢复滚动位置
      else if (savedPosition) {
        resolve(savedPosition)
      }
      // 3. 根据 meta 字段滚动到顶部或特定元素
      else if (to.matched.some(record => record.meta.scrollToTop)) {
        resolve({ x: 0, y: 0 })
      } else if (to.matched.some(record => record.meta.selector)) {
        const selector = to.matched.find(record => record.meta.selector).meta.selector;
        resolve({ selector });
      }
      // 4. 默认回到顶部
      else {
        resolve({ x: 0, y: 0 })
      }
    })
  }
})

这个例子考虑了以下情况：

• 锚点链接（to.hash）
• 恢复之前的滚动位置（savedPosition）
• 根据路由 meta 字段滚动到顶部或特定元素
• 默认回到顶部

5. scrollBehavior 的注意事项

• 异步组件: 确保在异步组件加载完成后再进行滚动操作，可以使用 Vue.nextTick。
• 过渡动画: 过渡动画可能会影响滚动行为，可以使用 setTimeout 或 Vue.transition 事件来延迟滚动。
• 固定头部: 如果页面有固定头部，需要计算偏移量，防止内容被头部遮挡。
• behavior: 'smooth': 使用 behavior: 'smooth' 可以使滚动更平滑，但不是所有浏览器都支持。
• 性能优化: 避免在 scrollBehavior 函数中执行耗时的操作，因为它会在每次路由切换时执行。
• 类型安全: 确保 scrollBehavior 函数返回的对象类型正确，可以使用 TypeScript 来增强类型安全。

6. 表格：scrollBehavior 参数和返回值总结

参数	类型	描述
to	Object	目标路由对象
from	Object	来源路由对象
savedPosition	Object	如果存在，上次的滚动位置。只有在使用 popstate 导航 (例如点击浏览器的后退/前进按钮) 时才可用。

返回值形式	描述
{ x: number, y: number }	指定滚动条的横向和纵向位置（单位像素）。例如：{ x: 0, y: 100 }
{ selector: string }	滚动到匹配选择器的元素。例如：{ selector: '#element-id' }
{ selector: string, offset: { x: number, y: number } }	滚动到匹配选择器的元素，并添加额外的偏移量。例如：{ selector: '#element-id', offset: { x: 0, y: -50 } } 这在有固定头部时很有用。
{ el: Element }	直接滚动到对应的DOM元素。例如: { el: document.getElementById('element-id') }。
undefined 或 null	保持当前滚动位置。

7. 常见的坑与技巧

• 锚点链接不生效： 检查是否使用了正确的选择器，以及目标元素是否已经渲染到 DOM 中。
• 滚动位置不准确： 可能是因为固定头部或其他元素的影响，需要计算正确的偏移量。
• 过渡动画导致滚动异常： 可以使用 setTimeout 或 Vue.transition 事件来延迟滚动。
• 在 beforeRouteEnter 中使用 scrollBehavior: beforeRouteEnter 无法访问 this，因此不能直接操作 DOM。可以将滚动逻辑放在 mounted 钩子中，或者使用 scrollBehavior 函数。
• 使用自定义指令： 可以将一些常用的滚动行为封装成自定义指令，方便在组件中使用。

8. 总结：灵活运用 scrollBehavior，优化用户体验

Vue Router 的 scrollBehavior 提供了一种强大而灵活的方式来控制页面跳转时的滚动行为。 掌握 scrollBehavior 的用法，并结合实际需求进行配置，可以显著提升单页应用的用户体验。通过本文的讲解，相信你已经对 scrollBehavior 有了更深入的理解，并能够在实际项目中灵活运用。