From: Eduardo San Martin Morote Date: Tue, 8 Sep 2020 16:11:31 +0000 (+0200) Subject: docs(api): add missing functions X-Git-Tag: v4.0.0-beta.10~47 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f95f86f71746d031dee4c4fff293b560cca80dd;p=thirdparty%2Fvuejs%2Frouter.git docs(api): add missing functions --- diff --git a/docs/api/index.md b/docs/api/index.md index 218cafc6..5a792ea7 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -54,7 +54,7 @@ Setting `replace` prop will call `router.replace()` instead of `router.push()` w ### active-class - type: `string` -- default: `"router-link-active"` (or global [`routerLinkActiveClass`](#TODO)) +- default: `"router-link-active"` (or global [`linkActiveClass`](#linkactiveclass)) Class to apply on the rendered `a` when the link is active. @@ -81,7 +81,7 @@ Whether `` should not wrap its content in an `` element. Useful ### exact-active-class - type: `string` -- default: `"router-link-exact-active"` (or global [`routerLinkExactActiveClass`](#TODO)) +- default: `"router-link-exact-active"` (or global [`linkExactActiveClass`](#linkexactactiveclass)) Class to apply when the link is exact active. @@ -89,7 +89,9 @@ Class to apply when the link is exact active. `` exposes a low level customization through a [scoped slot](https://v3.vuejs.org/guide/component-slots.html#scoped-slots). This is a more advanced API that primarily targets library authors but can come in handy for developers as well, to build a custom component like a _NavLink_ or other. -\*\*Remember to pass the `custom` option to `` to prevent it from wrapping its content inside of an `` element. +:::tip +Remember to pass the `custom` option to `` to prevent it from wrapping its content inside of an `` element. +::: ```html
  • ` has a `name`, it will render the component with the corre ## createRouter -Creates a Router instance that can be used by a Vue app. +Creates a Router instance that can be used by a Vue app. Check the [RouterOptions](#routeroptions) for a list of all the properties that can be passed. **Signature:** @@ -155,9 +158,113 @@ export declare function createRouter(options: RouterOptions): Router ### Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------- | -------------------------------- | -| options | [`RouterOptions`](./vue-router-interface#routeroptions) | Options to initialize the router | +| Parameter | Type | Description | +| --------- | ------------------------------- | -------------------------------- | +| options | [RouterOptions](#routeroptions) | Options to initialize the router | + +## RouterOptions + +### history + +History implementation used by the router. Most web applications should use `createWebHistory` but it requires the server to be properly configured. You can also use a _hash_ based history with `createWebHashHistory` that does not require any configuration on the server but isn't handled at all by search engines and does poorly on SEO. + +**Signature:** + +```typescript +history: RouterHistory +``` + +#### Examples + +```js +createRouter({ + history: createWebHistory(), + // other options... +}) +``` + +### linkActiveClass + +Default class applied to active [RouterLink](#router-link-props). If none is provided, `router-link-active` will be applied. + +**Signature:** + +```typescript +linkActiveClass?: string; +``` + +### linkExactActiveClass + +Default class applied to exact active [RouterLink](#router-link-props). If none is provided, `router-link-exact-active` will be applied. + +**Signature:** + +```typescript +linkExactActiveClass?: string; +``` + +### parseQuery + +Custom implementation to parse a query. See its counterpart, [stringifyQuery](#stringifyquery). + +**Signature:** + +```typescript +parseQuery?: typeof originalParseQuery; +``` + +#### Examples + +Let's say you want to use the package [qs](https://github.com/ljharb/qs) to parse queries, you can provide both `parseQuery` and `stringifyQuery`: + +```js +import qs from 'qs' + +createRouter({ + // other options... + parse: qs.parse, + stringifyQuery: qs.stringify, +}) +``` + +### routes + +Initial list of routes that should be added to the router. + +**Signature:** + +```typescript +routes: RouteRecordRaw[]; +``` + +### scrollBehavior + +Function to control scrolling when navigating between pages. Can return a Promise to delay scrolling. Check . + +**Signature:** + +```typescript +scrollBehavior?: ScrollBehavior; +``` + +#### Examples + +```js +function scrollBehavior(to, from, savedPosition) { + // `to` and `from` are both route locations + // `savedPosition` can be null if there isn't one +} +``` + +### stringifyQuery + +Custom implementation to stringify a query object. Should not prepend a leading `?`. [parseQuery](#parsequery) counterpart to handle query parsing. + +**Signature:** + +```typescript +stringifyQuery?: typeof originalStringifyQuery; +``` ## createWebHistory @@ -216,7 +323,7 @@ createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/in ## createMemoryHistory -Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. It's up to the user to replace that location with the starter location. +Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. It's up to the user to replace that location with the starter location by either calling `router.push` or `router.replace`. **Signature:** @@ -226,10 +333,78 @@ export declare function createMemoryHistory(base?: string): RouterHistory ### Parameters -| Parameter | Type | Description | -| --------- | ------ | ----------------------------------------- | -| base | string | Base applied to all urls, defaults to '/' | +| Parameter | Type | Description | +| --------- | -------- | ----------------------------------------- | +| base | `string` | Base applied to all urls, defaults to '/' | ### Returns a history object that can be passed to the router constructor + +## NavigationFailureType + +Enumeration with all possible types for navigation failures. Can be passed to [isNavigationFailure](#isnavigationfailure) to check for specific failures. **Never use any of the numerical values**, always use the variables like `NavigationFailureType.aborted`. + +**Signature:** + +```typescript +export declare enum NavigationFailureType +``` + +### Members + +| Member | Value | Description | +| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | +| aborted | 4 | An aborted navigation is a navigation that failed because a navigation guard returned `false` or called `next(false)` | +| cancelled | 8 | A cancelled navigation is a navigation that failed because a more recent navigation finished started (not necessarily finished). | +| duplicated | 16 | A duplicated navigation is a navigation that failed because it was initiated while already being at the exact same location. | + +## Composition API + +### onBeforeRouteLeave + +Add a navigation guard that triggers whenever the component for the current location is about to be left. Similar to but can be used in any component. The guard is removed when the component is unmounted. + +**Signature:** + +```typescript +export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void +``` + +#### Parameters + +| Parameter | Type | Description | +| ---------- | --------------- | ----------------------------------- | +| leaveGuard | NavigationGuard | [NavigationGuard](#navigationguard) | + +### onBeforeRouteUpdate + +Add a navigation guard that triggers whenever the current location is about to be updated. Similar to but can be used in any component. The guard is removed when the component is unmounted. + +**Signature:** + +```typescript +export declare function onBeforeRouteUpdate(updateGuard: NavigationGuard): void +``` + +#### Parameters + +| Parameter | Type | Description | +| ----------- | --------------- | ----------------------------------- | +| updateGuard | NavigationGuard | [NavigationGuard](#navigationguard) | + +### useLink + +TODO: + +### useRoute + +TODO: + +### useRouter + +TODO: + +## TypeScript + +Here are some of the interfaces and types used by Vue Router. The documentation references them to give you an idea of the existing properties in objects. diff --git a/docs/api/vue-router-enum.md b/docs/api/vue-router-enum.md index 6c41db3d..19f3a0d7 100644 --- a/docs/api/vue-router-enum.md +++ b/docs/api/vue-router-enum.md @@ -3,21 +3,3 @@ sidebar: auto --- # Enum - -## NavigationFailureType - -Enumeration with all possible types for navigation failures. Can be passed to to check for specific failures. - -**Signature:** - -```typescript -export declare enum NavigationFailureType -``` - -### Members - -| Member | Value | Description | -| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | -| aborted | 4 | An aborted navigation is a navigation that failed because a navigation guard returned `false` or called `next(false)` | -| cancelled | 8 | A cancelled navigation is a navigation that failed because a more recent navigation finished started (not necessarily finished). | -| duplicated | 16 | A duplicated navigation is a navigation that failed because it was initiated while already being at the exact same location. | diff --git a/docs/api/vue-router-function.md b/docs/api/vue-router-function.md index bb3f1528..df79f12c 100644 --- a/docs/api/vue-router-function.md +++ b/docs/api/vue-router-function.md @@ -6,38 +6,6 @@ ## isNavigationFailure -## onBeforeRouteLeave - -Add a navigation guard that triggers whenever the component for the current location is about to be left. Similar to but can be used in any component. The guard is removed when the component is unmounted. - -**Signature:** - -```typescript -export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void -``` - -### Parameters - -| Parameter | Type | Description | -| ---------- | --------------- | --------------------------------------------------------- | -| leaveGuard | NavigationGuard | [NavigationGuard](./vue-router-interface#navigationguard) | - -## onBeforeRouteUpdate - -Add a navigation guard that triggers whenever the current location is about to be updated. Similar to but can be used in any component. The guard is removed when the component is unmounted. - -**Signature:** - -```typescript -export declare function onBeforeRouteUpdate(updateGuard: NavigationGuard): void -``` - -### Parameters - -| Parameter | Type | Description | -| ----------- | --------------- | --------------------------------------------------------- | -| updateGuard | NavigationGuard | [NavigationGuard](./vue-router-interface#navigationguard) | - ## parseQuery Transforms a queryString into a [LocationQuery](./vue-router-typealias#locationquery) object. Accept both, a version with the leading `?` and without Should work as URLSearchParams diff --git a/docs/api/vue-router-interface.md b/docs/api/vue-router-interface.md index 478b5162..5ad439f4 100644 --- a/docs/api/vue-router-interface.md +++ b/docs/api/vue-router-interface.md @@ -603,114 +603,6 @@ Where to redirect if the route is directly matched. The redirection happens befo redirect: _RouteRecordBase['redirect'] | undefined ``` -## RouterOptions - -### Methods - -### Properties - -#### history - -History implementation used by the router. Most web applications should use `createWebHistory` but it requires the server to be properly configured. You can also use a _hash_ based history with `createWebHashHistory` that does not require any configuration on the server but isn't handled at all by search engines and does poorly on SEO. - -**Signature:** - -```typescript -history: RouterHistory -``` - -### Examples - -```js -createRouter({ - history: createWebHistory(), - // other options... -}) -``` - -#### linkActiveClass - -Default class applied to active [RouterLink](./vue-router-variable#routerlink). If none is provided, `router-link-active` will be applied. - -**Signature:** - -```typescript -linkActiveClass?: string; -``` - -#### linkExactActiveClass - -Default class applied to exact active [RouterLink](./vue-router-variable#routerlink). If none is provided, `router-link-exact-active` will be applied. - -**Signature:** - -```typescript -linkExactActiveClass?: string; -``` - -#### parseQuery - -Custom implementation to parse a query. See its counterpart, [stringifyQuery](./vue-router-interface#routeroptions.stringifyquery). - -**Signature:** - -```typescript -parseQuery?: typeof originalParseQuery; -``` - -### Examples - -Let's say you want to use the package [qs](https://github.com/ljharb/qs) to parse queries, you can provide both `parseQuery` and `stringifyQuery`: - -```js -import qs from 'qs' - -createRouter({ - // other options... - parse: qs.parse, - stringifyQuery: qs.stringify, -}) -``` - -#### routes - -Initial list of routes that should be added to the router. - -**Signature:** - -```typescript -routes: RouteRecordRaw[]; -``` - -#### scrollBehavior - -Function to control scrolling when navigating between pages. Can return a Promise to delay scrolling. Check . - -**Signature:** - -```typescript -scrollBehavior?: ScrollBehavior; -``` - -### Examples - -```js -function scrollBehavior(to, from, savedPosition) { - // `to` and `from` are both route locations - // `savedPosition` can be null if there isn't one -} -``` - -#### stringifyQuery - -Custom implementation to stringify a query object. Should not prepend a leading `?`. [parseQuery](./vue-router-interface#routeroptions.parsequery) counterpart to handle query parsing. - -**Signature:** - -```typescript -stringifyQuery?: typeof originalStringifyQuery; -``` - ### Methods ### Properties diff --git a/src/history/memory.ts b/src/history/memory.ts index 93f4b80a..f3dfec60 100644 --- a/src/history/memory.ts +++ b/src/history/memory.ts @@ -10,11 +10,10 @@ import { HistoryLocation, } from './common' -// TODO: verify base is working for SSR - /** * Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. - * It's up to the user to replace that location with the starter location. + * It's up to the user to replace that location with the starter location by either calling `router.push` or `router.replace`. + * * @param base - Base applied to all urls, defaults to '/' * @returns a history object that can be passed to the router constructor */