vue router api · 各種API文檔及教程

# API 參考 [This project is sponsored by?![bit](https://raw.githubusercontent.com/vuejs/vuejs.org/master/themes/vue/source/images/bit-wide.png)](https://www.bitsrc.io/?utm_source=vue&utm_medium=vue&utm_campaign=vue&utm_term=vue&utm_content=vue) ## [#](https://router.vuejs.org/zh/api/#router-link)`<router-link>` `<router-link>`?組件支持用戶在具有路由功能的應用中 (點擊) 導航。通過?`to`?屬性指定目標地址，默認渲染成帶有正確鏈接的?`<a>`?標簽，可以通過配置?`tag`?屬性生成別的標簽.。另外，當目標路由成功激活時，鏈接元素自動設置一個表示激活的 CSS 類名。 `<router-link>`?比起寫死的?`<a href="...">`?會好一些，理由如下： * 無論是 HTML5 history 模式還是 hash 模式，它的表現行為一致，所以，當你要切換路由模式，或者在 IE9 降級使用 hash 模式，無須作任何變動。 * 在 HTML5 history 模式下，`router-link`?會守衛點擊事件，讓瀏覽器不再重新加載頁面。 * 當你在 HTML5 history 模式下使用?`base`?選項之后，所有的?`to`?屬性都不需要寫 (基路徑) 了。 ### [#](https://router.vuejs.org/zh/api/#%E5%B0%86%E6%BF%80%E6%B4%BB-class-%E5%BA%94%E7%94%A8%E5%9C%A8%E5%A4%96%E5%B1%82%E5%85%83%E7%B4%A0)將激活 class 應用在外層元素有時候我們要讓激活 class 應用在外層元素，而不是?`<a>`?標簽本身，那么可以用?`<router-link>`?渲染外層元素，包裹著內層的原生?`<a>`?標簽： ``` <router-link tag="li" to="/foo"> <a>/foo</a> </router-link> ``` 在這種情況下，`<a>`?將作為真實的鏈接 (它會獲得正確的?`href`?的)，而 "激活時的CSS類名" 則設置到外層的?`<li>`。 ## [#](https://router.vuejs.org/zh/api/#router-link-props)`<router-link>`?Props ### [#](https://router.vuejs.org/zh/api/#to)to * 類型:?`string | Location` * required 表示目標路由的鏈接。當被點擊后，內部會立刻把?`to`?的值傳到?`router.push()`，所以這個值可以是一個字符串或者是描述目標位置的對象。 ```  <router-link to="home">Home</router-link>  <a href="home">Home</a>  <router-link v-bind:to="'home'">Home</router-link>  <router-link :to="'home'">Home</router-link>  <router-link :to="{ path: 'home' }">Home</router-link>  <router-link :to="{ name: 'user', params: { userId: 123 }}">User</router-link>  <router-link :to="{ path: 'register', query: { plan: 'private' }}">Register</router-link> ``` ### [#](https://router.vuejs.org/zh/api/#replace)replace * 類型:?`boolean` * 默認值:?`false` 設置?`replace`?屬性的話，當點擊時，會調用?`router.replace()`?而不是?`router.push()`，于是導航后不會留下 history 記錄。 ``` <router-link :to="{ path: '/abc'}" replace></router-link> ``` ### [#](https://router.vuejs.org/zh/api/#append)append * 類型:?`boolean` * 默認值:?`false` 設置?`append`?屬性后，則在當前 (相對) 路徑前添加基路徑。例如，我們從?`/a`?導航到一個相對路徑?`b`，如果沒有配置?`append`，則路徑為?`/b`，如果配了，則為?`/a/b` ``` <router-link :to="{ path: 'relative/path'}" append></router-link> ``` ### [#](https://router.vuejs.org/zh/api/#tag)tag * 類型:?`string` * 默認值:?`"a"` 有時候想要?`<router-link>`?渲染成某種標簽，例如?`<li>`。于是我們使用?`tag`?prop 類指定何種標簽，同樣它還是會監聽點擊，觸發導航。 ``` <router-link to="/foo" tag="li">foo</router-link>  <li>foo</li> ``` ### [#](https://router.vuejs.org/zh/api/#active-class)active-class * 類型:?`string` * 默認值:?`"router-link-active"` 設置鏈接激活時使用的 CSS 類名。默認值可以通過路由的構造選項?`linkActiveClass`?來全局配置。 ### [#](https://router.vuejs.org/zh/api/#exact)exact * 類型:?`boolean` * 默認值:?`false` "是否激活" 默認類名的依據是?inclusive match?(全包含匹配)。舉個例子，如果當前的路徑是?`/a`?開頭的，那么?`<router-link to="/a">`?也會被設置 CSS 類名。按照這個規則，每個路由都會激活`<router-link to="/">`！想要鏈接使用 "exact 匹配模式"，則使用?`exact`?屬性： ```  <router-link to="/" exact> ``` 查看更多關于激活鏈接類名的例子[可運行](https://jsfiddle.net/8xrk1n9f/) ### [#](https://router.vuejs.org/zh/api/#event)event * 類型:?`string | Array<string>` * 默認值:?`'click'` 聲明可以用來觸發導航的事件。可以是一個字符串或是一個包含字符串的數組。 ### [#](https://router.vuejs.org/zh/api/#exact-active-class)exact-active-class * 類型:?`string` * 默認值:?`"router-link-exact-active"` 配置當鏈接被精確匹配的時候應該激活的 class。注意默認值也是可以通過路由構造函數選項?`linkExactActiveClass`?進行全局配置的。 ## [#](https://router.vuejs.org/zh/api/#router-view)`<router-view>` `<router-view>`?組件是一個 functional 組件，渲染路徑匹配到的視圖組件。`<router-view>`?渲染的組件還可以內嵌自己的?`<router-view>`，根據嵌套路徑，渲染嵌套組件。其他屬性 (非 router-view 使用的屬性) 都直接傳給渲染的組件，很多時候，每個路由的數據都是包含在路由參數中。因為它也是個組件，所以可以配合?`<transition>`?和?`<keep-alive>`?使用。如果兩個結合一起用，要確保在內層使用?`<keep-alive>`： ``` <transition> <keep-alive> <router-view></router-view> </keep-alive> </transition> ``` ## [#](https://router.vuejs.org/zh/api/#router-view-props)`<router-view>`?Props ### [#](https://router.vuejs.org/zh/api/#name)name * 類型:?`string` * 默認值:?`"default"` 如果?`<router-view>`設置了名稱，則會渲染對應的路由配置中?`components`?下的相應組件。查看?[命名視圖](https://router.vuejs.org/zh/guide/essentials/named-views.html)?中的例子。 ## [#](https://router.vuejs.org/zh/api/#router-%E6%9E%84%E5%BB%BA%E9%80%89%E9%A1%B9)Router 構建選項 ### [#](https://router.vuejs.org/zh/api/#routes)routes * 類型:?`Array<RouteConfig>` `RouteConfig`?的類型定義： ``` declare type RouteConfig = { path: string; component?: Component; name?: string; // 命名路由 components?: { [name: string]: Component }; // 命名視圖組件 redirect?: string | Location | Function; props?: boolean | string | Function; alias?: string | Array<string>; children?: Array<RouteConfig>; // 嵌套路由 beforeEnter?: (to: Route, from: Route, next: Function) => void; meta?: any; // 2.6.0+ caseSensitive?: boolean; // 匹配規則是否大小寫敏感？(默認值：false) pathToRegexpOptions?: Object; // 編譯正則的選項 } ``` ### [#](https://router.vuejs.org/zh/api/#mode)mode * 類型:?`string` * 默認值:?`"hash" (瀏覽器環境) | "abstract" (Node.js 環境)` * 可選值:?`"hash" | "history" | "abstract"` 配置路由模式: * `hash`: 使用 URL hash 值來作路由。支持所有瀏覽器，包括不支持 HTML5 History Api 的瀏覽器。 * `history`: 依賴 HTML5 History API 和服務器配置。查看?[HTML5 History 模式](https://router.vuejs.org/zh/guide/essentials/history-mode.html)。 * `abstract`: 支持所有 JavaScript 運行環境，如 Node.js 服務器端。如果發現沒有瀏覽器的 API，路由會自動強制進入這個模式。 ### [#](https://router.vuejs.org/zh/api/#base)base * 類型:?`string` * 默認值:?`"/"` 應用的基路徑。例如，如果整個單頁應用服務在?`/app/`?下，然后?`base`?就應該設為?`"/app/"`。 ### [#](https://router.vuejs.org/zh/api/#linkactiveclass)linkActiveClass * 類型:?`string` * 默認值:?`"router-link-active"` 全局配置?`<router-link>`?的默認“激活 class 類名”。參考?[router-link](https://router.vuejs.org/zh/api/#router-link)。 ### [#](https://router.vuejs.org/zh/api/#linkexactactiveclass)linkExactActiveClass * 類型:?`string` * 默認值:?`"router-link-exact-active"` 全局配置?`<router-link>`?精確激活的默認的 class。可同時翻閱?[router-link](https://router.vuejs.org/zh/api/#router-link)。 ### [#](https://router.vuejs.org/zh/api/#scrollbehavior)scrollBehavior * 類型:?`Function` 簽名: ``` type PositionDescriptor = { x: number, y: number } | { selector: string } | ?{} type scrollBehaviorHandler = ( to: Route, from: Route, savedPosition?: { x: number, y: number } ) => PositionDescriptor | Promise<PositionDescriptor> ``` 更多詳情參考[滾動行為](https://router.vuejs.org/zh/guide/advanced/scroll-behavior.html)。 ### [#](https://router.vuejs.org/zh/api/#parsequery-stringifyquery)parseQuery / stringifyQuery * 類型:?`Function` 提供自定義查詢字符串的解析/反解析函數。覆蓋默認行為。 ### [#](https://router.vuejs.org/zh/api/#fallback)fallback * 類型:?`boolean` 當瀏覽器不支持?`history.pushState`?控制路由是否應該回退到?`hash`?模式。默認值為?`true`。在 IE9 中，設置為?`false`?會使得每個?`router-link`?導航都觸發整頁刷新。它可用于工作在 IE9 下的服務端渲染應用，因為一個 hash 模式的 URL 并不支持服務端渲染。 ## [#](https://router.vuejs.org/zh/api/#router-%E5%AE%9E%E4%BE%8B%E5%B1%9E%E6%80%A7)Router 實例屬性 ### [#](https://router.vuejs.org/zh/api/#router-app)router.app * 類型:?`Vue instance` 配置了?`router`?的 Vue 根實例。 ### [#](https://router.vuejs.org/zh/api/#router-mode)router.mode * 類型:?`string` 路由使用的[模式](https://router.vuejs.org/zh/api/#mode)。 ### [#](https://router.vuejs.org/zh/api/#router-currentroute)router.currentRoute * 類型:?`Route` 當前路由對應的[路由信息對象](https://router.vuejs.org/zh/api/#%E8%B7%AF%E7%94%B1%E5%AF%B9%E8%B1%A1)。 ## [#](https://router.vuejs.org/zh/api/#router-%E5%AE%9E%E4%BE%8B%E6%96%B9%E6%B3%95)Router 實例方法 ### [#](https://router.vuejs.org/zh/api/#router-beforeeach)router.beforeEach ### [#](https://router.vuejs.org/zh/api/#router-beforeresolve)router.beforeResolve ### [#](https://router.vuejs.org/zh/api/#router-aftereach)router.afterEach 函數簽名： ``` router.beforeEach((to, from, next) => { /* must call `next` */ }) router.beforeResolve((to, from, next) => { /* must call `next` */ }) router.afterEach((to, from) => {}) ``` 增加全局的導航守衛。參考[導航守衛](https://router.vuejs.org/zh/guide/advanced/navigation-guards.html)。在 2.5.0+ 這三個方法都返回一個移除已注冊的守衛/鉤子的函數。 ### [#](https://router.vuejs.org/zh/api/#router-push)router.push ### [#](https://router.vuejs.org/zh/api/#router-replace)router.replace ### [#](https://router.vuejs.org/zh/api/#router-go)router.go ### [#](https://router.vuejs.org/zh/api/#router-back)router.back ### [#](https://router.vuejs.org/zh/api/#router-forward)router.forward 函數簽名： ``` router.push(location, onComplete?, onAbort?) router.replace(location, onComplete?, onAbort?) router.go(n) router.back() router.forward() ``` 動態的導航到一個新 URL。參考[編程式導航](https://router.vuejs.org/zh/guide/essentials/navigation.html)。 ### [#](https://router.vuejs.org/zh/api/#router-getmatchedcomponents)router.getMatchedComponents 函數簽名： ``` const matchedComponents: Array<Component> = router.getMatchedComponents(location?) ``` 返回目標位置或是當前路由匹配的組件數組 (是數組的定義/構造類，不是實例)。通常在服務端渲染的數據預加載時時候。 ### [#](https://router.vuejs.org/zh/api/#router-resolve)router.resolve 函數簽名： ``` const resolved: { location: Location; route: Route; href: string; } = router.resolve(location, current?, append?) ``` 解析目標位置 (格式和?`<router-link>`?的?`to`?prop 一樣)。 * `current`?是當前默認的路由 (通常你不需要改變它) * `append`?允許你在?`current`?路由上附加路徑 (如同?[`router-link`](https://router.vuejs.org/zh/api/#router-link.md-props)) ### [#](https://router.vuejs.org/zh/api/#router-addroutes)router.addRoutes 函數簽名： ``` router.addRoutes(routes: Array<RouteConfig>) ``` 動態添加更多的路由規則。參數必須是一個符合?`routes`?選項要求的數組。 ### [#](https://router.vuejs.org/zh/api/#router-onready)router.onReady 函數簽名： ``` router.onReady(callback, [errorCallback]) ``` 該方法把一個回調排隊，在路由完成初始導航時調用，這意味著它可以解析所有的異步進入鉤子和路由初始化相關聯的異步組件。這可以有效確保服務端渲染時服務端和客戶端輸出的一致。第二個參數?`errorCallback`?只在 2.4+ 支持。它會在初始化路由解析運行出錯 (比如解析一個異步組件失敗) 時被調用。 ### [#](https://router.vuejs.org/zh/api/#router-onerror)router.onError 函數簽名： ``` router.onError(callback) ``` 注冊一個回調，該回調會在路由導航過程中出錯時被調用。注意被調用的錯誤必須是下列情形中的一種： * 錯誤在一個路由守衛函數中被同步拋出； * 錯誤在一個路由守衛函數中通過調用?`next(err)`?的方式異步捕獲并處理； * 渲染一個路由的過程中，需要嘗試解析一個異步組件時發生錯誤。 ## [#](https://router.vuejs.org/zh/api/#%E8%B7%AF%E7%94%B1%E5%AF%B9%E8%B1%A1)路由對象一個路由對象 (route object)?表示當前激活的路由的狀態信息，包含了當前 URL 解析得到的信息，還有 URL 匹配到的路由記錄 (route records)。路由對象是不可變 (immutable) 的，每次成功的導航后都會產生一個新的對象。路由對象出現在多個地方: * 在組件內，即?`this.$route` * 在?`$route`?觀察者回調內 * `router.match(location)`?的返回值 * 導航守衛的參數： ``` router.beforeEach((to, from, next) => { // `to` 和 `from` 都是路由對象 }) ``` * `scrollBehavior`?方法的參數: ``` const router = new VueRouter({ scrollBehavior (to, from, savedPosition) { // `to` 和 `from` 都是路由對象 } }) ``` ### [#](https://router.vuejs.org/zh/api/#%E8%B7%AF%E7%94%B1%E5%AF%B9%E8%B1%A1%E5%B1%9E%E6%80%A7)路由對象屬性 * $route.path * 類型:?`string` 字符串，對應當前路由的路徑，總是解析為絕對路徑，如?`"/foo/bar"`。 * $route.params * 類型:?`Object` 一個 key/value 對象，包含了動態片段和全匹配片段，如果沒有路由參數，就是一個空對象。 * $route.query * 類型:?`Object` 一個 key/value 對象，表示 URL 查詢參數。例如，對于路徑?`/foo?user=1`，則有?`$route.query.user == 1`，如果沒有查詢參數，則是個空對象。 * $route.hash * 類型:?`string` 當前路由的 hash 值 (帶?`#`) ，如果沒有 hash 值，則為空字符串。 * $route.fullPath * 類型:?`string` 完成解析后的 URL，包含查詢參數和 hash 的完整路徑。 * $route.matched * 類型:?`Array<RouteRecord>` 一個數組，包含當前路由的所有嵌套路徑片段的路由記錄?。路由記錄就是?`routes`?配置數組中的對象副本 (還有在?`children`?數組)。 ``` const router = new VueRouter({ routes: [ // 下面的對象就是路由記錄 { path: '/foo', component: Foo, children: [ // 這也是個路由記錄 { path: 'bar', component: Bar } ] } ] }) ``` 當 URL 為?`/foo/bar`，`$route.matched`?將會是一個包含從上到下的所有對象 (副本)。 * $route.name 當前路由的名稱，如果有的話。(查看[命名路由](https://router.vuejs.org/zh/guide/essentials/named-routes.html)) * $route.redirectedFrom 如果存在重定向，即為重定向來源的路由的名字。(參閱[重定向和別名](https://router.vuejs.org/zh/guide/essentials/redirect-and-alias.html)) ## [#](https://router.vuejs.org/zh/api/#%E7%BB%84%E4%BB%B6%E6%B3%A8%E5%85%A5)組件注入 ### [#](https://router.vuejs.org/zh/api/#%E6%B3%A8%E5%85%A5%E7%9A%84%E5%B1%9E%E6%80%A7)注入的屬性通過在 Vue 根實例的?`router`?配置傳入 router 實例，下面這些屬性成員會被注入到每個子組件。 * this.$router router 實例。 * this.$route 當前激活的[路由信息對象](https://router.vuejs.org/zh/api/#%E8%B7%AF%E7%94%B1%E5%AF%B9%E8%B1%A1)。這個屬性是只讀的，里面的屬性是 immutable (不可變) 的，不過你可以 watch (監測變化) 它。 ### [#](https://router.vuejs.org/zh/api/#%E5%A2%9E%E5%8A%A0%E7%9A%84%E7%BB%84%E4%BB%B6%E9%85%8D%E7%BD%AE%E9%80%89%E9%A1%B9)增加的組件配置選項 * beforeRouteEnter * beforeRouteUpdate * beforeRouteLeave 查看[組件內的守衛](https://router.vuejs.org/zh/guide/advanced/navigation-guards.html#%E7%BB%84%E4%BB%B6%E5%86%85%E7%9A%84%E5%AE%88%E5%8D%AB)。