Skip to content

Commit

Permalink
docs(zh): updated (#2903)
Browse files Browse the repository at this point in the history 
* docs(zh): updated

* Apply suggestions from code review

Co-Authored-By: GU Yiling <justice360@gmail.com>

* Update README.md

* Update README.md
  • Loading branch information
@Jinjiang @posva
Jinjiang authored and posva committed Sep 2, 2019
1 parent f40139c commit 039bd8f
Show file tree
Hide file tree
Showing 3 changed files with 102 additions and 62 deletions.
158 changes: 99 additions & 59 deletions docs/zh/api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,52 @@ sidebar: auto
`<router-link>` 比起写死的 `<a href="...">` 会好一些，理由如下：

- 无论是 HTML5 history 模式还是 hash 模式，它的表现行为一致，所以，当你要切换路由模式，或者在 IE9 降级使用 hash 模式，无须作任何变动。

- 在 HTML5 history 模式下，`router-link` 会守卫点击事件，让浏览器不再重新加载页面。

- 当你在 HTML5 history 模式下使用 `base` 选项之后，所有的 `to` 属性都不需要写 (基路径) 了。

### 将激活 class 应用在外层元素
### `v-slot` API (3.1.0 新增)

`router-link` 通过一个[作用域插槽](https://cn.vuejs.org/v2/guide/components-slots.html#作用域插槽)暴露底层的定制能力。这是一个更高阶的 API，主要面向库作者，但也可以为开发者提供便利，多数情况用在一个类似 _NavLink_ 这样的组件里。

有时候我们要让激活 class 应用在外层元素，而不是 `<a>` 标签本身，那么可以用 `<router-link>` 渲染外层元素，包裹着内层的原生 `<a>` 标签：
**在使用 `v-slot` API 时，需要向 `router-link` 传入一个单独的子元素**。否则 `router-link` 将会把子元素包裹在一个 `span` 元素内。

```html
<router-link
to="/about"
v-slot="{ href, route, navigate, isActive, isExactActive }"
>
<NavLink :active="isActive" :href="href" @click="navigate"
>{{ route.fullPath }}</NavLink
>
</router-link>
```

``` html
<router-link tag="li" to="/foo">
<a>/foo</a>
- `href`：解析后的 URL。将会作为一个 `a` 元素的 `href` attribute。
- `route`：解析后的规范化的地址。
- `navigate`：触发导航的函数。**会在必要时自动阻止事件**，和 `router-link` 同理。
- `isActive`：如果需要应用[激活的 class](#active-class) 则为 `true`。允许应用一个任意的 class。
- `isExactActive`：如果需要应用[精确激活的 class](#exact-active-class) 则为 `true`。允许应用一个任意的 class。

### 示例：将激活的 class 应用在外层元素

有的时候我们可能想把激活的 class 应用到一个外部元素而不是 `<a>` 标签本身，这时你可以在一个 `router-link` 中包裹该元素并使用 `v-slot` property 来创建链接：

```html
<router-link
to="/foo"
v-slot="{ href, route, navigate, isActive, isExactActive }"
>
<li
:class="[isActive && 'router-link-active', isExactActive && 'router-link-exact-active']"
>
<a :href="href" @click="navigate">{{ route.fullPath }}</a>
</li>
</router-link>
```

在这种情况下，`<a>` 将作为真实的链接 (它会获得正确的 `href` 的)，而 "激活时的 CSS 类名" 则设置到外层的 `<li>`。
:::tip 提示
如果你在 `<a>` 元素上添加一个 `target="_blank"`，则 `@click="navigate"` 处理器会被忽略。
:::

## `<router-link>` Props

Expand All @@ -40,7 +70,7 @@ sidebar: auto

表示目标路由的链接。当被点击后，内部会立刻把 `to` 的值传到 `router.push()`，所以这个值可以是一个字符串或者是描述目标位置的对象。

``` html
```html
<!-- 字符串 -->
<router-link to="home">Home</router-link>
<!-- 渲染结果 -->
Expand All @@ -59,7 +89,9 @@ sidebar: auto
<router-link :to="{ name: 'user', params: { userId: 123 }}">User</router-link>

<!-- 带查询参数，下面的结果为 /register?plan=private -->
<router-link :to="{ path: 'register', query: { plan: 'private' }}">Register</router-link>
<router-link :to="{ path: 'register', query: { plan: 'private' }}"
>Register</router-link
>
```

### replace
Expand All @@ -69,7 +101,7 @@ sidebar: auto

设置 `replace` 属性的话，当点击时，会调用 `router.replace()` 而不是 `router.push()`，于是导航后不会留下 history 记录。

``` html
```html
<router-link :to="{ path: '/abc'}" replace></router-link>
```

Expand All @@ -80,7 +112,7 @@ sidebar: auto

设置 `append` 属性后，则在当前 (相对) 路径前添加基路径。例如，我们从 `/a` 导航到一个相对路径 `b`，如果没有配置 `append`，则路径为 `/b`，如果配了，则为 `/a/b`

``` html
```html
<router-link :to="{ path: 'relative/path'}" append></router-link>
```

Expand All @@ -92,7 +124,7 @@ sidebar: auto
有时候想要 `<router-link>` 渲染成某种标签，例如 `<li>`。
于是我们使用 `tag` prop 类指定何种标签，同样它还是会监听点击，触发导航。

``` html
```html
<router-link to="/foo" tag="li">foo</router-link>
<!-- 渲染结果 -->
<li>foo</li>
Expand All @@ -103,21 +135,21 @@ sidebar: auto
- 类型: `string`
- 默认值: `"router-link-active"`

设置 链接激活时使用的 CSS 类名。默认值可以通过路由的构造选项 `linkActiveClass` 来全局配置。
设置链接激活时使用的 CSS 类名。默认值可以通过路由的构造选项 `linkActiveClass` 来全局配置。

### exact

- 类型: `boolean`
- 默认值: `false`

"是否激活" 默认类名的依据是 **inclusive match** (全包含匹配)。
“是否激活”默认类名的依据是**包含匹配**。
举个例子，如果当前的路径是 `/a` 开头的，那么 `<router-link to="/a">` 也会被设置 CSS 类名。

按照这个规则，每个路由都会激活`<router-link to="/">`！想要链接使用 "exact 匹配模式"，则使用 `exact` 属性：
按照这个规则，每个路由都会激活 `<router-link to="/">`！想要链接使用“精确匹配模式”，则使用 `exact` 属性：

``` html
```html
<!-- 这个链接只会在地址为 / 的时候被激活 -->
<router-link to="/" exact>
<router-link to="/" exact></router-link>
```

查看更多关于激活链接类名的例子[可运行](https://jsfiddle.net/8xrk1n9f/)
Expand Down Expand Up @@ -145,7 +177,7 @@ sidebar: auto

因为它也是个组件，所以可以配合 `<transition>` 和 `<keep-alive>` 使用。如果两个结合一起用，要确保在内层使用 `<keep-alive>`：

``` html
```html
<transition>
<keep-alive>
<router-view></router-view>
Expand All @@ -170,22 +202,22 @@ sidebar: auto

`RouteConfig` 的类型定义：

``` js
declare type RouteConfig = {
path: string;
component?: Component;
name?: string; // 命名路由
components?: { [name: string]: Component }; // 命名视图组件
redirect?: string | Location | Function;
props?: boolean | Object | Function;
alias?: string | Array<string>;
children?: Array<RouteConfig>; // 嵌套路由
beforeEnter?: (to: Route, from: Route, next: Function) => void;
meta?: any;
```ts
interface RouteConfig = {
path: string,
component?: Component,
name?: string, // 命名路由
components?: { [name: string]: Component }, // 命名视图组件
redirect?: string | Location | Function,
props?: boolean | Object | Function,
alias?: string | Array<string>,
children?: Array<RouteConfig>, // 嵌套路由
beforeEnter?: (to: Route, from: Route, next: Function) => void,
meta?: any,

// 2.6.0+
caseSensitive?: boolean; // 匹配规则是否大小写敏感？(默认值：false)
pathToRegexpOptions?: Object; // 编译正则的选项
caseSensitive?: boolean, // 匹配规则是否大小写敏感？(默认值：false)
pathToRegexpOptions?: Object // 编译正则的选项
}
```

Expand Down Expand Up @@ -217,15 +249,15 @@ sidebar: auto

- 默认值: `"router-link-active"`

全局配置 `<router-link>` 的默认“激活 class 类名”。参考 [router-link](#router-link)。
全局配置 `<router-link>` 默认的激活的 class。参考 [router-link](#router-link)。

### linkExactActiveClass

- 类型: `string`

- 默认值: `"router-link-exact-active"`

全局配置 `<router-link>` 精确激活的默认的 class。可同时翻阅 [router-link](#router-link)。
全局配置 `<router-link>` 默认的精确激活的 class。可同时翻阅 [router-link](#router-link)。

### scrollBehavior

Expand Down Expand Up @@ -285,18 +317,20 @@ sidebar: auto
## Router 实例方法
### router.beforeEach
### router.beforeResolve
### router.afterEach
函数签名：
``` js
```js
router.beforeEach((to, from, next) => {
/* must call `next` */
/* 必须调用 `next` */
})

router.beforeResolve((to, from, next) => {
/* must call `next` */
/* 必须调用 `next` */
})

router.afterEach((to, from) => {})
Expand All @@ -307,14 +341,18 @@ router.afterEach((to, from) => {})
在 2.5.0+ 这三个方法都返回一个移除已注册的守卫/钩子的函数。

### router.push

### router.replace

### router.go

### router.back

### router.forward

函数签名：

``` js
```js
router.push(location, onComplete?, onAbort?)
router.push(location).then(onComplete).catch(onAbort)
router.replace(location, onComplete?, onAbort?)
Expand All @@ -330,7 +368,7 @@ router.forward()
函数签名：
``` js
```js
const matchedComponents: Array<Component> = router.getMatchedComponents(location?)
```
Expand All @@ -340,7 +378,7 @@ const matchedComponents: Array<Component> = router.getMatchedComponents(location
函数签名：
``` js
```js
const resolved: {
location: Location;
route: Route;
Expand All @@ -357,7 +395,7 @@ const resolved: {
函数签名：
``` js
```js
router.addRoutes(routes: Array<RouteConfig>)
```
Expand All @@ -367,7 +405,7 @@ router.addRoutes(routes: Array<RouteConfig>)
函数签名：
``` js
```js
router.onReady(callback, [errorCallback])
```
Expand All @@ -381,7 +419,7 @@ router.onReady(callback, [errorCallback])
函数签名：
``` js
```js
router.onError(callback)
```
Expand Down Expand Up @@ -409,65 +447,67 @@ router.onError(callback)
- 导航守卫的参数：
``` js
```js
router.beforeEach((to, from, next) => {
// `to` 和 `from` 都是路由对象
})
```
- `scrollBehavior` 方法的参数:
``` js
```js
const router = new VueRouter({
scrollBehavior (to, from, savedPosition) {
scrollBehavior(to, from, savedPosition) {
// `to` 和 `from` 都是路由对象
}
})
```
### 路由对象属性
- **$route.path**
- **\$route.path**
- 类型: `string`
字符串，对应当前路由的路径，总是解析为绝对路径，如 `"/foo/bar"`。
- **$route.params**
- **\$route.params**
- 类型: `Object`
一个 key/value 对象，包含了动态片段和全匹配片段，如果没有路由参数，就是一个空对象。
- **$route.query**
- **\$route.query**
- 类型: `Object`
一个 key/value 对象，表示 URL 查询参数。例如，对于路径 `/foo?user=1`，则有 `$route.query.user == 1`，如果没有查询参数，则是个空对象。
- **$route.hash**
- **\$route.hash**
- 类型: `string`
当前路由的 hash 值 (带 `#`) ，如果没有 hash 值，则为空字符串。
- **$route.fullPath**
- **\$route.fullPath**
- 类型: `string`
完成解析后的 URL，包含查询参数和 hash 的完整路径。
- **$route.matched**
- **\$route.matched**
- 类型: `Array<RouteRecord>`
一个数组，包含当前路由的所有嵌套路径片段的**路由记录** 。路由记录就是 `routes` 配置数组中的对象副本 (还有在 `children` 数组)。
``` js
```js
const router = new VueRouter({
routes: [
// 下面的对象就是路由记录
{ path: '/foo', component: Foo,
{
path: '/foo',
component: Foo,
children: [
// 这也是个路由记录
{ path: 'bar', component: Bar }
Expand All @@ -479,11 +519,11 @@ router.onError(callback)
当 URL 为 `/foo/bar`，`$route.matched` 将会是一个包含从上到下的所有对象 (副本)。
- **$route.name**
- **\$route.name**
当前路由的名称，如果有的话。(查看[命名路由](../guide/essentials/named-routes.md))
- **$route.redirectedFrom**
- **\$route.redirectedFrom**
如果存在重定向，即为重定向来源的路由的名字。(参阅[重定向和别名](../guide/essentials/redirect-and-alias.md))
Expand All @@ -493,11 +533,11 @@ router.onError(callback)
通过在 Vue 根实例的 `router` 配置传入 router 实例，下面这些属性成员会被注入到每个子组件。
- **this.$router**
- **this.\$router**
router 实例。
- **this.$route**
- **this.\$route**
当前激活的[路由信息对象](#路由对象)。这个属性是只读的，里面的属性是 immutable (不可变) 的，不过你可以 watch (监测变化) 它。
Expand Down
Loading

0 comments on commit 039bd8f

Please sign in to comment.