diff --git a/docs/zh/api/index.md b/docs/zh/api/index.md index 9a7e7343e..67a35c09c 100644 --- a/docs/zh/api/index.md +++ b/docs/zh/api/index.md @@ -40,9 +40,7 @@ sidebar: auto - 类型: `{ [type: string]: Function }` - 在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数，`payload` 作为第二个参数（可选）。 - - `context` 对象包含以下属性： + 在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数，`context` 对象包含以下属性： ``` js { @@ -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 ``` @@ -89,12 +87,12 @@ sidebar: auto 包含了子模块的对象，会被合并到 store，大概长这样： - ``` js + ```js { key: { state, namespaced?, - mutations, + mutations?, actions?, getters?, modules? @@ -130,7 +128,7 @@ sidebar: auto 为某个特定的 Vuex 实例打开或关闭 devtools。对于传入 `false` 的实例来说 Vuex store 不会订阅到 devtools 插件。对于一个页面中有多个 store 的情况非常有用。 - ``` js + ```js { devtools: false } @@ -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` -- `dispatch(action: Object, options?: Object): Promise` +- `dispatch(type: string, payload?: any, options?: Object): Promise` +- `dispatch(action: Object, options?: Object): Promise` 分发 action。`options` 里可以有 `root: true`，它允许在[命名空间模块](../guide/modules.md#命名空间)里分发根的 action。返回一个解析所有被触发的 action 处理器的 Promise。[详细介绍](../guide/actions.md) @@ -174,7 +172,7 @@ 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) 方法的参数。 @@ -182,50 +180,58 @@ sidebar: auto ### 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}`) @@ -238,7 +244,7 @@ sidebar: auto `subscribeAction` 也可以指定一个 `error` 处理函数以捕获分发 action 的时候被抛出的错误。该函数会从第三个参数接收到一个 `error` 对象。 - ``` js + ```js store.subscribeAction({ error: (action, state, error) => { console.log(`error action ${action.type}`) @@ -251,7 +257,7 @@ sidebar: auto ### registerModule -- `registerModule(path: string | Array, module: Module, options?: Object)` +- `registerModule(path: string | Array, module: Module, options?: Object)` 注册一个动态模块。[详细介绍](../guide/modules.md#模块动态注册) @@ -259,7 +265,7 @@ sidebar: auto ### unregisterModule -- `unregisterModule(path: string | Array)` +- `unregisterModule(path: string | Array)` 卸载一个动态模块。[详细介绍](../guide/modules.md#模块动态注册) @@ -271,7 +277,7 @@ sidebar: auto ### hotUpdate -- `hotUpdate(newOptions: Object)` +- `hotUpdate(newOptions: Object)` 热替换新的 action 和 mutation。[详细介绍](../guide/hot-reload.md) @@ -279,7 +285,7 @@ sidebar: auto ### mapState -- `mapState(namespace?: string, map: Array | Object): Object` +- `mapState(namespace?: string, map: Array | Object): Object` 为组件创建计算属性以返回 Vuex store 中的状态。[详细介绍](../guide/state.md#mapstate-辅助函数) @@ -289,7 +295,7 @@ sidebar: auto ### mapGetters -- `mapGetters(namespace?: string, map: Array | Object): Object` +- `mapGetters(namespace?: string, map: Array | Object): Object` 为组件创建计算属性以返回 getter 的返回值。[详细介绍](../guide/getters.md#mapgetters-辅助函数) @@ -297,7 +303,7 @@ sidebar: auto ### mapActions -- `mapActions(namespace?: string, map: Array | Object): Object` +- `mapActions(namespace?: string, map: Array | Object): Object` 创建组件方法分发 action。[详细介绍](../guide/actions.md#在组件中分发-action) @@ -307,7 +313,7 @@ sidebar: auto ### mapMutations -- `mapMutations(namespace?: string, map: Array | Object): Object` +- `mapMutations(namespace?: string, map: Array | Object): Object` 创建组件方法提交 mutation。[详细介绍](../guide/mutations.md#在组件中提交-mutation) @@ -378,7 +384,7 @@ sidebar: auto 最后，将 key 传递给 `useStore` 方法以获取指定类型的 store 实例。 ```ts - // vue 组件 + // 在 vue 组件内 import { useStore } from 'vuex' import { key } from './store' diff --git a/docs/zh/guide/actions.md b/docs/zh/guide/actions.md index 5e7d76aed..3b75834aa 100644 --- a/docs/zh/guide/actions.md +++ b/docs/zh/guide/actions.md @@ -81,7 +81,8 @@ actions: { checkout ({ commit, state }, products) { // 把当前购物车的物品备份起来 const savedCartItems = [...state.cart.added] - // 发出结账请求，然后乐观地清空购物车 + // 发出结账请求 + // 然后乐观地清空购物车 commit(types.CHECKOUT_REQUEST) // 购物 API 接受一个成功回调和一个失败回调 shop.buyProducts( diff --git a/docs/zh/guide/forms.md b/docs/zh/guide/forms.md index d229ed2e1..d9095c728 100644 --- a/docs/zh/guide/forms.md +++ b/docs/zh/guide/forms.md @@ -15,6 +15,7 @@ ``` html ``` + ``` js // ... computed: { @@ -47,6 +48,7 @@ mutations: { ``` html ``` + ``` js // ... computed: { diff --git a/docs/zh/guide/getters.md b/docs/zh/guide/getters.md index cc016797a..daf790e20 100644 --- a/docs/zh/guide/getters.md +++ b/docs/zh/guide/getters.md @@ -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 作为其第一个参数： @@ -31,7 +31,7 @@ const store = createStore({ ] }, getters: { - doneTodos: (state) => { + doneTodos (state) { return state.todos.filter(todo => todo.done) } } diff --git a/docs/zh/guide/modules.md b/docs/zh/guide/modules.md index 47fc1f8f1..4976aa482 100644 --- a/docs/zh/guide/modules.md +++ b/docs/zh/guide/modules.md @@ -46,7 +46,6 @@ const moduleA = { state.count++ } }, - getters: { doubleCount (state) { return state.count * 2 @@ -151,6 +150,7 @@ modules: { someGetter (state, getters, rootState, rootGetters) { getters.someOtherGetter // -> 'foo/someOtherGetter' rootGetters.someOtherGetter // -> 'someOtherGetter' + rootGetters['bar/someOtherGetter'] // -> 'bar/someOtherGetter' }, someOtherGetter: state => { ... } }, @@ -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' @@ -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([ @@ -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', [ @@ -290,6 +299,7 @@ const store = createStore({ /* 选项 */ }) store.registerModule('myModule', { // ... }) + // 注册嵌套模块 `nested/myModule` store.registerModule(['nested', 'myModule'], { // ... diff --git a/docs/zh/guide/mutations.md b/docs/zh/guide/mutations.md index a3393336b..9a8a7b6fb 100644 --- a/docs/zh/guide/mutations.md +++ b/docs/zh/guide/mutations.md @@ -36,6 +36,7 @@ mutations: { } } ``` + ``` js store.commit('increment', 10) ``` @@ -95,7 +96,8 @@ import { SOME_MUTATION } from './mutation-types' const store = createStore({ state: { ... }, mutations: { - // 我们可以使用 ES2015 风格的计算属性命名功能来使用一个常量作为函数名 + // 我们可以使用 ES2015 风格的计算属性命名功能 + // 来使用一个常量作为函数名 [SOME_MUTATION] (state) { // 修改 state } diff --git a/docs/zh/guide/plugins.md b/docs/zh/guide/plugins.md index de068d94d..99d4c4a31 100644 --- a/docs/zh/guide/plugins.md +++ b/docs/zh/guide/plugins.md @@ -27,7 +27,7 @@ const store = createStore({ 在插件中不允许直接修改状态——类似于组件，只能通过提交 mutation 来触发变化。 -通过提交 mutation，插件可以用来同步数据源到 store。例如，同步 websocket 数据源到 store（下面是个大概例子，实际上 `createPlugin` 方法可以有更多选项来完成复杂任务）： +通过提交 mutation，插件可以用来同步数据源到 store。例如，同步 websocket 数据源到 store（下面是个大概例子，实际上 `createWebSocketPlugin` 方法可以有更多选项来完成复杂任务）： ``` js export default function createWebSocketPlugin (socket) { @@ -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()] }) ``` diff --git a/docs/zh/guide/testing.md b/docs/zh/guide/testing.md index 11f5a6ee8..c2ea95327 100644 --- a/docs/zh/guide/testing.md +++ b/docs/zh/guide/testing.md @@ -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) diff --git a/docs/zh/guide/typescript-support.md b/docs/zh/guide/typescript-support.md index 84794c8cc..70c3967c6 100644 --- a/docs/zh/guide/typescript-support.md +++ b/docs/zh/guide/typescript-support.md @@ -12,7 +12,6 @@ Vuex 没有为 `this.$store` 属性提供开箱即用的类型声明。如果你 ```ts // vuex.d.ts -import { ComponentCustomProperties } from 'vue' import { Store } from 'vuex' declare module '@vue/runtime-core' { @@ -91,7 +90,6 @@ export default { 本质上，Vuex 将store 安装到 Vue 应用中使用了 Vue 的 [Provide/Inject](https://v3.cn.vuejs.org/api/composition-api.html#provide-inject) 特性，这就是 injection key 是很重要的因素的原因。 - ### 简化 `useStore` 用法 引入 `InjectionKey` 并将其传入 `useStore` 使用过的任何地方，很快就会成为一项重复性的工作。为了简化问题，可以定义自己的组合式函数来检索类型化的 store ：