路由滚动行为API变更

路由滚动行为API变更

Vue Router的滚动行为API在版本迭代中经历了多次调整，从基础配置到更精细化的控制方式。这些变更直接影响开发者处理页面导航时的滚动位置恢复逻辑，特别是在SPA应用中保持与传统多页应用一致的滚动体验。

早期版本的基础滚动控制

在Vue Router 2.x时代，通过简单的scrollBehavior函数即可定义基本滚动行为：

const router = new VueRouter({
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) {
      return savedPosition
    } else {
      return { x: 0, y: 0 }
    }
  }
})

这种实现存在明显局限性：

• 仅支持同步返回位置对象
• 无法处理异步加载内容的滚动定位
• 缺少对容器滚动的支持（仅限window）

Vue Router 3.x的Promise支持

3.x版本引入了异步解决方案，允许返回Promise对象：

scrollBehavior(to, from, savedPosition) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ x: 0, y: 200 })
    }, 500)
  })
}

典型应用场景包括：

1. 等待动态内容加载完成
2. 配合页面过渡动画时序
3. 需要计算动态元素位置的情况

// 等待特定DOM元素加载
scrollBehavior(to) {
  if (to.hash) {
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({
          selector: to.hash,
          offset: { x: 0, y: 10 }
        })
      }, 800)
    })
  }
}

Vue Router 4.x的重大变更

4.0版本对API进行了彻底重构，主要变化包括：

1. 参数签名变更：

// 新版参数结构
scrollBehavior(to, from, savedPosition) {
  // 返回值为ScrollPosition | ScrollPositionNormalized
}

2. 位置对象标准化：

interface ScrollPositionNormalized {
  left: number
  top: number
  behavior?: ScrollOptions['behavior']
}

3. 容器滚动支持：

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    // 指定滚动容器
    return {
      el: '#app-container',
      top: 100
    }
  }
})

滚动行为与路由元信息结合

现代实践中常配合meta字段实现精细化控制：

routes: [
  {
    path: '/detail/:id',
    component: DetailPage,
    meta: {
      scrollPos: {
        selector: '.comments-section',
        offset: { y: -20 }
      }
    }
  }
]

对应的滚动行为处理：

scrollBehavior(to) {
  if (to.meta.scrollPos) {
    return {
      ...to.meta.scrollPos,
      behavior: 'smooth'
    }
  }
  return { top: 0 }
}

现代浏览器API的集成

利用ScrollToOptions实现高级效果：

scrollBehavior() {
  return {
    top: 500,
    behavior: 'smooth',
    // 新增的现代浏览器特性
    inline: 'center',
    block: 'nearest'
  }
}

处理边界情况的完整示例：

scrollBehavior(to, from, savedPosition) {
  // 浏览器前进/后退时恢复位置
  if (savedPosition) {
    return savedPosition
  }
  
  // 哈希导航定位
  if (to.hash) {
    return {
      el: decodeURIComponent(to.hash),
      behavior: 'smooth',
      top: 20
    }
  }
  
  // 特定路由的特殊处理
  if (to.matched.some(record => record.meta.keepScroll)) {
    return false // 禁止滚动
  }
  
  // 默认行为
  return new Promise(resolve => {
    requestAnimationFrame(() => {
      resolve({ top: 0, left: 0 })
    })
  })
}

与Composition API的协作模式

在setup环境中管理滚动状态：

import { useRouter } from 'vue-router'

export default {
  setup() {
    const router = useRouter()
    
    router.afterEach((to) => {
      if (to.meta.scrollTop !== false) {
        window.scrollTo({
          top: 0,
          behavior: 'auto'
        })
      }
    })
  }
}

动态修改滚动行为的实用技巧：

// 在组件内动态更新滚动目标
onMounted(() => {
  const route = useRoute()
  if (route.query.scrollTo) {
    const target = document.querySelector(route.query.scrollTo)
    target?.scrollIntoView({
      behavior: 'smooth'
    })
  }
})

滚动恢复的竞态条件处理

处理动态内容加载时的常见问题：

scrollBehavior(to) {
  return new Promise((resolve) => {
    const checkContentLoaded = () => {
      const targetEl = document.querySelector(to.hash)
      if (targetEl) {
        resolve({
          el: targetEl,
          behavior: 'smooth'
        })
      } else {
        requestAnimationFrame(checkContentLoaded)
      }
    }
    checkContentLoaded()
  })
}

带超时机制的实现方案：

scrollBehavior(to) {
  return Promise.race([
    new Promise(resolve => {
      const timer = setTimeout(() => {
        resolve({ top: 0 }) // 超时回退
      }, 1000)
      
      const target = document.querySelector(to.hash)
      if (target) {
        clearTimeout(timer)
        resolve({
          el: target,
          offset: { y: 20 }
        })
      }
    }),
    new Promise(resolve => {
      window.addEventListener('DOMContentLoaded', () => {
        const target = document.querySelector(to.hash)
        resolve(target ? { el: target } : { top: 0 })
      }, { once: true })
    })
  ])
}

滚动行为调试技巧

开发环境下的调试工具：

router.afterEach((to, from) => {
  if (process.env.NODE_ENV === 'development') {
    console.log('[Router] Scroll position:', {
      from: from.path,
      to: to.path,
      savedPosition: router.options.scrollBehavior(to, from, null)
    })
  }
})

性能监测实现：

const scrollBehavior = router.options.scrollBehavior
router.options.scrollBehavior = function(...args) {
  const start = performance.now()
  const result = scrollBehavior.apply(this, args)
  
  if (result instanceof Promise) {
    return result.finally(() => {
      console.log(`Scroll took ${performance.now() - start}ms`)
    })
  } else {
    console.log(`Scroll took ${performance.now() - start}ms`)
    return result
  }
}