将对象的属性转换为响应式引用，或包装一个值为 ref。

类型定义

declare function toRef<T extends object, K extends keyof T>(
  object: T,
  key: K,
  defaultValue?: T[K]
): PropertyRef<T, K>
declare function toRef<T extends Ref<any>>(value: T): T
declare function toRef<T>(value: T): Ref<T>
declare function toRef<T>(getter: () => T): GetterRef<T>

参数

参数	类型	说明
`object`	`T`	源对象
`key`	`keyof T`	对象属性名
`defaultValue`	`T[K]`	可选的默认值

返回值

调用方式	返回值	说明
`toRef(obj, key)`	`PropertyRef`	与源对象属性双向同步的 ref
`toRef(ref)`	`Ref`	如果已是 ref 则原样返回
`toRef(value)`	`Ref`	将值包装为 ref
`toRef(getter)`	`GetterRef`	只读的 getter ref

示例

import { reactive, toRef } from 'vitarx'

const state = reactive({ name: 'Vitarx' })
const nameRef = toRef(state, 'name')

nameRef.value = 'New Name' // 同步更新 state.name
state.name = 'Another' // 同步更新 nameRef.value

toRefs()

将响应式对象的所有属性转换为 ref。

类型定义

declare function toRefs<T extends object>(
  obj: T,
  skipWarn?: boolean
): { [K in keyof T]: ToRef<T[K]> }

参数

参数	类型	说明
`obj`	`T extends object`	响应式对象
`skipWarn`	`boolean`	是否跳过非响应式属性警告

返回值

类型	说明
`{ [K in keyof T]: ToRef<T[K]> }`	属性均为 ref 的普通对象

示例

import { reactive, toRefs } from 'vitarx'

const state = reactive({ count: 0, name: 'Vitarx' })
const { count, name } = toRefs(state)

toValue()

获取 ref 的值，如果不是 ref 则直接返回。支持 getter 函数。

类型定义

declare function toValue<T>(source: T | Ref<T> | (() => T)): T

参数

参数	类型	说明
`source`	`T \| Ref<T> \| (() => T)`	可能是 ref、getter 或普通值

返回值

类型	说明
`T`	ref 的值、getter 的返回值或原值

示例

import { ref, toValue } from 'vitarx'

toValue(ref(0)) // 0
toValue(() => 10) // 10
toValue(10) // 10

unref()

toValue() 的别名。

类型定义

declare function unref<T>(ref: Ref<T> | T): T

toRaw()

获取响应式对象的原始对象。

类型定义

declare function toRaw<T extends object>(wrap: T | RawValue<T>): T

参数

参数	类型	说明
`wrap`	`T \| RawValue<T>`	响应式代理对象

返回值

类型	说明
`T`	原始对象

示例

import { reactive, toRaw } from 'vitarx'

const state = reactive({ count: 0 })
const raw = toRaw(state)
raw.count++ // 不会触发更新

markRaw()

标记一个对象为"永远不会被响应式化"。

类型定义

declare function markRaw<T extends object>(obj: T): RawObject<T>

参数

参数	类型	说明
`obj`	`T extends object`	要标记的对象

返回值

类型	说明
`RawObject<T>`	标记后的对象（与原对象相同引用）

示例

import { markRaw, reactive } from 'vitarx'

const rawObject = markRaw({ config: {} })
const state = reactive({ data: rawObject })
state.data === rawObject // true，未被代理

列表同步

syncList()

新增于 4.1.0 版本

将新列表数据按 key 对齐回写进既有响应式数组，实现元素级精确更新。它是 For 列表更新模型中「原地修改」通道的自动化工具——尤其适合把服务端返回的全量新数据消化进既有列表，而无需替换数组引用。

同步规则：

同 key 的行：复用既有对象引用（保持行 DOM 与行内状态），并将新数据浅层回写——值变化的属性触发精确更新，值未变的属性零触发
新 key 的行：直接采用源对象
消失 key 的行：从目标数组中移除
顺序：对齐源列表（配合 For 的 key 复用，重排转为 DOM 移动而非重建）

类型定义

type SyncKey<T> = keyof T | ((item: T) => unknown)

declare function syncList<T>(
  target: T[],
  source: readonly T[],
  key: SyncKey<T>
): void

参数

参数	类型	说明
`target`	`T[]`	既有响应式数组（须为深度响应式：`reactive([])` 或深 ref）
`source`	`readonly T[]`	新列表数据（原始对象即可，无需响应式）
`key`	`SyncKey<T>`	列表项唯一标识，属性名或函数（语义同 `For` 的 key，须唯一）

示例

import { ref, syncList } from 'vitarx'

// 深响应式数组作为列表数据源
const users = ref([
  { id: 1, name: '张三', age: 25 },
  { id: 2, name: '李四', age: 30 }
])

async function refresh() {
  // 服务端返回全量新数据（全新对象引用）
  const fresh = await fetchUsers()
  // 不替换数组引用，回写进既有结构：
  // 同 id 行内容自动更新（元素级），新增行插入，消失行移除
  syncList(users.value, fresh, 'id')
}

syncList 全程无 diff 计算：属性写入依赖信号系统的值去重，只有真正变化的属性产生更新。若 target 不是响应式数组，开发模式会输出警告（写入不会触发视图更新）。

参考：列表渲染 — 数据更新模型

类型判断

isRef()

检查值是否为 ref。

类型定义

declare function isRef(val: any): val is Ref

示例

isRef(ref(0)) // true
isRef(0) // false

isReactive()

检查对象是否为 reactive 创建的响应式代理。

类型定义

declare function isReactive(val: any): val is Reactive | ShallowReactive

示例

isReactive(reactive({})) // true
isReactive({}) // false

isReadonly()

检查对象是否为 readonly 创建的只读代理。

类型定义

declare function isReadonly(obj: any): boolean

示例

isReadonly(readonly({})) // true
isReadonly({}) // false

isComputed()

检查值是否为 computed 创建的计算属性。

类型定义

declare function isComputed(val: unknown): val is Computed<any>

示例

const double = computed(() => count.value * 2)
isComputed(double) // true
isComputed(ref(0)) // false

其他工具

untrack()

已于 4.0.5 版本弃用，改名为 untracked

执行一个函数而不追踪响应式依赖。

类型定义

declare function untrack<T>(fn: () => T): T

参数

参数	类型	说明
`fn`	`() => T`	要执行的函数

返回值

类型	说明
`T`	函数的返回值

示例

import { ref, computed, untrack } from 'vitarx'

const count = ref(0)
const double = computed(() => {
  return untrack(() => count.value) * 2 // 读取但不建立依赖
})
double.value // 0
count.value++
double.value // 0（未更新，因为未建立依赖）

INFO