From 5eab1efbd34a311cfc19a27adf325c7a5f256272 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Fri, 24 May 2024 16:18:58 +0800 Subject: [PATCH] docs: add route related docs (#26) Co-authored-by: meteorlxy --- docs/.vuepress/configs/sidebar/en.ts | 1 + docs/.vuepress/configs/sidebar/zh.ts | 1 + docs/advanced/cookbook/resolving-routes.md | 50 +++++++++++++++++++ docs/guide/migration.md | 2 +- docs/reference/client-api.md | 29 +++++++++++ docs/zh/advanced/cookbook/resolving-routes.md | 50 +++++++++++++++++++ docs/zh/guide/migration.md | 2 +- docs/zh/reference/client-api.md | 29 +++++++++++ 8 files changed, 162 insertions(+), 2 deletions(-) create mode 100644 docs/advanced/cookbook/resolving-routes.md create mode 100644 docs/zh/advanced/cookbook/resolving-routes.md diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index 6140b78c..3d16bb3c 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -39,6 +39,7 @@ export const sidebarEn: SidebarConfig = { '/advanced/cookbook/making-a-theme-extendable.md', '/advanced/cookbook/passing-data-to-client-code.md', '/advanced/cookbook/markdown-and-vue-sfc.md', + '/advanced/cookbook/resolving-routes.md', ], }, ], diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 2328c433..82cc4b77 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -39,6 +39,7 @@ export const sidebarZh: SidebarConfig = { '/zh/advanced/cookbook/making-a-theme-extendable.md', '/zh/advanced/cookbook/passing-data-to-client-code.md', '/zh/advanced/cookbook/markdown-and-vue-sfc.md', + '/zh/advanced/cookbook/resolving-routes.md', ], }, ], diff --git a/docs/advanced/cookbook/resolving-routes.md b/docs/advanced/cookbook/resolving-routes.md new file mode 100644 index 00000000..4f3d55b1 --- /dev/null +++ b/docs/advanced/cookbook/resolving-routes.md @@ -0,0 +1,50 @@ +# Resolving Routes + +## Getting all routes + +You can make use of [useRoutes](../../reference/client-api.md#useroutes) to get all routes information. + +The return value of `useRoutes` is a Ref object containing all routes. The keys are route paths of each route, and the values are the corresponding route information. + +```ts +import { useRoutes } from 'vuepress/client' + +const routes = useRoutes() +// { +// '/': { meta: { title: 'Home' }, loader: HomePageLoader }, +// '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader }, +// ... +// } + +const routePaths = computed(() => Object.keys(routes.value)) +// => ['/‘, '/404.html', '/foo/', '/bar/', ...] +``` + +## Resolving route path + +You can make use of [resolveRoutePath](../../reference/client-api.md#resolveroutepath) to resolve the route path of the given link. + +`resolveRoutePath` receives a link and an optional base path, and returns the resolved route path: + +```ts +import { resolveRoutePath } from 'vuepress/client' + +const routePath = resolveRoutePath('/foo/') // => '/foo/' +const routePath = resolveRoutePath('baz.html', '/foo/bar.html') // => '/foo/baz.html' +``` + +## Resolving route information + +You can make use of [resolveRoute](../../reference/client-api.md#resolveroute) to resolve route information for a given link. + +`resolveRoute` receives a link and an optional base path, and returns the resolved route information: + +```ts +import { resolveRoute } from 'vuepress/client' + +const route = resolveRoute('/foo/') // => { notFound: false, path: '/foo/', meta: { title: 'Foo' }, loader: FooPageLoader } +const route = resolveRoute('baz.html', '/foo/bar.html') // => { notFound: false, path: '/foo/baz.html', meta: { title: 'Baz' }, loader: BazPageLoader } +const route = resolveRoute('/not-exist.html') // => { notFound: true, path: '/not-exist.html', meta: { title: 'Not Found' }, loader: NotFoundPageLoader } +``` + +There is a `notFound` field in the returned information, which is used to indicate whether a corresponding route exists for a given path. When the route does not exist, the `notFound` field would be `true`, the `path` field would be the normalized path, and the `meta` and `loader` fields would point to the default 404 page. diff --git a/docs/guide/migration.md b/docs/guide/migration.md index 431ce31d..69150d28 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -415,7 +415,7 @@ Some major breaking changes: - `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/plugins/theme-data.html) plugin and its `useThemeData` composition API. - Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](https://ecosystem.vuejs.press/plugins/palette.html) may help. - Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/plugins/prismjs.html) or [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/plugins/shiki.html), or implement syntax highlighting in your own way. -- For scalability concerns, `this.$site.pages` is not available any more. +- For scalability concerns, `this.$site.pages` is not available any more. See [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) for how to retrieve pages data in v2. For more detailed guide about how to write a theme in v2, see [Advanced > Writing a Theme](../advanced/theme.md). diff --git a/docs/reference/client-api.md b/docs/reference/client-api.md index fe8e874f..ebfc4d7a 100644 --- a/docs/reference/client-api.md +++ b/docs/reference/client-api.md @@ -73,6 +73,17 @@ const { The value is the `lang` property of the page data. +## useRoutes + +- Details: + + Returns the routes ref object. + + The value is the `routes` property of the site data. + +- Also see: + - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) + ### useRouteLocale - Details: @@ -106,6 +117,24 @@ const { - Also see: - [Advanced > Cookbook > Usage of Client Config](../advanced/cookbook/usage-of-client-config.md) +### resolveRoute + +- Details: + + Parses the route of the given link. + +- Also see: + - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) + +## resolveRoutePath + +- Details: + + Parses the route path of the given link. + +- Also see: + - [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) + ### withBase - Details: diff --git a/docs/zh/advanced/cookbook/resolving-routes.md b/docs/zh/advanced/cookbook/resolving-routes.md new file mode 100644 index 00000000..7ec8e7ac --- /dev/null +++ b/docs/zh/advanced/cookbook/resolving-routes.md @@ -0,0 +1,50 @@ +# 解析路由 + +## 获取全部路由 + +在开发主题和插件时，你可能希望获取所有页面的信息。通过 [useRoutes](../../reference/client-api.md#useroutes) 就可以获取所有页面的路由记录。 + +`useRoutes` 的返回值是一个包含了所有路由信息的 Ref 对象。其属性是每条路由的路由路径，对应的值是路径的路由信息。 + +```ts +import { useRoutes } from 'vuepress/client' + +const routes = useRoutes() +// { +// '/': { meta: { title: 'Home' }, loader: HomePageLoader }, +// '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader }, +// ... +// } + +const routePaths = computed(() => Object.keys(routes.value)) +// => [’/‘, '/404.html', '/foo/', '/bar/', ...] +``` + +## 解析路由地址 + +你可以使用 [resolveRoutePath](../../reference/client-api.md#resolveroutepath) 来解析给定的链接对应的路由路径。 + +`resolveRoutePath` 接收一个链接地址和一个可选的基础路径，返回一个解析后的路由地址: + +```ts +import { resolveRoutePath } from 'vuepress/client' + +const routePath = resolveRoutePath('/foo/') // => '/foo/' +const routePath = resolveRoutePath('baz.html', '/foo/bar.html') // => '/foo/baz.html' +``` + +## 解析路由信息 + +你可以使用 [resolveRoute](../../reference/client-api.md#resolveroute) 来解析给定的链接对应的路由信息。 + +`resolveRoute` 接收一个链接地址和一个可选的基础路径，返回一个解析后的路由信息: + +```ts +import { resolveRoute } from 'vuepress/client' + +const route = resolveRoute('/foo/') // => { notFound: false, path: '/foo/', meta: { title: 'Foo' }, loader: FooPageLoader } +const route = resolveRoute('baz.html', '/foo/bar.html') // => { notFound: false, path: '/foo/baz.html', meta: { title: 'Baz' }, loader: BazPageLoader } +const route = resolveRoute('/not-exist.html') // => { notFound: true, path: '/not-exist.html', meta: { title: 'Not Found' }, loader: NotFoundPageLoader } +``` + +路由信息中存在一个 `notFound` 字段，用于标识给定的路径是否存在对应的路由。当路由不存在时，返回值中的 `notFound` 字段为 `true`，其 `path` 字段为规范化后的路径，而 `meta` 和 `loader` 字段则会指向默认的 404 页面。 diff --git a/docs/zh/guide/migration.md b/docs/zh/guide/migration.md index 3a01abc4..fe7563b1 100644 --- a/docs/zh/guide/migration.md +++ b/docs/zh/guide/migration.md @@ -417,7 +417,7 @@ v1 的主题和插件和 v2 并不兼容。 - `themeConfig` 已经从用户配置和站点数据中移除。如果你想要像 v1 一样通过 `this.$site.themeConfig` 来访问 `themeConfig` ，我们现在建议使用 [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/zh/plugins/theme-data.html) 插件和它提供的 Composition API `useThemeData` 。 - Stylus 不再是默认的 CSS 预处理器，并且 Stylus 调色板系统不再被默认支持。如果你仍然想要使用和 v1 类似的调色板系统，可以使用 [@vuepress/plugin-palette](https://ecosystem.vuejs.press/zh/plugins/palette.html) 。 - 由 Prism.js 提供的 Markdown 代码块的语法高亮不再被默认支持。你可以选择使用 [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/zh/plugins/prismjs.html) 或 [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/plugin/shiki.html) ，或者用你自己的方式实现语法高亮。 -- 考虑到可扩展性， `this.$site.pages` 不再可用。 +- 考虑到可扩展性， `this.$site.pages` 不再可用。查看 [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) 了解如何在 v2 中获取页面的数据。 你可以参考 [深入 > 开发主题](../advanced/theme.md) 来了解如何开发一个 v2 主题。 diff --git a/docs/zh/reference/client-api.md b/docs/zh/reference/client-api.md index 5b6248ca..c8b6deb5 100644 --- a/docs/zh/reference/client-api.md +++ b/docs/zh/reference/client-api.md @@ -73,6 +73,17 @@ const { 它的值是页面数据的 `lang` 属性。 +### useRoutes + +- 详情： + + 返回所有路由的 Ref 对象。 + + 它的值是站点数据的路由信息。 + +- 参考： + - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) + ### useRouteLocale - 详情： @@ -106,6 +117,24 @@ const { - 参考： - [深入 > Cookbook > 客户端配置的使用方法](../advanced/cookbook/usage-of-client-config.md) +### resolveRoute + +- 详情： + + 解析给定链接对应的路由 + +- 参考： + - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) + +## resolveRoutePath + +- 详情： + + 解析给定链接对应的路由路径 + +- 参考： + - [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) + ### withBase - 详情：