API: router 属性配置

router 属性配置

router 属性让你可以个性化配置 Nuxt.js 应用的路由(vue-router)。

base

  • 类型: String
  • 默认值: '/'

应用的根URL。举个例子,如果整个单页面应用的所有资源可以通过 /app/ 来访问,那么 base 配置项的值需要设置为 '/app/'

例如 (nuxt.config.js):

  1. module.exports = {
  2. router: {
  3. base: '/app/'
  4. }
  5. }

base 被设置后,Nuxt.js 会自动将它添加至页面中: <base href="{{ router.base }}"/>

该配置项的值会被直接传给 vue-router 的构造器

routeNameSplitter

  • 类型: String
  • 默认: '-'

您可能希望更改Nuxt.js使用的路由名称之间的分隔符。您可以通过配置文件中的routeNameSplitter选项执行此操作。想象一下,我们有页面文件pages/posts/_id.vue。Nuxt将以编程方式生成路由名称,在本例中为posts-id。因此,将routeNameSplitter配置修改为/,这样路由名称生成为posts/id

例如 (nuxt.config.js):

  1. export default {
  2. router: {
  3. routeNameSplitter: '/'
  4. }
  5. }

extendRoutes

  • 类型: Function

您可能希望扩展Nuxt.js创建的路由。您可以通过extendRoutes选项执行此操作。

例如添加自定义路由:

nuxt.config.js

  1. export default {
  2. router: {
  3. extendRoutes (routes, resolve) {
  4. routes.push({
  5. name: 'custom',
  6. path: '*',
  7. component: resolve(__dirname, 'pages/404.vue')
  8. })
  9. }
  10. }
  11. }

路由的模式应该遵循vue-router模式。

linkActiveClass

  • 类型: String
  • 默认值: 'nuxt-link-active'

全局配置 <nuxt-link> 组件默认的激活类名。

例如 (nuxt.config.js):

  1. module.exports = {
  2. router: {
  3. linkActiveClass: 'active-link'
  4. }
  5. }

该配置项的值会被直接传给 vue-router 的构造器

linkExactActiveClass

  • 类型: String
  • 默认: 'nuxt-link-exact-active'

全局配置 <nuxt-link> 默认的active class。

例如 (nuxt.config.js):

  1. export default {
  2. router: {
  3. linkExactActiveClass: 'exact-active-link'
  4. }
  5. }

此选项直接提供给vue-router linkexactactiveclass.

linkPrefetchedClass

  • 类型: String
  • 默认: false

全局配置<nuxt-link>默认值(默认情况下禁用功能)

例子 (nuxt.config.js):

  1. export default {
  2. router: {
  3. linkPrefetchedClass: 'nuxt-link-prefetched'
  4. }
  5. }

middleware

  • 类型: StringArray
    • 数值元素类型: String

为应用的每个页面设置默认的中间件。

例如:

nuxt.config.js

  1. module.exports = {
  2. router: {
  3. // 在每页渲染前运行 middleware/user-agent.js 中间件的逻辑
  4. middleware: 'user-agent'
  5. }
  6. }

middleware/user-agent.js

  1. export default function (context) {
  2. // 给上下文对象增加 userAgent 属性(增加的属性可在 `asyncData` 和 `fetch` 方法中获取)
  3. context.userAgent = process.server ? context.req.headers['user-agent'] : navigator.userAgent
  4. }

了解更多关于中间件的信息,请参考 中间件指引文档

mode

  • 类型:String
  • 默认值:'history'

配置路由的模式,鉴于服务端渲染的特性,不建议修改该配置。

示例 (nuxt.config.js):

  1. module.exports = {
  2. router: {
  3. mode: 'hash'
  4. }
  5. }

该配置项的值会被直接传给 vue-router 的构造器

scrollBehavior

  • 类型: Function

scrollBehavior 配置项用于个性化配置跳转至目标页面后的页面滚动位置。每次页面渲染后都会调用 scrollBehavior 配置的方法。

scrollBehavior 的默认配置为:

  1. const scrollBehavior = function (to, from, savedPosition) {
  2. // if the returned position is falsy or an empty object,
  3. // will retain current scroll position.
  4. let position = false
  5. // if no children detected and scrollToTop is not explicitly disabled
  6. if (
  7. to.matched.length < 2 &&
  8. to.matched.every(r => r.components.default.options.scrollToTop !== false)
  9. ) {
  10. // scroll to the top of the page
  11. position = { x: 0, y: 0 }
  12. } else if (to.matched.some(r => r.components.default.options.scrollToTop)) {
  13. // if one of the children has scrollToTop option set to true
  14. position = { x: 0, y: 0 }
  15. }
  16. // savedPosition is only available for popstate navigations (back button)
  17. if (savedPosition) {
  18. position = savedPosition
  19. }
  20. return new Promise((resolve) => {
  21. // wait for the out transition to complete (if necessary)
  22. window.$nuxt.$once('triggerScroll', () => {
  23. // coords will be used if no selector is provided,
  24. // or if the selector didn't match any element.
  25. if (to.hash) {
  26. let hash = to.hash
  27. // CSS.escape() is not supported with IE and Edge.
  28. if (typeof window.CSS !== 'undefined' && typeof window.CSS.escape !== 'undefined') {
  29. hash = '#' + window.CSS.escape(hash.substr(1))
  30. }
  31. try {
  32. if (document.querySelector(hash)) {
  33. // scroll to anchor by returning the selector
  34. position = { selector: hash }
  35. }
  36. } catch (e) {
  37. console.warn('Failed to save scroll position. Please add CSS.escape() polyfill (https://github.com/mathiasbynens/CSS.escape).')
  38. }
  39. }
  40. resolve(position)
  41. })
  42. })
  43. }

举个例子,我们可以配置所有页面渲染后滚动至顶部:

nuxt.config.js

  1. module.exports = {
  2. router: {
  3. scrollBehavior (to, from, savedPosition) {
  4. return { x: 0, y: 0 }
  5. }
  6. }
  7. }

该配置项的值会被直接传给 vue-router 的构造器

parseQuery / stringifyQuery

  • 类型: Function

提供自定义查询字符串解析/字符串化功能。覆盖默认值。

此选项直接提供在vue-router parseQuery / stringifyQuery.

prefetchLinks

Nuxt v2.4.0 添加

  • 类型: Boolean
  • 默认: true

在视图中检测到时,配置<nuxt-link>用来预获取代码分割页面。需要支持IntersectionObserver(参阅 CanIUse)。

我们建议使用Polyfill.io等服务有条件地填充此功能:

nuxt.config.js

  1. export default {
  2. head: {
  3. script: [
  4. { src: 'https://polyfill.io/v2/polyfill.min.js?features=IntersectionObserver', body: true }
  5. ]
  6. }
  7. }

要禁用特定链接上的预取,可以使用no-prefetch 属性:

  1. <nuxt-link to="/about" no-prefetch>About page not pre-fetched</nuxt-link>

要全局禁用所有链接上的预取,请将prefetchLinks设置为false

  1. // nuxt.config.js
  2. export default {
  3. router: {
  4. prefetchLinks: false
  5. }
  6. }

fallback

  • 类型: boolean
  • 默认: false

当浏览器不支持history.pushState但模式设置为history时,控制路由器是否应回退。

将此设置为false实质上会使每个路由器链接导航在IE9中刷新整页。当应用程序是服务器呈现并且需要在IE9中工作时,这很有用,因为hash模式URL不适用于SSR。

此选项直接提供在vue-router fallback.