Skip to content

Commit a701210

Browse files
yyx990803yyx990803
committed
update module namespace docs
1 parent ebecec7 commit a701210

File tree

1 file changed

+104
-56
lines changed

1 file changed

+104
-56
lines changed

‎docs/en/modules.md

Lines changed: 104 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -81,83 +81,131 @@ const moduleA = {
8181

8282
### Namespacing
8383

84-
> This feature is not released yet! It will be out soon in [email protected].
84+
By default, actions, mutations and getters inside modules are still registered under the **global namespace** - this allows multiple modules to react to the same mutation/action type.
8585

86-
Note that actions, mutations and getters inside modules are still registered under the **global namespace** - this allows multiple modules to react to the same mutation/action type. You probably should namespace your Vuex module if you are writing a reusable one that will be used in unknown environments. To support namespacing for avoiding name clashing, Vuex provides `namespace` option. If you specify string value to `namespace` option, module assets types are prefixed by the given value:
86+
If you want your modules to be more self-contained or resuable, you can mark it as namespaced with `namespaced: true`. When the module is registered, all of its getters, actions and mutations will be automatically namespaced based on the path the module is registered at. For example:
8787

8888
``` js
89-
export default {
90-
namespace: 'account/',
91-
92-
// module assets
93-
state: { ... }, // module state will not be changed by prefix option
94-
getters: {
95-
isAdmin () { ... } // -> getters['account/isAdmin']
96-
},
97-
actions: {
98-
login () { ... } // -> dispatch('account/login')
99-
},
100-
mutations: {
101-
login () { ... } // -> commit('account/login')
102-
},
103-
104-
// nested modules
89+
const store = new Vuex.Store({
10590
modules: {
106-
// inherit the namespace from parent module
107-
myPage: {
108-
state: { ... },
109-
getters: {
110-
profile () { ... } // -> getters['account/profile']
111-
}
112-
},
91+
account: {
92+
namespaced: true,
11393

114-
// nest the namespace
115-
posts: {
116-
namespace: 'posts/',
117-
118-
state: { ... },
94+
// module assets
95+
state: { ... }, // module state is already nested and not affected by namespace option
11996
getters: {
120-
popular () { ... } // -> getters['account/posts/popular']
97+
isAdmin () { ... } // -> getters['account/isAdmin']
98+
},
99+
actions: {
100+
login () { ... } // -> dispatch('account/login')
101+
},
102+
mutations: {
103+
login () { ... } // -> commit('account/login')
104+
},
105+
106+
// nested modules
107+
modules: {
108+
// inherits the namespace from parent module
109+
myPage: {
110+
state: { ... },
111+
getters: {
112+
profile () { ... } // -> getters['account/profile']
113+
}
114+
},
115+
116+
// further nest the namespace
117+
posts: {
118+
namespaced: true,
119+
120+
state: { ... },
121+
getters: {
122+
popular () { ... } // -> getters['account/posts/popular']
123+
}
124+
}
121125
}
122126
}
123127
}
124-
}
128+
})
125129
```
126130

127-
Namespaced getters and actions will receive localized `getters`, `dispatch` and `commit`. In other words, you can use the module assets without writing prefix in the same module. If you want to use the global ones, `rootGetters` is passed to the 4th argument of getter functions and the property of the action context. In addition, `dispatch` and `commit` receives `root` option on their last argument.
131+
Namespaced getters and actions will receive localized `getters`, `dispatch` and `commit`. In other words, you can use the module assets without writing prefix in the same module. Toggling between namespaced or not does not affect the code inside the module.
128132

129-
``` js
130-
export default {
131-
namespace: 'prefix/',
133+
#### Accessing Global Assets in Namespaced Modules
132134

133-
getters: {
134-
// `getters` is localized to this module's getters
135-
// you can use rootGetters via 4th argument of getters
136-
someGetter (state, getters, rootState, rootGetters) {
137-
getters.someOtherGetter // -> 'prefix/someOtherGetter'
138-
rootGetters.someOtherGetter // -> 'someOtherGetter'
135+
If you want to use global state and getters, `rootState` and `rootGetters` are passed as the 3rd and 4th arguments to getter functions, and also exposed as properties on the `context` object passed to action functions.
136+
137+
To dispatch actions or commit mutations in the global namespace, pass `{ root: true }` as the 3rd argument to `dispatch` and `commit`.
138+
139+
``` js
140+
modules: {
141+
foo: {
142+
namespaced: true,
143+
144+
getters: {
145+
// `getters` is localized to this module's getters
146+
// you can use rootGetters via 4th argument of getters
147+
someGetter (state, getters, rootState, rootGetters) {
148+
getters.someOtherGetter // -> 'foo/someOtherGetter'
149+
rootGetters.someOtherGetter // -> 'someOtherGetter'
150+
},
151+
someOtherGetter: state => { ... }
139152
},
140-
someOtherGetter: state => { ... }
141-
},
142153

143-
actions: {
144-
// dispatch and commit are also localized for this module
145-
// they will accept `root` option for the root dispatch/commit
146-
someAction ({ dispatch, commit, getters, rootGetters }) {
147-
getters.someGetter // -> 'prefix/someGetter'
148-
rootGetters.someGetter // -> 'someGetter'
154+
actions: {
155+
// dispatch and commit are also localized for this module
156+
// they will accept `root` option for the root dispatch/commit
157+
someAction ({ dispatch, commit, getters, rootGetters }) {
158+
getters.someGetter // -> 'foo/someGetter'
159+
rootGetters.someGetter // -> 'someGetter'
149160

150-
dispatch('someOtherAction') // -> 'prefix/someOtherAction'
151-
dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
161+
dispatch('someOtherAction') // -> 'foo/someOtherAction'
162+
dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
152163

153-
commit('someMutation') // -> 'prefix/someMutation'
154-
commit('someMutation', null, { root: true }) // -> 'someMutation'
155-
},
156-
someOtherAction (ctx, payload) { ... }
164+
commit('someMutation') // -> 'foo/someMutation'
165+
commit('someMutation', null, { root: true }) // -> 'someMutation'
166+
},
167+
someOtherAction (ctx, payload) { ... }
168+
}
157169
}
158170
}
159171
```
160172

173+
#### Binding Helpers with Namespace
174+
175+
When binding a namespaced module to components with the `mapState`, `mapGetters`, `mapActions` and `mapMutations` helpers, it can get a bit verbose:
176+
177+
``` js
178+
computed: {
179+
...mapState({
180+
a: state => state.some.nested.module.a,
181+
b: state => state.some.nested.module.b
182+
})
183+
},
184+
methods: {
185+
...mapActions([
186+
'some/nested/module/foo',
187+
'some/nested/module/bar'
188+
])
189+
}
190+
```
191+
192+
In such cases, you can pass the module namespace string as the first argument to the helpers so that all bindings are done using that module as the context. The above can be simplified to:
193+
194+
``` js
195+
computed: {
196+
...mapState('some/nested/module', {
197+
a: state => state.a,
198+
b: state => state.b
199+
})
200+
},
201+
methods: {
202+
...mapActions('some/nested/module', [
203+
'foo',
204+
'bar'
205+
])
206+
}
207+
```
208+
161209
#### Caveat for Plugin Developers
162210

163211
You may care about unpredictable namespacing for your modules when you create a [plugin](plugins.md) that provides the modules and let users add them to a Vuex store. Your modules will be also namespaced if the plugin users add your modules under a namespaced module. To adapt this situation, you may need to receive a namespace value via your plugin option:

0 commit comments

Comments
 (0)