-
Notifications
You must be signed in to change notification settings - Fork 4.7k
Rework the Reactivity in Depth guide #934
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@skirtles-code great improvements! I've left a few non-blocking points for your consideration
Is there a way to speak about |
@stafyniaksacha Those functions are covered more thoroughly on the next page of the guide. This page is trying to explain the underlying mechanics of how the reactivity system works rather than the specific details of how the individual functions behave. Arguably some of the material on this page, e.g. the sections Proxied Objects and Proxy vs. original identity, stray a little from the central topic and should be moved elsewhere. Those sections already existed prior to my reworking so I've retained them for now but it may make sense to move them eventually, especially once we introduce a proper page of Vue 3 reactivity caveats (#849). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Solid improvements @skirtles-code! Going to go ahead and merge this because we can always iterate with another PR. Thanks for your work on this!
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