Rework the Reactivity in Depth guide #934
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of Problem
Rendered: https://deploy-preview-934--vue-docs-next-preview.netlify.app/guide/reactivity.html
This started as an attempt to make some small tweaks to the Reactivity in Depth page. One tweak led to another and the end result is a significant reworking of the existing page. Much of the original structure remains but the diff will likely be a mess and I suggest that any reviewers approach it is as though it were a new page.
The biggest addition is a section about effects. The term 'effect' is used by subsequent pages in the guide (e.g. when discussing effect flush timing) but it wasn't really explained anywhere. It also appears in the animation at the bottom of this page. To my mind, this is a really important concept that forms a key part of the 'how reactivity works' puzzle. Once the concept is introduced I have then weaved it in where appropriate for the explanations that follow.
I have intentionally avoided using the term 'watcher'. Roughly speaking, a watcher is a combination of an effect and a separate callback function. I didn't want to introduce yet another concept on this page if I could help it and, hopefully, the explanations hold together without explicitly mentioning it.
Some of the later examples on the existing page use a function called
reactive
. However, it wasn't explicitly stated what that function was or how it related to the proxies shown earlier. Whilereactive
and related functions are covered more thoroughly on the next page of the guide, I've tried to tie everything together a little more explicitly, before it gets used by those later examples.The original proxy examples are mostly unchanged. I've renamed the parameters to avoid the names
prop
andkey
, as those terms have other connotations in Vue that could lead to confusion. I have also merged the first couple of proxy examples. Those two examples only differed by a single line of console logging, so a single example seemed sufficient.There are various other changes throughout but I hope they are mostly self-explanatory. Please feel free to to ask for clarification about any of the changes I've made.
Additional Information