Vue 3 中 ref 必须通过 .value 访问和修改,基础类型赋值漏掉 .value 会导致响应失效,对象/数组内部变更天然响应但整体替换仍需 .value,模板自动解包而逻辑中不可省略。

Vue 3 中,ref 是响应式数据的基础封装方式,所有修改都必须通过 .value 进行——这不是可选项,而是响应式追踪的必要路径。只要漏掉 .value,赋值就脱离 Vue 的依赖系统,视图不会更新。
基础类型:必须走 .value 赋值
字符串、数字、布尔值等基本类型用 ref 包裹后,读写都需经过 .value:
-
正确:
count.value = 5、loading.value = true、message.value += '!' -
错误:
count = 5(重赋 ref 变量本身,ref 实例被覆盖) -
错误:
const c = count; c.value = 5(虽没报错,但若c是局部解构,后续再改可能丢失上下文,不推荐)
对象/数组类型:.value 是入口,内部变更天然响应
当 ref 包裹的是对象或数组时,.value 指向一个由 reactive 处理过的响应式代理:
-
修改属性:
user.value.name = '李四'、list.value.push(item)—— 触发更新 -
新增字段:
user.value.avatar = 'avatar.png'—— Vue 3 的 Proxy 支持动态添加,无需nextTick或额外操作 -
整体替换:
user.value = { name: '王五', age: 26 }—— 替换整个对象,响应式链保持完整 -
避免断链:
const u = user.value; u.name = '赵六'——u是普通对象引用,修改不触发响应
在模板和组合式 API 中的注意事项
模板中会自动解包 ref,所以 {{ count }} 等价于 {{ count.value }};但在 JavaScript 逻辑中,永远不能省略 .value:
立即学习“前端免费学习笔记(深入)”;
- 计算属性里:
computed(() => user.value?.name || '匿名') - watch 监听:
watch(() => user.value.name, ...)或直接watch(user, ...)(监听整个 ref) - 传参给函数:
api.update(user.value)—— 传的是响应式对象本身,不是 ref - 子组件接收:
defineProps({ user: Object as PropType<ref>> })</ref>,子组件内仍需props.user.value.name
常见误操作与修复提示
这些写法看似合理,实则破坏响应性:
-
user = { name: '新用户' }→ 应改为user.value = { name: '新用户' } -
const { name } = user→ 解构后name是只读常量,无法响应式更新 -
list.value = list.value.filter(...)✅ 正确;list = list.value.filter(...)❌ 错误(ref 被覆盖) - 异步后忘记
.value:await fetchUser().then(data => user = data)→ 必须写成user.value = data


















