vuejs / docs

📄 Documentation for Vue 3
https://vuejs.org
Other
2.94k stars 4.47k forks source link

Add a remark about watching objects/array refs #2454

Open silentmantra opened 1 year ago

silentmantra commented 1 year ago

From the docs at least for me it's not obvious that watching a ref is actually shallow watching its value only.
The problem that we know that an object/array ref makes the object/array accessed through the ref's value reactive. So intuitively it could seem that watching an object/array ref is deep like watching a reactive variable, but it's not.

I think a remark about this case should be added in the docs, otherwise I see periodically that kind of questions on the stackoverflow:

https://stackoverflow.com/questions/76786334/cannot-watch-an-array-ref-in-vue-3/76786671

alexchexes commented 1 year ago

Absolutely. There is inconsistent terminology usage. The deep watchers section states the following:

When you call watch() directly on a reactive object, it will implicitly create a deep watcher.

At the same time, the ref() documentation section states:

ref() Takes an inner value and returns a reactive and mutable ref object.

But actually, when you call watch() on ref (which is a reactive object according to the ref() documentation), it will not create a deep watcher.

So this needs to be clarified, as the current phrasing is misleading.

soletan commented 5 months ago

I was searching the documentation for a hint on why this example does not work (showing "changes: 2"). Stumbling upon the same statement in docs about watch() deeply watching by default was definitely confusing here.