From 945c7e570f98afc43d07978b3f7c079ca01b0941 Mon Sep 17 00:00:00 2001 From: Jinjiang Date: Tue, 21 Apr 2020 15:21:40 +0800 Subject: [PATCH] docs(zh): update --- docs/zh/README.md | 2 ++ docs/zh/api/README.md | 9 ++++++++ docs/zh/guide/README.md | 2 ++ docs/zh/guide/advanced/lazy-loading.md | 2 ++ docs/zh/guide/advanced/navigation-guards.md | 23 +++++++++++++++++-- docs/zh/guide/advanced/scroll-behavior.md | 2 ++ docs/zh/guide/advanced/transitions.md | 2 ++ docs/zh/guide/essentials/dynamic-matching.md | 18 ++++++++------- docs/zh/guide/essentials/history-mode.md | 2 ++ docs/zh/guide/essentials/named-routes.md | 2 ++ docs/zh/guide/essentials/nested-routes.md | 2 ++ docs/zh/guide/essentials/passing-props.md | 2 ++ .../zh/guide/essentials/redirect-and-alias.md | 2 +- 13 files changed, 59 insertions(+), 11 deletions(-) diff --git a/docs/zh/README.md b/docs/zh/README.md index d790fdb42..9e813c1a5 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -4,6 +4,8 @@ 对于 TypeScript 用户来说，`vue-router@3.0+` 依赖 `vue@2.5+`，反之亦然。 ::: +
观看 Vue School 的关于 Vue Router 的免费视频课程 (英文)
+ Vue Router 是 [Vue.js](http://cn.vuejs.org) 官方的路由管理器。它和 Vue.js 的核心深度集成，让构建单页面应用变得易如反掌。包含的功能有： - 嵌套的路由/视图表 diff --git a/docs/zh/api/README.md b/docs/zh/api/README.md index 3cd404cc0..94c64cc40 100644 --- a/docs/zh/api/README.md +++ b/docs/zh/api/README.md @@ -166,6 +166,13 @@ sidebar: auto 配置当链接被精确匹配的时候应该激活的 class。注意默认值也是可以通过路由构造函数选项 `linkExactActiveClass` 进行全局配置的。 +### aria-current-value + +- 类型: `'page' | 'step' | 'location' | 'date' | 'time'` +- 默认值: `"page"` + + 当链接根据精确匹配规则激活时配置的 `aria-current` 的值。这个值应该是 ARIA 规范中[允许的 aria-current 的值](https://www.w3.org/TR/wai-aria-1.2/#aria-current)。在绝大多数场景下，默认值 `page` 应该是最合适的。 + ## `` `` 组件是一个 functional 组件，渲染路径匹配到的视图组件。`` 渲染的组件还可以内嵌自己的 ``，根据嵌套路径，渲染嵌套组件。 @@ -288,6 +295,8 @@ sidebar: auto - 类型: `boolean` +- 默认值: `true` + 当浏览器不支持 `history.pushState` 控制路由是否应该回退到 `hash` 模式。默认值为 `true`。 在 IE9 中，设置为 `false` 会使得每个 `router-link` 导航都触发整页刷新。它可用于工作在 IE9 下的服务端渲染应用，因为一个 hash 模式的 URL 并不支持服务端渲染。 diff --git a/docs/zh/guide/README.md b/docs/zh/guide/README.md index b5d2ac53f..05134397e 100644 --- a/docs/zh/guide/README.md +++ b/docs/zh/guide/README.md @@ -6,6 +6,8 @@ 同时，所有的例子都将使用完整版的 Vue 以解析模板。更多细节请[移步这里](https://cn.vuejs.org/v2/guide/installation.html#运行时-编译器-vs-只包含运行时)。 ::: +
观看 Vue School 的关于 Vue Router 的免费视频课程 (英文)
+ 用 Vue.js + Vue Router 创建单页应用，是非常简单的。使用 Vue.js ，我们已经可以通过组合组件来组成应用程序，当你要把 Vue Router 添加进来，我们需要做的是，将组件 (components) 映射到路由 (routes)，然后告诉 Vue Router 在哪里渲染它们。下面是个基本例子： ## HTML diff --git a/docs/zh/guide/advanced/lazy-loading.md b/docs/zh/guide/advanced/lazy-loading.md index f87191ad7..51391c85b 100644 --- a/docs/zh/guide/advanced/lazy-loading.md +++ b/docs/zh/guide/advanced/lazy-loading.md @@ -1,5 +1,7 @@ # 路由懒加载 +
观看 Vue School 的如何路由懒加载的免费视频课程 (英文)
+ 当打包构建应用时，JavaScript 包会变得非常大，影响页面加载。如果我们能把不同路由对应的组件分割成不同的代码块，然后当路由被访问的时候才加载对应组件，这样就更加高效了。 结合 Vue 的[异步组件](https://cn.vuejs.org/v2/guide/components-dynamic-async.html#异步组件)和 Webpack 的[代码分割功能](https://doc.webpack-china.org/guides/code-splitting-async/#require-ensure-/)，轻松实现路由组件的懒加载。 diff --git a/docs/zh/guide/advanced/navigation-guards.md b/docs/zh/guide/advanced/navigation-guards.md index 28ff3908b..54a53f8a0 100644 --- a/docs/zh/guide/advanced/navigation-guards.md +++ b/docs/zh/guide/advanced/navigation-guards.md @@ -8,6 +8,8 @@ 记住**参数或查询的改变并不会触发进入/离开的导航守卫**。你可以通过[观察 `$route` 对象](../essentials/dynamic-matching.md#响应路由参数的变化)来应对这些变化，或使用 `beforeRouteUpdate` 的组件内守卫。 +
观看 Vue School 的导航守卫如何工作的免费视频课程 (英文)
+ ## 全局前置守卫 你可以使用 `router.beforeEach` 注册一个全局前置守卫： @@ -38,7 +40,24 @@ router.beforeEach((to, from, next) => { - **`next(error)`**: (2.4.0+) 如果传入 `next` 的参数是一个 `Error` 实例，则导航会被终止且该错误会被传递给 [`router.onError()`](../../api/#router-onerror) 注册过的回调。 -**确保要调用 `next` 方法，否则钩子就不会被 resolved。** +**确保 `next` 函数在任何给定的导航守卫中都被严格调用一次。它可以出现多于一次，但是只能在所有的逻辑路径都不重叠的情况下，否则钩子永远都不会被解析或报错。**这里有一个在用户未能验证身份时重定向到 `/login` 的示例： + +```js +// BAD +router.beforeEach((to, from, next) => { + if (to.name !== 'Login' && !isAuthenticated) next({ name: 'Login' }) + // 如果用户未能验证身份，则 `next` 会被调用两次 + next() +}) +``` + +```js +// GOOD +router.beforeEach((to, from, next) => { + if (to.name !== 'Login' && !isAuthenticated) next({ name: 'Login' }) + else next() +}) +``` ## 全局解析守卫 @@ -143,7 +162,7 @@ beforeRouteLeave (to, from, next) { ## 完整的导航解析流程 1. 导航被触发。 -2. 在失活的组件里调用离开守卫。 +2. 在失活的组件里调用 `beforeRouteLeave` 守卫。 3. 调用全局的 `beforeEach` 守卫。 4. 在重用的组件里调用 `beforeRouteUpdate` 守卫 (2.2+)。 5. 在路由配置里调用 `beforeEnter`。 diff --git a/docs/zh/guide/advanced/scroll-behavior.md b/docs/zh/guide/advanced/scroll-behavior.md index c30670362..c354ff419 100644 --- a/docs/zh/guide/advanced/scroll-behavior.md +++ b/docs/zh/guide/advanced/scroll-behavior.md @@ -1,5 +1,7 @@ # 滚动行为 +
观看 Vue School 的如何控制滚动行为的免费视频课程 (英文)
+ 使用前端路由，当切换到新路由时，想要页面滚到顶部，或者是保持原先的滚动位置，就像重新加载页面那样。 `vue-router` 能做到，而且更好，它让你可以自定义路由切换时页面如何滚动。 **注意: 这个功能只在支持 `history.pushState` 的浏览器中可用。** diff --git a/docs/zh/guide/advanced/transitions.md b/docs/zh/guide/advanced/transitions.md index f71869df5..d1197b007 100644 --- a/docs/zh/guide/advanced/transitions.md +++ b/docs/zh/guide/advanced/transitions.md @@ -1,5 +1,7 @@ # 过渡动效 +
观看 Vue School 的如何创建路由过渡动效的免费视频课程 (英文)
+ `` 是基本的动态组件，所以我们可以用 `` 组件给它添加一些过渡效果： ``` html diff --git a/docs/zh/guide/essentials/dynamic-matching.md b/docs/zh/guide/essentials/dynamic-matching.md index a5297a64f..9eec0b5bb 100644 --- a/docs/zh/guide/essentials/dynamic-matching.md +++ b/docs/zh/guide/essentials/dynamic-matching.md @@ -1,8 +1,10 @@ # 动态路由匹配 +
观看 Vue School 的如何匹配动态路由的免费视频课程 (英文)
+ 我们经常需要把某种模式匹配到的所有路由，全都映射到同个组件。例如，我们有一个 `User` 组件，对于所有 ID 各不相同的用户，都要使用这个组件来渲染。那么，我们可以在 `vue-router` 的路由路径中使用“动态路径参数”(dynamic segment) 来达到这个效果： -``` js +```js const User = { template: '
User
' } @@ -20,7 +22,7 @@ const router = new VueRouter({ 一个“路径参数”使用冒号 `:` 标记。当匹配到一个路由时，参数值会被设置到 `this.$route.params`，可以在每个组件内使用。于是，我们可以更新 `User` 的模板，输出当前用户的 ID： -``` js +```js const User = { template: '
User {{ $route.params.id }}
' } @@ -31,8 +33,8 @@ const User = { 你可以在一个路由中设置多段“路径参数”，对应的值都会设置到 `$route.params` 中。例如： | 模式 | 匹配路径 | $route.params | -|---------|------|--------| -| /user/:username | /user/evan | `{ username: 'evan' }` | +| ----------------------------- | ------------------- | -------------------------------------- | +| /user/:username | /user/evan | `{ username: 'evan' }` | | /user/:username/post/:post_id | /user/evan/post/123 | `{ username: 'evan', post_id: '123' }` | 除了 `$route.params` 外，`$route` 对象还提供了其它有用的信息，例如，`$route.query` (如果 URL 中有查询参数)、`$route.hash` 等等。你可以查看 [API 文档](../../api/#路由对象) 的详细说明。 @@ -43,11 +45,11 @@ const User = { 复用组件时，想对路由参数的变化作出响应的话，你可以简单地 watch (监测变化) `$route` 对象： -``` js +```js const User = { template: '...', watch: { - '$route' (to, from) { + $route(to, from) { // 对路由变化作出响应... } } @@ -56,7 +58,7 @@ const User = { 或者使用 2.2 中引入的 `beforeRouteUpdate` [导航守卫](../advanced/navigation-guards.html)： -``` js +```js const User = { template: '...', beforeRouteUpdate (to, from, next) { @@ -96,7 +98,7 @@ this.$route.params.pathMatch // '/non-existing' ## 高级匹配模式 -`vue-router` 使用 [path-to-regexp](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0) 作为路径匹配引擎，所以支持很多高级的匹配模式，例如：可选的动态路径参数、匹配零个或多个、一个或多个，甚至是自定义正则匹配。查看它的 [文档](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0#parameters) 学习高阶的路径匹配，还有 [这个例子 ](https://github.com/vuejs/vue-router/blob/dev/examples/route-matching/app.js) 展示 `vue-router` 怎么使用这类匹配。 +`vue-router` 使用 [path-to-regexp](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0) 作为路径匹配引擎，所以支持很多高级的匹配模式，例如：可选的动态路径参数、匹配零个或多个、一个或多个，甚至是自定义正则匹配。查看它的[文档](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0#parameters)学习高阶的路径匹配，还有[这个例子 ](https://github.com/vuejs/vue-router/blob/dev/examples/route-matching/app.js)展示 `vue-router` 怎么使用这类匹配。 ## 匹配优先级 diff --git a/docs/zh/guide/essentials/history-mode.md b/docs/zh/guide/essentials/history-mode.md index ee27f0c56..9ef4a31ce 100644 --- a/docs/zh/guide/essentials/history-mode.md +++ b/docs/zh/guide/essentials/history-mode.md @@ -19,6 +19,8 @@ const router = new VueRouter({ ## 后端配置例子 +**注意**：下列示例假设你在根目录服务这个应用。如果想部署到一个子目录，你需要使用 [Vue CLI 的 `publicPath` 选项](https://cli.vuejs.org/zh/config/#publicpath) 和相关的 [router `base` property](https://router.vuejs.org/zh/api/#base)。你还需要把下列示例中的根目录调整成为子目录 (例如用 `RewriteBase /name-of-your-subfolder/` 替换掉 `RewriteBase /`)。 + #### Apache ```apache diff --git a/docs/zh/guide/essentials/named-routes.md b/docs/zh/guide/essentials/named-routes.md index 175eeefab..da4481cf6 100644 --- a/docs/zh/guide/essentials/named-routes.md +++ b/docs/zh/guide/essentials/named-routes.md @@ -1,5 +1,7 @@ # 命名路由 +
观看 Vue School 的如何使用命名路由及其参数的免费视频课程 (英文)
+ 有时候，通过一个名称来标识一个路由显得更方便一些，特别是在链接一个路由，或者是执行一些跳转的时候。你可以在创建 Router 实例的时候，在 `routes` 配置中给某个路由设置名称。 ``` js diff --git a/docs/zh/guide/essentials/nested-routes.md b/docs/zh/guide/essentials/nested-routes.md index e9e0f2b84..8d0d15a40 100644 --- a/docs/zh/guide/essentials/nested-routes.md +++ b/docs/zh/guide/essentials/nested-routes.md @@ -1,5 +1,7 @@ # 嵌套路由 +
观看 Vue School 的如何使用嵌套路由的免费视频课程 (英文)
+ 实际生活中的应用界面，通常由多层嵌套的组件组合而成。同样地，URL 中各段动态路径也按某种结构对应嵌套的各层组件，例如： ``` diff --git a/docs/zh/guide/essentials/passing-props.md b/docs/zh/guide/essentials/passing-props.md index 120a64dde..2d30d20f5 100644 --- a/docs/zh/guide/essentials/passing-props.md +++ b/docs/zh/guide/essentials/passing-props.md @@ -1,5 +1,7 @@ # 路由组件传参 +
观看 Vue School 的如何向路由组件传递 prop 的免费视频课程 (英文)
+ 在组件中使用 `$route` 会使之与其对应路由形成高度耦合，从而使组件只能在某些特定的 URL 上使用，限制了其灵活性。 使用 `props` 将组件和路由解耦： diff --git a/docs/zh/guide/essentials/redirect-and-alias.md b/docs/zh/guide/essentials/redirect-and-alias.md index 56a567946..a31810321 100644 --- a/docs/zh/guide/essentials/redirect-and-alias.md +++ b/docs/zh/guide/essentials/redirect-and-alias.md @@ -35,7 +35,7 @@ const router = new VueRouter({ }) ``` -注意[导航守卫](../advanced/navigation-guards.md)并没有应用在跳转路由上，而仅仅应用在其目标上。在下面这个例子中，为 `/a` 路由添加一个 `beforeEach` 或 `beforeLeave` 守卫并不会有任何效果。 +注意[导航守卫](../advanced/navigation-guards.md)并没有应用在跳转路由上，而仅仅应用在其目标上。在下面这个例子中，为 `/a` 路由添加一个 `beforeEach` 守卫并不会有任何效果。 其它高级用法，请参考[例子](https://github.com/vuejs/vue-router/blob/dev/examples/redirect/app.js)。