From: Eduardo San Martin Morote Date: Fri, 11 Sep 2020 15:04:38 +0000 (+0200) Subject: docs(api): formatted version of RouteRecordRaw X-Git-Tag: v4.0.0-beta.10~27 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cada52d53704752f0e3393c72f77239ac0a3d4ba;p=thirdparty%2Fvuejs%2Frouter.git docs(api): formatted version of RouteRecordRaw --- diff --git a/docs/api/index.md b/docs/api/index.md index e7310ce7..00eaafc6 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -358,7 +358,7 @@ Here are some of the interfaces and types used by Vue Router. The documentation ### currentRoute -Current [RouteLocationNormalized](./vue-router-interface#routelocationnormalized) +Current [RouteLocationNormalized](#routelocationnormalized) **Signature:** @@ -380,7 +380,7 @@ readonly options: RouterOptions; ### addRoute -Add a new [Route Record](./vue-router-typealias#routerecordraw) as the child of an existing route. +Add a new [Route Record](.#routerecordraw) as the child of an existing route. **Signature:** @@ -397,7 +397,7 @@ _Parameters_ ### addRoute -Add a new [route record](./vue-router-typealias#routerecordraw) to the router. +Add a new [route record](#routerecordraw) to the router. **Signature:** @@ -439,7 +439,7 @@ router.afterEach((to, from, failure) => { ### back -Go back in history if possible by calling `history.back()`. Equivalent to `router.go(-1)`. Returns a Promise. See the limitations at [go](./vue-router-interface#router.go). +Go back in history if possible by calling `history.back()`. Equivalent to `router.go(-1)`. Returns a Promise. See the limitations at [`router.go()`](#go). **Signature:** @@ -511,7 +511,7 @@ _Parameters_ ### getRoutes -Get a full list of all the [route records](./vue-router-typealias#routerecord). +Get a full list of all the [route records](#routerecord). **Signature:** @@ -759,70 +759,149 @@ Custom implementation to stringify a query object. Should not prepend a leading stringifyQuery?: typeof originalStringifyQuery; ``` -## NavigationFailure +## RouteRecordRaw -Extended Error that contains extra information regarding a failed navigation. +Route record that can be provided by the user when adding routes via the [`routes` option](#routeroptions) or via [`router.addRoutes()`](#addroutes). There are three different kind of route records: -**Signature:** +- Single views records: have a `component` option +- Multiple views records ([named views](/guide/essentials/named-views.md)): have a `components` option +- Redirect records: cannot have `component` or `components` option because a redirect record is never reached. -```typescript -export interface NavigationFailure extends RouterErrorBase -``` +### path -### Properties +- **Type**: `string` +- **Details**: -#### from + Path of the record. Should start with `/` unless the record is the child of another record. + Can define parameters: `/users/:id` matches `/users/1` as well as `/users/posva`. -Route location we were navigating from +- **See Also**: [Dynamic Route Matching](/guide/essentials/dynamic-matching.md) -**Signature:** +### redirect -```typescript -from: RouteLocationNormalized -``` +- **Type**: [`RouteLocationRaw`](#routelocationraw) (Optional) +- **Details**: -#### to + Where to redirect if the route is directly matched. The redirection happens + before any navigation guard and triggers a new navigation with the new + target location. -Route location we were navigating to +### children -**Signature:** +- **Type**: Array of [`RouteRecordRaw`](#routerecordraw) (Optional) +- **Details**: -```typescript -to: RouteLocationNormalized + Nested routes of the current record. + +- **See Also**: [Nested Routes](/guide/advanced/nested-routes.md) + +### alias + +- **Type**: `string | string[]` (Optional) +- **Details**: + + Aliases for the route. Allows defining extra paths that will behave like a + copy of the record. This enables paths shorthands like `/users/:id` and + `/u/:id`. **All `alias` and `path` values must share the same params**. + +### name + +- **Type**: `string | symbol` (Optional) +- **Details**: + + Unique name for the route record. + +### beforeEnter + +- **Type**: [`NavigationGuard | NavigationGuard[]`](#navigationguard) (Optional) +- **Details**: + + Before enter guard specific to this record. Note `beforeEnter` has no effect if the record has a `redirect` property. + +### meta + +- **Type**: [`RouteMeta`](#routemeta) (Optional) +- **Details**: + + Custom data attached to the record. + +- **See Also**: [Meta fields](/guide/advanced/meta.md) + +## RouteLocationRaw + +User-level route location that can be passed to `router.push()`, `redirect`, and returned in [Navigation Guards](/guide/advanced/navigation-guards.md). + +A raw location can either be a `string` like `/users/posva#bio` or an object: + +```js +// these three forms are equivalent +router.push('/users/posva#bio) +router.push({ path: '/users/posva', hash: '#bio' }) +router.push({ name: 'users', params: { username: 'posva' }, hash: '#bio' }) +// only change the hash +router.push({ hash: '#bio' }) +// only change query +router.push({ query: { page: '2' } }) +// change one param +router.push({ params: { username: 'jolyne' } }) ``` -#### type +Note `path` must be provided encoded (e.g. `phantom blood` becomes `phantom%20blood`) while `params`, `query` and `hash` must not, they are encoded by the router. + +Raw route locations also support an extra option `replace` to call `router.replace()` instead of `router.push()` in navigation guards. Note this also internally calls `router.replace()` even when calling `router.push()`: + +```js +router.push({ hash: '#bio', replace: true }) +// equivalent to +router.replace({ hash: '#bio' }) +``` + +## RouteLocation + +Resolved [RouteLocationRaw](#routelocationraw) that can contain [redirect records](#routerecordraw). Apart from that it has the same properties as [RouteLocationNormalized](#routelocationnormalized). + +## RouteLocationNormalized + +Normalized route location. Does not have any [redirect records](#routerecordraw). In navigation guards, `to` and `from` are always of this type. + +### matched + +Array of [normalized route records](#routerecord). + +## NavigationFailure -Type of the navigation. One of [NavigationFailureType](./vue-router-enum#navigationfailuretype) +Extended Error that contains extra information regarding a failed navigation. **Signature:** ```typescript -type: ErrorTypes.NAVIGATION_CANCELLED | - ErrorTypes.NAVIGATION_ABORTED | - ErrorTypes.NAVIGATION_DUPLICATED +export interface NavigationFailure extends RouterErrorBase ``` -## RouteLocation +### from -[RouteLocationRaw](./vue-router-typealias#routelocationraw) resolved using the matcher +Route location we were navigating from **Signature:** ```typescript -export interface RouteLocation extends _RouteLocationBase +from: RouteLocationNormalized ``` -### matched +### to -Array of [RouteRecord](./vue-router-typealias#routerecord) containing components as they were passed when adding records. It can also contain redirect records. This can't be used directly +Route location we were navigating to **Signature:** ```typescript -matched: RouteRecord[]; +to: RouteLocationNormalized ``` +### type + +Type of the navigation. One of [NavigationFailureType](#navigationfailuretype) + ## NavigationGuard Navigation guard. See [Navigation Guards](/guide/advanced/navigation-guards.md). @@ -852,5 +931,5 @@ export interface NavigationGuard { It can return any value that can be passed to `next` as long as it is omitted from the list of arguments. - `boolean`: Return `true` to accept the navigation or `false` to reject it. -- a [route location](#routelocation) to redirect somewhere else. +- a [route location](#routelocationraw) to redirect somewhere else. - `undefined` (or no `return`). Same as returning `true` diff --git a/docs/api/vue-router-interface.md b/docs/api/vue-router-interface.md index 52360bad..b766d477 100644 --- a/docs/api/vue-router-interface.md +++ b/docs/api/vue-router-interface.md @@ -1,101 +1,5 @@ # Interface -## NavigationGuard - -### Properties - -## RouteLocationMatched - -### Methods - -### Properties - -#### components - -## RouteLocationNormalized - -Similar to [RouteLocation](./vue-router-interface#routelocation) but its [matched](./vue-router-interface#routelocationnormalized.matched) cannot contain redirect records - -**Signature:** - -```typescript -export interface RouteLocationNormalized extends _RouteLocationBase -``` - -### Methods - -### Properties - -#### matched - -Array of [RouteRecordNormalized](./vue-router-interface#routerecordnormalized) - -**Signature:** - -```typescript -matched: RouteRecordNormalized[]; -``` - -## RouteLocationNormalizedLoaded - -[RouteLocationRaw](./vue-router-typealias#routelocationraw) with - -**Signature:** - -```typescript -export interface RouteLocationNormalizedLoaded extends _RouteLocationBase -``` - -### Methods - -### Properties - -#### matched - -Array of [RouteLocationMatched](./vue-router-interface#routelocationmatched) containing only plain components (any lazy-loaded components have been loaded and were replaced inside of the `components` object) so it can be directly used to display routes. It cannot contain redirect records either - -**Signature:** - -```typescript -matched: RouteLocationMatched[]; -``` - -## RouteLocationOptions - -### Methods - -### Properties - -#### force - -Triggers the navigation even if the location is the same as the current one - -**Signature:** - -```typescript -force?: boolean; -``` - -#### replace - -Replace the entry in the history instead of pushing a new entry - -**Signature:** - -```typescript -replace?: boolean; -``` - -#### state - -State to save using the History API. This cannot contain any reactive values and some primitives like Symbols are forbidden. More info [on MDN](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState#Parameters). - -**Signature:** - -```typescript -state?: HistoryState; -``` - ## RouteRecordNormalized Normalized version of a [Route Record](./vue-router-typealias#routerecord) diff --git a/docs/api/vue-router-typealias.md b/docs/api/vue-router-typealias.md index e0499ba1..18441955 100644 --- a/docs/api/vue-router-typealias.md +++ b/docs/api/vue-router-typealias.md @@ -1,44 +1,13 @@ # TypeAlias -## LocationQuery - -Normalized query object that appears in [RouteLocationNormalized](./vue-router-interface#routelocationnormalized) - -**Signature:** -```typescript -export declare type LocationQuery = Record; -``` - -## LocationQueryRaw - -Loose [LocationQuery](./vue-router-typealias#locationquery) object that can be passed to functions like [push](./vue-router-interface#router.push) and [replace](./vue-router-interface#router.replace) or anywhere when creating a [RouteLocationRaw](./vue-router-typealias#routelocationraw) - -**Signature:** -```typescript -export declare type LocationQueryRaw = Record; -``` - -## PathParserOptions - -## RouteLocationRaw - -User-level route location - -**Signature:** -```typescript -export declare type RouteLocationRaw = string | (RouteQueryAndHash & LocationAsPath & RouteLocationOptions) | (RouteQueryAndHash & LocationAsNameRaw & RouteLocationOptions) | (RouteQueryAndHash & LocationAsRelativeRaw & RouteLocationOptions); -``` - -## RouteParams - ## RouteRecord Normalized version of a [Route Record](./vue-router-typealias#routerecord) **Signature:** + ```typescript -export declare type RouteRecord = RouteRecordNormalized; +export declare type RouteRecord = RouteRecordNormalized ``` ## RouteRecordRaw -