Vue toRefs 与 toRef：在组合式 API 中解构响应式对象-Vue.js-PHP中文网

直接解构 reactive 对象会丢失响应性，需用 toref（单个属性）或 torefs（批量属性）建立引用通道以保持双向同步；ref() 用于创建独立响应式值，三者不可混淆。

vue torefs 与 toref：在组合式 api 中解构响应式对象

直接解构 reactive 对象会丢失响应性，因为解构出来的只是普通值，和源对象不再关联。要安全解构，就得靠 toRef 和 toRefs —— 它们不是复制数据，而是建立“引用通道”，让变量改值时能同步更新源对象、触发视图刷新。

toRefs：批量转成 ref，适合整体解构

当你有一整个响应式对象，并希望在模板或逻辑中自由解构多个属性时，toRefs 是首选。

它把 reactive 对象的每个可枚举属性都转成一个独立的 ref，返回一个普通对象
解构后的变量仍是响应式引用，修改 name.value 或赋新值给 name（在 script setup 中支持自动解包）都会同步到源对象
常用于组合式函数（Composable）的返回值，方便消费者组件解构使用而不掉响应性

示例：

Ainative Vue Sdk

使用 `@ainative/vue-sdk` 为 Vue 3 应用添加 AI 聊天功能。适用于以下场景：(1) 安装 `@ainative/vue-sdk`，(2) 在 Vue 组件中使用 `useChat` 组合式函数，(3) 提供……

下载

import { reactive, toRefs } from 'vue'
const state = reactive({ name: 'Vue', version: 3 })
const { name, version } = toRefs(state) // ✅ 安全解构
name.value = 'Nuxt' // state.name 同步更新

toRef：按需创建单个 ref，适合处理个别属性

当你只关心响应式对象中的某一个字段，或者该字段可能暂时不存在（比如可选 prop），toRef 更精准灵活。

它不转换整个对象，只针对指定 key 创建一个与源属性双向绑定的 ref
即使 state.foo 当前为 undefined，toRef(state, 'foo') 仍会返回一个可用的 ref
特别适合封装可复用逻辑时接收 props 的某个字段，避免因 prop 缺失报错

示例：

const props = defineProps({ title: String })
// 即使 title 是可选的，也能安全创建 ref
const titleRef = toRef(props, 'title')

别混淆：ref() vs toRef() vs toRefs()

三者用途完全不同，混用容易出错：

ref(value)：从零创建一个响应式基础值，适用于独立变量
toRef(obj, key)：从已有响应式对象中“借出”一个属性的响应式引用
toRefs(obj)：对整个响应式对象执行 toRef，批量生成所有属性的 ref

注意：toRefs 只处理对象上当前存在的、可枚举的属性；若需支持动态或可选字段，优先选 toRef。

常见误区提醒

这些操作看似相似，但结果差异很大：

❌ const { count } = reactive({ count: 0 }) → count 是普通数字，改它不会更新视图
❌ const count = ref(state.count) → 创建的是快照副本，和 state.count 无关联
✅ const count = toRef(state, 'count') → 双向同步，改 count.value 就等于改 state.count

响应性不是自动继承的，解构是“断连操作”，必须显式用 toRef 或 toRefs 恢复连接。