Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs(zh): update zh docs from en docs (#2150)
* docs(zh): update zh docs from en docs

* Update docs/zh/api/index.md

Co-authored-by: Jinjiang <[email protected]>

* docs(zh): apply suggestions

* docs: apply suggestions

Co-authored-by: Jinjiang <[email protected]>
  • Loading branch information
KimYangOfCat and Jinjiang committed May 28, 2022
1 parent 75d20ec commit 01f87f0
Show file tree
Hide file tree
Showing 9 changed files with 67 additions and 48 deletions.
76 changes: 41 additions & 35 deletions docs/zh/api/index.md
Expand Up @@ -40,9 +40,7 @@ sidebar: auto

- 类型: `{ [type: string]: Function }`

在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数,`payload` 作为第二个参数(可选)。

`context` 对象包含以下属性:
在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数,`context` 对象包含以下属性:

``` js
{
Expand All @@ -67,15 +65,15 @@ sidebar: auto

```
state, // 如果在模块中定义则为模块的局部状态
getters, // 等同于 store.getters
getters // 等同于 store.getters
```

当定义在一个模块里时会特别一些:

```
state, // 如果在模块中定义则为模块的局部状态
getters, // 等同于 store.getters
rootState // 等同于 store.state
getters, // 当前模块的局部 getters
rootState, // 全局 state
rootGetters // 所有 getters
```

Expand All @@ -89,12 +87,12 @@ sidebar: auto

包含了子模块的对象,会被合并到 store,大概长这样:

``` js
```js
{
key: {
state,
namespaced?,
mutations,
mutations?,
actions?,
getters?,
modules?
Expand Down Expand Up @@ -130,7 +128,7 @@ sidebar: auto
为某个特定的 Vuex 实例打开或关闭 devtools。对于传入 `false` 的实例来说 Vuex store 不会订阅到 devtools 插件。对于一个页面中有多个 store 的情况非常有用。
``` js
```js
{
devtools: false
}
Expand All @@ -154,15 +152,15 @@ sidebar: auto
### commit
- `commit(type: string, payload?: any, options?: Object)`
- `commit(mutation: Object, options?: Object)`
- `commit(type: string, payload?: any, options?: Object)`
- `commit(mutation: Object, options?: Object)`
提交 mutation。`options` 里可以有 `root: true`,它允许在[命名空间模块](../guide/modules.md#命名空间)里提交根的 mutation。[详细介绍](../guide/mutations.md)
### dispatch
- `dispatch(type: string, payload?: any, options?: Object): Promise<any>`
- `dispatch(action: Object, options?: Object): Promise<any>`
- `dispatch(type: string, payload?: any, options?: Object): Promise<any>`
- `dispatch(action: Object, options?: Object): Promise<any>`
分发 action。`options` 里可以有 `root: true`,它允许在[命名空间模块](../guide/modules.md#命名空间)里分发根的 action。返回一个解析所有被触发的 action 处理器的 Promise。[详细介绍](../guide/actions.md)
Expand All @@ -174,58 +172,66 @@ sidebar: auto
### watch
- `watch(fn: Function, callback: Function, options?: Object): Function`
- `watch(fn: Function, callback: Function, options?: Object): Function`
 响应式地侦听 `fn` 的返回值,当值改变时调用回调函数。`fn` 接收 store 的 state 作为第一个参数,其 getter 作为第二个参数。最后接收一个可选的对象参数表示 Vue 的 [`vm.$watch`](https://cn.vuejs.org/v2/api/#vm-watch) 方法的参数。
 要停止侦听,调用此方法返回的函数即可停止侦听。
### subscribe
- `subscribe(handler: Function, options?: Object): Function`
- `subscribe(handler: Function, options?: Object): Function`
订阅 store 的 mutation。`handler` 会在每个 mutation 完成后调用,接收 mutation 和经过 mutation 后的状态作为参数:
``` js
store.subscribe((mutation, state) => {
```js
const unsubscribe = store.subscribe((mutation, state) => {
console.log(mutation.type)
console.log(mutation.payload)
})

// 你可以调用 unsubscribe 来停止订阅。
unsubscribe()
```
默认情况下,新的处理函数会被添加到其链的尾端,因此它会在其它之前已经被添加了的处理函数之后执行。这一行为可以通过向 `options` 添加 `prepend: true` 来覆写,即把处理函数添加到其链的最开始。
``` js
```js
store.subscribe(handler, { prepend: true })
```
 要停止订阅,调用此方法返回的函数即可停止订阅。
`subscribe` 方法将返回一个 `unsubscribe` 函数,当不再需要订阅时应该调用该函数。例如,你可能会订阅一个 Vuex 模块,当你取消注册该模块时取消订阅。或者你可能从一个 Vue 组件内部调用 `subscribe`,然后不久就会销毁该组件。在这些情况下,你应该记得手动取消订阅。
通常用于插件。[详细介绍](../guide/plugins.md)
### subscribeAction
- `subscribeAction(handler: Function, options?: Object): Function`
- `subscribeAction(handler: Function, options?: Object): Function`
订阅 store 的 action。`handler` 会在每个 action 分发的时候调用并接收 action 描述和当前的 store 的 state 这两个参数:
订阅 store 的 action。`handler` 会在每个 action 分发的时候调用并接收 action 描述和当前的 store 的 state 这两个参数。
`subscribe` 方法将返回一个 `unsubscribe` 函数,当不再需要订阅时,应调用该函数。例如,当取消注册一个 Vuex 模块或销毁一个 Vue 组件之前。
``` js
store.subscribeAction((action, state) => {
```js
const unsubscribe = store.subscribeAction((action, state) => {
console.log(action.type)
console.log(action.payload)
})

// 你可以调用 unsubscribe 来停止订阅。
unsubscribe()
```
默认情况下,新的处理函数会被添加到其链的尾端,因此它会在其它之前已经被添加了的处理函数之后执行。这一行为可以通过向 `options` 添加 `prepend: true` 来覆写,即把处理函数添加到其链的最开始。
``` js
```js
store.subscribeAction(handler, { prepend: true })
```
要停止订阅,调用此方法返回的函数即可停止订阅
`subscribeAction` 方法将返回一个 `unsubscribe` 函数,当不再需要订阅时,应该调用该函数。例如,你可能会订阅一个 Vuex 模块,并在取消注册该模块时取消订阅。或者你可能从 Vue 组件内部调用`subscribeAction`,然后不久就会销毁该组件。在这些情况下,你应该记得手动取消订阅
`subscribeAction` 也可以指定订阅处理函数的被调用时机应该在一个 action 分发*之前*还是*之后* (默认行为是*之前*):
``` js
```js
store.subscribeAction({
before: (action, state) => {
console.log(`before action ${action.type}`)
Expand All @@ -238,7 +244,7 @@ sidebar: auto
`subscribeAction` 也可以指定一个 `error` 处理函数以捕获分发 action 的时候被抛出的错误。该函数会从第三个参数接收到一个 `error` 对象。
``` js
```js
store.subscribeAction({
error: (action, state, error) => {
console.log(`error action ${action.type}`)
Expand All @@ -251,15 +257,15 @@ sidebar: auto
### registerModule
- `registerModule(path: string | Array<string>, module: Module, options?: Object)`
- `registerModule(path: string | Array<string>, module: Module, options?: Object)`
注册一个动态模块。[详细介绍](../guide/modules.md#模块动态注册)
`options` 可以包含 `preserveState: true` 以允许保留之前的 state。用于服务端渲染。
### unregisterModule
- `unregisterModule(path: string | Array<string>)`
- `unregisterModule(path: string | Array<string>)`
卸载一个动态模块。[详细介绍](../guide/modules.md#模块动态注册)
Expand All @@ -271,15 +277,15 @@ sidebar: auto
### hotUpdate
- `hotUpdate(newOptions: Object)`
- `hotUpdate(newOptions: Object)`
热替换新的 action 和 mutation。[详细介绍](../guide/hot-reload.md)
## 组件绑定的辅助函数
### mapState
- `mapState(namespace?: string, map: Array<string> | Object<string | function>): Object`
- `mapState(namespace?: string, map: Array<string> | Object<string | function>): Object`

为组件创建计算属性以返回 Vuex store 中的状态。[详细介绍](../guide/state.md#mapstate-辅助函数)

Expand All @@ -289,15 +295,15 @@ sidebar: auto

### mapGetters

- `mapGetters(namespace?: string, map: Array<string> | Object<string>): Object`
- `mapGetters(namespace?: string, map: Array<string> | Object<string>): Object`

为组件创建计算属性以返回 getter 的返回值。[详细介绍](../guide/getters.md#mapgetters-辅助函数)

第一个参数是可选的,可以是一个命名空间字符串。[详细介绍](../guide/modules.md#带命名空间的绑定函数)

### mapActions

- `mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object`
- `mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object`

创建组件方法分发 action。[详细介绍](../guide/actions.md#在组件中分发-action)

Expand All @@ -307,7 +313,7 @@ sidebar: auto

### mapMutations

- `mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object`
- `mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object`

创建组件方法提交 mutation。[详细介绍](../guide/mutations.md#在组件中提交-mutation)

Expand Down Expand Up @@ -378,7 +384,7 @@ sidebar: auto
最后,将 key 传递给 `useStore` 方法以获取指定类型的 store 实例。
```ts
// vue 组件
// vue 组件内
import { useStore } from 'vuex'
import { key } from './store'

Expand Down
3 changes: 2 additions & 1 deletion docs/zh/guide/actions.md
Expand Up @@ -81,7 +81,8 @@ actions: {
checkout ({ commit, state }, products) {
// 把当前购物车的物品备份起来
const savedCartItems = [...state.cart.added]
// 发出结账请求,然后乐观地清空购物车
// 发出结账请求
// 然后乐观地清空购物车
commit(types.CHECKOUT_REQUEST)
// 购物 API 接受一个成功回调和一个失败回调
shop.buyProducts(
Expand Down
2 changes: 2 additions & 0 deletions docs/zh/guide/forms.md
Expand Up @@ -15,6 +15,7 @@
``` html
<input :value="message" @input="updateMessage">
```

``` js
// ...
computed: {
Expand Down Expand Up @@ -47,6 +48,7 @@ mutations: {
``` html
<input v-model="message">
```

``` js
// ...
computed: {
Expand Down
4 changes: 2 additions & 2 deletions docs/zh/guide/getters.md
Expand Up @@ -17,7 +17,7 @@ computed: {
Vuex 允许我们在 store 中定义“getter”(可以认为是 store 的计算属性)。

::: warning 注意
从 Vue 3.0 开始,getter 的结果不再像计算属性一样会被缓存起来。这是一个已知的问题,将会在 3.2 版本中修复。详情请看 [PR #1878](https://github.com/vuejs/vuex/pull/1883)
从 Vue 3.0 开始,getter 的结果不再像计算属性一样会被缓存起来。这是一个已知的问题,将会在 3.1 版本中修复。详情请看 [PR #1878](https://github.com/vuejs/vuex/pull/1883)
:::

Getter 接受 state 作为其第一个参数:
Expand All @@ -31,7 +31,7 @@ const store = createStore({
]
},
getters: {
doneTodos: (state) => {
doneTodos (state) {
return state.todos.filter(todo => todo.done)
}
}
Expand Down
16 changes: 13 additions & 3 deletions docs/zh/guide/modules.md
Expand Up @@ -46,7 +46,6 @@ const moduleA = {
state.count++
}
},

getters: {
doubleCount (state) {
return state.count * 2
Expand Down Expand Up @@ -151,6 +150,7 @@ modules: {
someGetter (state, getters, rootState, rootGetters) {
getters.someOtherGetter // -> 'foo/someOtherGetter'
rootGetters.someOtherGetter // -> 'someOtherGetter'
rootGetters['bar/someOtherGetter'] // -> 'bar/someOtherGetter'
},
someOtherGetter: state => { ... }
},
Expand All @@ -161,6 +161,7 @@ modules: {
someAction ({ dispatch, commit, getters, rootGetters }) {
getters.someGetter // -> 'foo/someGetter'
rootGetters.someGetter // -> 'someGetter'
rootGetters['bar/someGetter'] // -> 'bar/someGetter'

dispatch('someOtherAction') // -> 'foo/someOtherAction'
dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
Expand Down Expand Up @@ -209,7 +210,11 @@ computed: {
...mapState({
a: state => state.some.nested.module.a,
b: state => state.some.nested.module.b
})
}),
...mapGetters([
'some/nested/module/someGetter', // -> this['some/nested/module/someGetter']
'some/nested/module/someOtherGetter', // -> this['some/nested/module/someOtherGetter']
])
},
methods: {
...mapActions([
Expand All @@ -226,7 +231,11 @@ computed: {
...mapState('some/nested/module', {
a: state => state.a,
b: state => state.b
})
}),
...mapGetters('some/nested/module', [
'someGetter', // -> this.someGetter
'someOtherGetter', // -> this.someOtherGetter
])
},
methods: {
...mapActions('some/nested/module', [
Expand Down Expand Up @@ -290,6 +299,7 @@ const store = createStore({ /* 选项 */ })
store.registerModule('myModule', {
// ...
})

// 注册嵌套模块 `nested/myModule`
store.registerModule(['nested', 'myModule'], {
// ...
Expand Down
4 changes: 3 additions & 1 deletion docs/zh/guide/mutations.md
Expand Up @@ -36,6 +36,7 @@ mutations: {
}
}
```

``` js
store.commit('increment', 10)
```
Expand Down Expand Up @@ -95,7 +96,8 @@ import { SOME_MUTATION } from './mutation-types'
const store = createStore({
state: { ... },
mutations: {
// 我们可以使用 ES2015 风格的计算属性命名功能来使用一个常量作为函数名
// 我们可以使用 ES2015 风格的计算属性命名功能
// 来使用一个常量作为函数名
[SOME_MUTATION] (state) {
// 修改 state
}
Expand Down
6 changes: 3 additions & 3 deletions docs/zh/guide/plugins.md
Expand Up @@ -27,7 +27,7 @@ const store = createStore({

在插件中不允许直接修改状态——类似于组件,只能通过提交 mutation 来触发变化。

通过提交 mutation,插件可以用来同步数据源到 store。例如,同步 websocket 数据源到 store(下面是个大概例子,实际上 `createPlugin` 方法可以有更多选项来完成复杂任务):
通过提交 mutation,插件可以用来同步数据源到 store。例如,同步 websocket 数据源到 store(下面是个大概例子,实际上 `createWebSocketPlugin` 方法可以有更多选项来完成复杂任务):

``` js
export default function createWebSocketPlugin (socket) {
Expand Down Expand Up @@ -90,9 +90,9 @@ const store = createStore({
Vuex 自带一个日志插件用于一般的调试:

``` js
import createLogger from 'vuex/dist/logger'
import { createLogger } from 'vuex'

const store = new Vuex.Store({
const store = createStore({
plugins: [createLogger()]
})
```
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/guide/testing.md
Expand Up @@ -119,7 +119,7 @@ const testAction = (action, args, state, expectedMutations, done) => {

describe('actions', () => {
it('getAllProducts', done => {
testAction(actions.getAllProducts, [], {}, [
testAction(actions.getAllProducts, null, {}, [
{ type: 'REQUEST_PRODUCTS' },
{ type: 'RECEIVE_PRODUCTS', payload: { /* mocked response */ } }
], done)
Expand Down

0 comments on commit 01f87f0

Please sign in to comment.