From 51f0182221dfbc9e87a15fd6a5aae06a39513fd9 Mon Sep 17 00:00:00 2001 From: Eduardo San Martin Morote Date: Tue, 11 Jun 2024 12:09:34 +0200 Subject: [PATCH] docs: fix links --- .../docs/guide/advanced/navigation-guards.md | 4 +- .../docs/guide/essentials/active-links.md | 14 +++---- .../docs/guide/essentials/dynamic-matching.md | 17 ++++---- packages/docs/guide/migration/index.md | 2 +- packages/docs/typedoc-markdown.mjs | 2 +- packages/docs/zh/guide/migration/index.md | 4 +- packages/router/src/index.ts | 39 ++++++++++++++++++ packages/router/src/typed-routes/index.ts | 41 +++---------------- .../router/src/typed-routes/route-location.ts | 6 +-- 9 files changed, 69 insertions(+), 60 deletions(-) diff --git a/packages/docs/guide/advanced/navigation-guards.md b/packages/docs/guide/advanced/navigation-guards.md index 059328d3..12975df3 100644 --- a/packages/docs/guide/advanced/navigation-guards.md +++ b/packages/docs/guide/advanced/navigation-guards.md @@ -25,8 +25,8 @@ Global before guards are called in creation order, whenever a navigation is trig Every guard function receives two arguments: -- **`to`**: the target route location [in a normalized format](../../api/interfaces/RouteLocationNormalized.md) being navigated to. -- **`from`**: the current route location [in a normalized format](../../api/interfaces/RouteLocationNormalized.md) being navigated away from. +- **`to`**: the target route location [in a normalized format](../../api/#RouteLocationNormalized) being navigated to. +- **`from`**: the current route location [in a normalized format](../../api/#RouteLocationNormalized) being navigated away from. And can optionally return any of the following values: diff --git a/packages/docs/guide/essentials/active-links.md b/packages/docs/guide/essentials/active-links.md index d2a5398b..3c5f23ba 100644 --- a/packages/docs/guide/essentials/active-links.md +++ b/packages/docs/guide/essentials/active-links.md @@ -6,14 +6,14 @@ The RouterLink component adds two CSS classes to active links, `router-link-acti ## When are links active? -A RouterLink is considered to be ***active*** if: +A RouterLink is considered to be **_active_** if: 1. It matches the same route record (i.e. configured route) as the current location. 2. It has the same values for the `params` as the current location. If you're using [nested routes](./nested-routes), any links to ancestor routes will also be considered active if the relevant `params` match. -Other route properties, such as the [`query`](../../api/interfaces/RouteLocationNormalized#query), are not taken into account. +Other route properties, such as the [`query`](../../api/interfaces/RouteLocationBase.html#query), are not taken into account. The path doesn't necessarily need to be a perfect match. For example, using an [`alias`](./redirect-and-alias#Alias) would still be considered a match, so long as it resolves to the same route record and `params`. @@ -21,7 +21,7 @@ If a route has a [`redirect`](./redirect-and-alias#Redirect), it won't be follow ## Exact active links -An ***exact*** match does not include ancestor routes. +An **_exact_** match does not include ancestor routes. Let's imagine we have the following routes: @@ -34,9 +34,9 @@ const routes = [ { path: 'role/:roleId', component: Role, - } - ] - } + }, + ], + }, ] ``` @@ -51,7 +51,7 @@ Then consider these two links: ``` -If the current location path is `/user/erina/role/admin` then these would both be considered _active_, so the class `router-link-active` would be applied to both links. But only the second link would be considered _exact_, so only that second link would have the class `router-link-exact-active`. +If the current location path is `/user/erina/role/admin` then these would both be considered _active_, so the class `router-link-active` would be applied to both links. But only the second link would be considered _exact_, so only that second link would have the class `router-link-exact-active`. ## Configuring the classes diff --git a/packages/docs/guide/essentials/dynamic-matching.md b/packages/docs/guide/essentials/dynamic-matching.md index 4e09cd21..9c9fd0b9 100644 --- a/packages/docs/guide/essentials/dynamic-matching.md +++ b/packages/docs/guide/essentials/dynamic-matching.md @@ -32,12 +32,12 @@ A _param_ is denoted by a colon `:`. When a route is matched, the value of its _ You can have multiple _params_ in the same route, and they will map to corresponding fields on `route.params`. Examples: -| pattern | matched path | route.params | -| ------------------------------ | ------------------------ | -------------------------------------- | -| /users/:username | /users/eduardo | `{ username: 'eduardo' }` | +| pattern | matched path | route.params | +| ------------------------------ | ------------------------ | ---------------------------------------- | +| /users/:username | /users/eduardo | `{ username: 'eduardo' }` | | /users/:username/posts/:postId | /users/eduardo/posts/123 | `{ username: 'eduardo', postId: '123' }` | -In addition to `route.params`, the `route` object also exposes other useful information such as `route.query` (if there is a query in the URL), `route.hash`, etc. You can check out the full details in the [API Reference](../../api/interfaces/RouteLocationNormalized.md). +In addition to `route.params`, the `route` object also exposes other useful information such as `route.query` (if there is a query in the URL), `route.hash`, etc. You can check out the full details in the [API Reference](../../api/#RouteLocationNormalized). A working demo of this example can be found [here](https://codesandbox.io/s/route-params-vue-router-examples-mlb14?from-embed&initialpath=%2Fusers%2Feduardo%2Fposts%2F1). @@ -69,9 +69,12 @@ import { useRoute } from 'vue-router' const route = useRoute() -watch(() => route.params.id, (newId, oldId) => { - // react to route changes... -}) +watch( + () => route.params.id, + (newId, oldId) => { + // react to route changes... + } +) ``` diff --git a/packages/docs/guide/migration/index.md b/packages/docs/guide/migration/index.md index 4e276064..1f841c89 100644 --- a/packages/docs/guide/migration/index.md +++ b/packages/docs/guide/migration/index.md @@ -434,7 +434,7 @@ Note this will work if `path` was `/parent/` as the relative location `home` to Decoded values in `params`, `query`, and `hash` are now consistent no matter where the navigation is initiated (older browsers will still produce unencoded `path` and `fullPath`). The initial navigation should yield the same results as in-app navigations. -Given any [normalized route location](/api/interfaces/RouteLocationNormalized.md): +Given any [normalized route location](/api/#RouteLocationNormalized): - Values in `path`, `fullPath` are not decoded anymore. They will appear as provided by the browser (most browsers provide them encoded). e.g. directly writing on the address bar `https://example.com/hello world` will yield the encoded version: `https://example.com/hello%20world` and both `path` and `fullPath` will be `/hello%20world`. - `hash` is now decoded, that way it can be copied over: `router.push({ hash: $route.hash })` and be used directly in [scrollBehavior](/api/interfaces/RouterOptions.md#scrollBehavior)'s `el` option. diff --git a/packages/docs/typedoc-markdown.mjs b/packages/docs/typedoc-markdown.mjs index 89876024..f81533a9 100644 --- a/packages/docs/typedoc-markdown.mjs +++ b/packages/docs/typedoc-markdown.mjs @@ -8,7 +8,7 @@ const __dirname = path.dirname(new URL(import.meta.url).pathname) const DEFAULT_OPTIONS = { // disableOutputCheck: true, cleanOutputDir: true, - excludeInternal: true, + excludeInternal: false, readme: 'none', out: path.resolve(__dirname, './api'), entryDocument: 'index.md', diff --git a/packages/docs/zh/guide/migration/index.md b/packages/docs/zh/guide/migration/index.md index 96d446e0..895c6b39 100644 --- a/packages/docs/zh/guide/migration/index.md +++ b/packages/docs/zh/guide/migration/index.md @@ -79,7 +79,7 @@ createRouter({ }) ``` -**原因**: Vue支持的所有浏览器都支持 [HTML5 History API](https://developer.mozilla.org/zh-CN/docs/Web/API/History_API)，因此我们不再需要使用 `location.hash`，而可以直接使用 `history.pushState()`。 +**原因**: Vue 支持的所有浏览器都支持 [HTML5 History API](https://developer.mozilla.org/zh-CN/docs/Web/API/History_API)，因此我们不再需要使用 `location.hash`，而可以直接使用 `history.pushState()`。 ### 删除了 `*`（星标或通配符）路由 @@ -436,7 +436,7 @@ const routes = [ -给定任何[规范化的路由地址](/zh/api/interfaces/RouteLocationNormalized.md): +给定任何[规范化的路由地址](/zh/api/#RouteLocationNormalized): - `path`, `fullPath`中的值不再被解码了。例如，直接在地址栏上写 " world"，将得到编码后的版本："https://example.com/hello%20world"，而 "path "和 "fullPath "都是"/hello%20world"。 - `hash` 现在被解码了，这样就可以复制过来。`router.push({ hash: $route.hash })` 可以直接用于 [scrollBehavior](/zh/api/interfaces/RouterOptions.md#Properties-scrollBehavior) 的 `el` 配置中。 diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts index ae19d6ef..058feeba 100644 --- a/packages/router/src/index.ts +++ b/packages/router/src/index.ts @@ -61,21 +61,59 @@ export type { RouteMeta, RouteComponent, // RawRouteComponent, + RouteParamsGeneric, + RouteParamsRawGeneric, + MatcherLocation, } from './types' +export type { _Awaitable } from './types/utils' // Experimental Type Safe API export type { + RouteMap, + RouteMapGeneric, + // route location RouteLocationRaw, RouteLocation, + RouteLocationTyped, + RouteLocationTypedList, + RouteLocationGeneric, + + // RouteLocationNormalized + RouteLocationNormalizedGeneric, RouteLocationNormalized, + RouteLocationNormalizedTyped, + RouteLocationNormalizedTypedList, + + // RouteLocationNormalizedLoaded + RouteLocationNormalizedLoadedGeneric, RouteLocationNormalizedLoaded, + RouteLocationNormalizedLoadedTyped, + RouteLocationNormalizedLoadedTypedList, + + // RouteLocationResolved RouteLocationResolved, + RouteLocationResolvedGeneric, + RouteLocationResolvedTyped, + RouteLocationResolvedTypedList, + + // relative RouteLocationAsRelative, + RouteLocationAsRelativeGeneric, + RouteLocationAsRelativeTyped, + RouteLocationAsRelativeTypedList, + // string + RouteLocationAsString, + // as path + RouteLocationAsPathGeneric, + RouteLocationAsPathTyped, + RouteLocationAsPathTypedList, // route records RouteRecordInfo, RouteRecordName, + RouteRecordNameGeneric, + _RouteRecordProps, RouteRecordRedirectOption, // params @@ -92,6 +130,7 @@ export type { NavigationHookAfter, NavigationGuardReturn, NavigationGuardNext, + NavigationGuardNextCallback, } from './typed-routes' export { createRouter } from './router' diff --git a/packages/router/src/typed-routes/index.ts b/packages/router/src/typed-routes/index.ts index b91914c1..3a64a463 100644 --- a/packages/router/src/typed-routes/index.ts +++ b/packages/router/src/typed-routes/index.ts @@ -1,36 +1,5 @@ -export type { - ParamValue, - ParamValueOneOrMore, - ParamValueZeroOrMore, - ParamValueZeroOrOne, - RouteParams, - RouteParamsRaw, -} from './params' - -export type { RouteRecordInfo } from './route-map' - -export type { - RouteRecordName, - RouteLocationRaw, - RouteLocation, - RouteLocationNormalized, - RouteLocationNormalizedGeneric, - RouteLocationNormalizedLoaded, - RouteLocationResolved, - RouteLocationAsRelative, -} from './route-location' - -export type { - RouteRecordRedirectOption, - RouteRecordNameGeneric, - _RouteRecordProps, -} from './route-records' - -export type { - NavigationGuard, - NavigationGuardReturn, - NavigationHookAfter, - NavigationGuardWithThis, - NavigationGuardNext, - NavigationGuardNextCallback, -} from './navigation-guards' +export type * from './params' +export type * from './route-map' +export type * from './route-location' +export type * from './route-records' +export type * from './navigation-guards' diff --git a/packages/router/src/typed-routes/route-location.ts b/packages/router/src/typed-routes/route-location.ts index 0f9619fc..6cf08cee 100644 --- a/packages/router/src/typed-routes/route-location.ts +++ b/packages/router/src/typed-routes/route-location.ts @@ -240,7 +240,7 @@ export type RouteLocation = /** * Similar to {@link RouteLocation} but its - * {@link RouteLocationNormalizedTyped.matched `matched` property} cannot contain redirect records + * {@link RouteLocationNormalizedTyped.matched | `matched` property} cannot contain redirect records */ export type RouteLocationNormalized< Name extends keyof RouteMap = keyof RouteMap @@ -251,7 +251,6 @@ export type RouteLocationNormalized< /** * Similar to {@link RouteLocationNormalized} but its `components` do not contain any function to lazy load components. * In other words, it's ready to be rendered by ``. - * @see {@link RouteLocationNormalized} */ export type RouteLocationNormalizedLoaded< Name extends keyof RouteMap = keyof RouteMap @@ -270,8 +269,7 @@ export type RouteLocationAsRelative< : RouteLocationAsRelativeTypedList[Name] /** - * Route location resolved with `router.resolve()`. - * @see {@link Router['resolve'] | `router.resolve()`} + * Route location resolved with {@link Router | `router.resolve()`}. */ export type RouteLocationResolved< Name extends keyof RouteMap = keyof RouteMap -- 2.47.2