Skip to content

Commit def2c8d

Browse files
committed
[docs] update getters and actions
1 parent b5816ff commit def2c8d

File tree

5 files changed

+42
-17
lines changed

5 files changed

+42
-17
lines changed

docs/en/SUMMARY.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
- [What is Vuex?](intro.md)
66
- [Getting Started](getting-started.md)
77
- Core Concepts
8-
- [State](state.md)
8+
- [State and Getters](state.md)
99
- [Mutations](mutations.md)
1010
- [Actions](actions.md)
1111
- [Data Flow](data-flow.md)

docs/en/actions.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ import { incrementBy } from './actions'
5959

6060
const vm = new Vue({
6161
vuex: {
62-
state: { ... }, // state getters
62+
getters: { ... }, // state getters
6363
actions: {
6464
incrementBy // ES6 object literal shorthand, bind using the same name
6565
}
@@ -93,7 +93,7 @@ import { incrementBy } from './actions'
9393

9494
const vm = new Vue({
9595
vuex: {
96-
state: { ... },
96+
getters: { ... },
9797
actions: {
9898
plus: incrementBy // bind using a different name
9999
}
@@ -103,27 +103,31 @@ const vm = new Vue({
103103

104104
Now the action will be bound as `vm.plus` instead of `vm.incrementBy`.
105105

106+
### Inline Actions
107+
106108
If an action is specific to a component, you can take the shortcut and just define it inline:
107109

108110
``` js
109111
const vm = new Vue({
110112
vuex: {
111-
state: { ... },
113+
getters: { ... },
112114
actions: {
113115
plus: ({ dispatch }) => dispatch('INCREMENT')
114116
}
115117
}
116118
})
117119
```
118120

119-
Finally, if you simply want to bind all the actions:
121+
### Binding All Actions
122+
123+
If you simply want to bind all the shared actions:
120124

121125
``` js
122126
import * as actions from './actions'
123127

124128
const vm = new Vue({
125129
vuex: {
126-
state: { ... },
130+
getters: { ... },
127131
actions // bind all actions
128132
}
129133
})

docs/en/data-flow.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ const app = new Vue({
6565
el: '#app',
6666
store,
6767
vuex: {
68-
state: {
68+
getters: {
6969
count: state => state.count
7070
},
7171
actions: {

docs/en/forms.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The "Vuex way" to deal with it is binding the `<input>`'s value and call an acti
1616
``` js
1717
// ...
1818
vuex: {
19-
state: {
19+
getters: {
2020
message: state => state.obj.message
2121
},
2222
actions: {

docs/en/state.md

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# State
1+
# State and Getters
22

33
### Single State Tree
44

@@ -48,7 +48,7 @@ However, this pattern causes the component to rely on the global store singleton
4848

4949
By providing the `store` option to the root instance, the store will be injected into all child components of the root and will be available on them as `this.$store`. However it's quite rare that we will need to actually reference it.
5050

51-
2. Inside child components, retrieve state with **getter** functions in the `vuex.state` option:
51+
2. Inside child components, retrieve state with **getter** functions in the `vuex.getters` option:
5252

5353
``` js
5454
// MyComponent.js
@@ -57,7 +57,7 @@ However, this pattern causes the component to rely on the global store singleton
5757
data () { ... },
5858
// this is where we retrieve state from the store
5959
vuex: {
60-
state: {
60+
getters: {
6161
// a state getter function, which will
6262
// bind `store.state.count` on the component as `this.count`
6363
count: function (state) {
@@ -74,19 +74,38 @@ However, this pattern causes the component to rely on the global store singleton
7474

7575
``` js
7676
vuex: {
77-
state: {
77+
getters: {
7878
count: state => state.count
7979
}
8080
}
8181
```
8282

83+
### Getters Must Be Pure
84+
85+
All Vuex getters must be [pure functions](https://en.wikipedia.org/wiki/Pure_function) - they take the entire state tree in, and return some value solely based on that state. This makes them more testable, composable and efficient. It also means **you cannot rely on `this` inside getters**.
86+
87+
If you do need access to `this`, for example to compute derived state based on the component's local state or props, you need to define separate, plain computed properties:
88+
89+
``` js
90+
vuex: {
91+
getters: {
92+
currentId: state => state.currentId
93+
}
94+
},
95+
computed: {
96+
isCurrent () {
97+
return this.id === this.currentId
98+
}
99+
}
100+
```
101+
83102
### Getters Can Return Derived State
84103

85104
Vuex state getters are computed properties under the hood, this means you can leverage them to reactively (and efficiently) compute derived state. For example, say in the state we have an array of `messages` containing all messages, and a `currentThreadID` representing a thread that is currently being viewed by the user. What we want to display to the user is a filtered list of messages that belong to the current thread:
86105

87106
``` js
88107
vuex: {
89-
state: {
108+
getters: {
90109
filteredMessages: state => {
91110
return state.messages.filter(message => {
92111
return message.threadID === state.currentThreadID
@@ -98,11 +117,9 @@ vuex: {
98117

99118
Because Vue.js computed properties are automatically cached and only re-evaluated when a reactive dependency changes, you don't need to worry about this function being called on every mutation.
100119

101-
> Flux reference: Vuex getters can be roughly compared to [`mapStateToProps`](https://github.com/rackt/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) in Redux. However, because they leverage Vue's computed properties memoization under the hood, they are more efficient than `mapStateToProps`, and more similar to [reselect](https://github.com/reactjs/reselect).
102-
103120
### Sharing Getters Across Multiple Components
104121

105-
As you can see, in most cases getters are just pure functions: they take the whole state in, and returns some value. The `filteredMessages` getter may be useful inside multiple components. In that case, it's a good idea to share the same function between them:
122+
As you can see, the `filteredMessages` getter may be useful inside multiple components. In that case, it's a good idea to share the same function between them:
106123

107124
``` js
108125
// getters.js
@@ -119,13 +136,17 @@ import { filteredMessages } from './getters'
119136

120137
export default {
121138
vuex: {
122-
state: {
139+
getters: {
123140
filteredMessages
124141
}
125142
}
126143
}
127144
```
128145

146+
Because getters are pure, getters shared across multiple components are efficiently cached: when dependencies change, they only re-evaluate once for all components that uses them.
147+
148+
> Flux reference: Vuex getters can be roughly compared to [`mapStateToProps`](https://github.com/rackt/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) in Redux. However, because they leverage Vue's computed properties memoization under the hood, they are more efficient than `mapStateToProps`, and more similar to [reselect](https://github.com/reactjs/reselect).
149+
129150
### Components Are Not Allowed to Directly Mutate State
130151

131152
It's important to remember that **components should never directly mutate Vuex store state**. Because we want every state mutation to be explicit and trackable, all vuex store state mutations must be conducted inside the store's mutation handlers.

0 commit comments

Comments
 (0)