跪拜 Guibai
← All articles
Vue.js

Vue v-model's Three Fake Syncs That Leave Captchas Stuck on 'Passed'

By ruanno_top ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Form resets that leave a captcha marked as 'passed' break the entire re-submission flow, locking users out without a page refresh. The three anti-patterns and a 30-second manual test give any Vue team a way to verify a component is truly controlled before trusting v-model.

Summary

A form reset clears inputs and dropdowns but the slider captcha stays green and unmovable. The parent writes `false` to `v-model`, yet the component never notices. Three distinct controlled-component mistakes cause this: emitting `update:modelValue` without declaring the `modelValue` prop, snapshotting the prop into a ref and then wiping it in `onMounted`, and watching only truthy values so `false` is treated as "no new value". Together they produce a component that only half-participates in Vue's one-way data flow.

The fix is a consistent pattern: declare the prop, watch it for all legal values, and emit only on user interaction. The piece also provides a regex scanner that checks a component directory for these defects, a four-case test matrix that includes initial value, external writes, internal actions, and reset, and a comparison with the `defineModel` macro, which removes boilerplate but does not solve the watch logic. Version 0.2.29 ships the corrected `ClickCaptcha` and `SliderCaptcha` components with three new unit tests that pass after adding `await nextTick()`.

Takeaways
— v-model compiles to a `:model-value` prop plus an `@update:model-value` event; a component that only emits is uncontrolled from the parent's perspective.
— Three anti-patterns cause fake sync: no prop declaration, mount-time reset of the copied prop, and watch handlers that ignore falsy values.
— The fix requires three constraints: declare the prop, watch all legal values including `false`/`0`/`''`, and never emit from inside the watch; keep `resetVisual()` separate from `reset()`.
— A regex scan over 97 components found 5 candidates: 2 real bugs (ClickCaptcha missing prop, SliderCaptcha missing watch) and 3 false positives.
— Unit tests must `await nextTick()` before asserting DOM; the original test passed because it read pre-nextTick DOM.
— The correct test matrix has four cases: initial value, external writes via `setProps`, internal actions, and reset.
— `defineModel` reduces boilerplate but does not enforce watch semantics; the same rules apply.
— A 30-second experiment: mount the component, click buttons that set the parent value to true and false, and check if the component follows.
Conclusions

The bug is invisible in the default case because the initial value matches the component's internal state; it only appears after the first reset, which is why so many components ship with it.

Vue's type system and IDE don't catch a missing prop because emit alone makes the v-model contract syntactically valid; the failure is runtime-only.

The `nextTick` timing in the test is the real trap: the original assertion ran before the queue flushed, so it read stale DOM and gave a false green.

`defineModel` is often sold as a replacement for manual wiring, but it's just syntactic sugar; the watch logic that actually enforces controlled behavior is not generated.

Concepts & terms
v-model
Vue's syntactic sugar for a pair of `modelValue` prop and `update:modelValue` event, allowing a parent to pass a value down and receive changes back.
Controlled component
A component whose displayed state is fully derived from its props; in Vue this means it reads `modelValue` and emits on user action, so the parent's value is the single source of truth.
defineModel
A Vue 3.4+ macro that declares a `modelValue` prop and its update event in one line, reducing boilerplate but leaving watch semantics to the developer.
nextTick
A Vue API that resolves after the next DOM update; assertions without awaiting it can read stale DOM.
From the discussion
Featured comments
组合搭配函数

The third fake sync is the easiest to fall for. When writing if(value) in a watch, you think you're syncing only when there's a new value, but false, 0, and empty strings all get treated as no new value — and form resets just happen to set the value to false. Also the unit test part resonates a lot: asserting before nextTick reads the old DOM and still sees green, and that fake green is scarier than red. I'd like to ask: after you hook the scanning script into CI, the three false positives Dialog, Drawer, MessageBox — are they suppressed with a comment whitelist? If new components later have similar if/else branches, will you have to keep adding whitelist entries one by one?

ruanno_top

It's not actually hooked into CI yet — the script in the article is a template for everyone to adapt. The three false positives came from the regex only seeing if (value) without the else that follows; temporarily we whitelist by 'component name + rule name'. A new component hitting the same rule will first raise an alert and then get manual confirmation. Next step is to switch to @vue/compiler-sfc to parse the watch callback, which can distinguish between 'only handling truthy' and 'full if/else coverage', so there's no need to keep adding whitelist entries.

组合搭配函数  → ruanno_top

I accept that it's not actually hooked into CI yet — a template script and a CI gate are two different things, and getting it running before tightening is right. But I don't think the 'component + rule' whitelist can hold up for long — with more new components, the whitelist only grows longer and eventually no one dares to touch it. Switching to @vue/compiler-sfc to parse the watch callback and distinguishing 'truthy-only' from 'full if/else coverage' is the real solution. After that, the whitelist should only keep historical legacy and never admit new entries. Are you planning to implement the parsing first, or set up the whitelist's expiry mechanism first?

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗