Você está navegando a documentação da v2.x e anterior. Para a v3.x, clique aqui.

Migração do Vue Router 0.7.x

Somente Vue Router 2 é compatível com Vue 2, então se você estiver atualizando o Vue, terá de atualizar também o Vue Router. Esta é a razão pela qual incluímos detalhes de migração aqui na documentação principal. Para um guia completo em como usar o novo Vue Router, veja a documentação do Vue Router.

Inicialização do Roteador

router.start ^obsoleto

Não há mais uma API especial para inicializar um aplicativo com Vue Router. Em vez de:

router.start({
  template: '<router-view></router-view>'
}, '#app')

Passe uma propriedade router para a instância Vue:

new Vue({
  el: '#app',
  router: router,
  template: '<router-view></router-view>'
})

Ou, se estiver usando a compilação runtime-only do Vue:

new Vue({
  el: '#app',
  router: router,
  render: h => h('router-view')
})

Definição de Rotas

router.map ^alterado

Rotas são agora definidas como um Array em uma opção routes na inicialização do roteador. Então estas rotas, por exemplo:

router.map({
  '/foo': {
    component: Foo
  },
  '/bar': {
    component: Bar
  }
})

Serão definidas desta forma:

var router = new VueRouter({
  routes: [
    { path: '/foo', component: Foo },
    { path: '/bar', component: Bar }
  ]
})

A sintaxe com Array oferece mais precisão na definição de rotas, uma vez que ao iterar sobre objetos não existe garantia da mesma ordem de propriedades entre navegadores.

router.on ^removido

Se você precisar programaticamente gerar rotas quando iniciar a aplicação, é possível fazer isso acrescentando dinamicamente definições a um Array de rotas. Por exemplo:

// Rotas base normais
var routes = [
  // ...
]

// Rotas geradas dinamicamente
marketingPages.forEach(function (page) {
  routes.push({
    path: '/marketing/' + page.slug
    component: {
      extends: MarketingComponent
      data: function () {
        return { page: page }
      }
    }
  })
})

var router = new Router({
  routes: routes
})

Se houver necessidade de adicionar rotas após a inicialização, é possível substituir a função de identificação de rotas com uma nova que inclua a rota que você deseja adicionar:

router.match = createMatcher(
  [{
    path: '/my/new/path',
    component: MyComponent
  }].concat(router.options.routes)
)

router.beforeEach ^alterado

router.beforeEach agora trabalha assincronamente e recebe uma função next como seu terceiro argumento.

router.beforeEach(function (transition) {
  if (transition.to.path === '/forbidden') {
    transition.abort()
  } else {
    transition.next()
  }
})

router.beforeEach(function (to, from, next) {
  if (to.path === '/forbidden') {
    next(false)
  } else {
    next()
  }
})

subRoutes ^renomeado

Renomeado para children para consistência com Vue e com outras bibliotecas de rotas.

router.redirect ^alterado

Isto agora é uma opção da definição de uma rota. Então, por exemplo, você atualizará:

router.redirect({
  '/tos': '/terms-of-service'
})

Para uma definição conforme exibido abaixo, na configuração de suas routes:

{
  path: '/tos',
  redirect: '/terms-of-service'
}

router.alias ^alterado

Isto agora é uma opção da definição da rota de destino. Então, por exemplo, você atualizará:

router.alias({
  '/manage': '/admin'
})

Para uma definição conforme exibido abaixo, na configuração de suas routes:

{
  path: '/admin',
  component: AdminPanel,
  alias: '/manage'
}

Se você precisar de múltiplos apelidos, é possível usar uma sintaxe de Array:

alias: ['/manage', '/administer', '/administrate']

Propriedades Arbitrárias em Rotas ^substituído

Propriedades definidas arbitrariamente em rotas agora precisam estar inseridas em uma nova propriedade meta, para evitar conflitos com atualizações futuras. Então, por exemplo:

'/admin': {
  component: AdminPanel,
  requiresAuth: true
}

Deverá ser atualizado para:

{
  path: '/admin',
  component: AdminPanel,
  meta: {
    requiresAuth: true
  }
}

Assim, quando estiver acessando posteriormente esta propriedade da rota, será necessário também seguir através de meta. Por exemplo:

if (route.meta.requiresAuth) {
  // ...
}

Sintaxe para Arrays em Queries ^removed

Ao passar Arrays como parâmetros de queries, a sintaxe da query string não é mais /foo?users[]=Tom&users[]=Jerry. Em vez disto, a nova sintaxe é /foo?users=Tom&users=Jerry. Internamente, $route.query.users ainda será um Array, mas se houver somente um parâmetro na query: /foo?users=Tom, ao acessar diretamente esta rota, não haverá uma maneira do roteador saber se estamos esperando que users seja um Array. Por este motivo, considere adicionar um dado computado, substituindo qualquer acesso a $route.query.users por ele:

export default {
  // ...
  computed: {
    // assim, `users` serão serão um Array
    users () {
      const users = this.$route.query.users
      return Array.isArray(users) ? users : [users]
    }
  }
}

Identificação das Rotas

Agora a identificação das rotas utiliza path-to-regexp em seu interior, tornando-a muito mais flexível do que anteriormente.

Um ou Mais Parâmetros Nomeados ^alterado

A sintaxe mudou levemente, assim /category/*tags, por exemplo, deveria ser atualizado para /category/:tags+.

Links

v-link ^substituído

A diretiva v-link foi substituída por um novo componente <router-link>, visto que este tipo de tarefa é exclusivamente responsabilidade de componentes no Vue 2. Isso significa que em qualquer lugar que você tiver um link como este:

<a v-link="'/about'">Sobre</a>

Você precisará atualizá-lo desta forma:

<router-link to="/about">Sobre</router-link>

Observe que target="_blank" não é suportado no <router-link>, então se precisar forçar um link a abrir em uma nova aba, terá de utilizar <a> em seu lugar.

v-link-active ^substituído

A diretiva v-link-active também foi removida em favor de se especificar uma tag separada no componente <router-link>. Então, por exemplo, você irá atualizar isto:

<li v-link-active>
  <a v-link="'/about'">Sobre</a>
</li>

Para isto:

<router-link tag="li" to="/about">
  <a>Sobre</a>
</router-link>

O elemento <a> será efetivamente o link (e obterá corretamente o href), mas a classe de estado ativo será aplicada ao elemento externo <li>.

Navegação Programática

router.go ^changed

Para consistência com a HTML5 History API, router.go agora é usado somente para navegação de voltar/avançar, enquanto router.push é usado para navegação para uma página específica.

Opções do Roteador: Modos

hashbang: false ^removido

Hashbangs não são mais exigidos pelo Google para indexar uma URL, assim não são mais uma opção padrão (ou mesmo uma opção existente) para a estratégia de hash.

history: true ^substituído

Todos os modos de roteamento foram condensados em uma simples opção mode. Atualize:

var router = new VueRouter({
  history: true
})

Para:

var router = new VueRouter({
  mode: 'history'
})

abstract: true ^substituído

Todos os modos de roteamento foram condensados em uma simples opção mode. Atualize:

var router = new VueRouter({
  abstract: true
})

Para:

var router = new VueRouter({
  mode: 'abstract'
})

Opções do Roteador: Diversos

saveScrollPosition ^substituído

Foi substituído com uma opção scrollBehavior que aceita uma função, de forma que o comportamento de rolagem possa ser completamente personalizado - inclusive para cada rota. Abre-se muitas novas possibilidades, mas para simplesmente replicar o antigo comportamento de:

saveScrollPosition: true

Você pode substituir com uma função como esta:

scrollBehavior: function (to, from, savedPosition) {
  return savedPosition || { x: 0, y: 0 }
}

root ^renomeado

Renomeado para base para consistência com o elemento HTML <base>.

transitionOnLoad ^removido

Esta opção não é mais necessária agora que o sistema de transições do Vue tem explícito controle de appear de transições.

suppressTransitionError ^removido

Removido para simplificação de gatilhos. Se você realmente precisar suprimir erros de transição, você pode usar try…catch para isto.

Gatilhos do Roteador

activate ^substituído

Em seu lugar, use beforeRouteEnter no componente.

canActivate ^substituído

Em seu lugar, use beforeEnter no roteador.

deactivate ^removido

Em seu lugar, use os gatilhos em componentes beforeDestroy ou destroyed.

canDeactivate ^substituído

Em seu lugar, use beforeRouteLeave no componente.

canReuse: false ^removido

Não existem mais casos de uso para isso no novo Vue Router.

data ^substituído

A propriedade $route agora é reativa, desta forma utilize um observador para reagir a mudanças de rota, como neste exemplo:

watch: {
  '$route': 'fetchData'
},
methods: {
  fetchData: function () {
    // ...
  }
}

$loadingRouteData ^removido

Defina sua própria propriedade (por exemplo, isLoading) e atualize a situação através de um observador na rota. Por exemplo, se estiver obtendo dados remotos com o axios:

data () {
  return {
    posts: [],
    isLoading: false,
    fetchError: null
  }
},
watch: {
  '$route': () => {
    this.isLoading = true
    this.fetchData().then(() => {
      this.isLoading = false
    })
  }
},
methods: {
  fetchData: () => {
    return axios.get('/api/posts')
      .then(response => {
        this.posts = response.data.posts
      })
      .catch(error => {
        this.fetchError = error
      })
  }
}