Reactivity API（响应式与调度）
本页按「一个 API 一个小节」组织，结构参考 Vue 官方 API 文档。每个小节都包含用途、类型入口与使用建议，便于快速定位与深入阅读。
状态创建与派生
ref()
类型签名： typeof import('wevu')['ref']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
Ref<T> - 用途：创建最常用的基础响应式引用，适合原始值或独立状态。
- 说明：读取使用
ref.value；在模板中会自动解包。
customRef()
类型签名： typeof import('wevu')['customRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
CustomRefFactory<T>/CustomRefOptions<T> - 用途：自定义
track/trigger行为。 - 说明：适合防抖输入、手动控制触发时机等高级场景。
reactive()
类型签名： typeof import('wevu')['reactive']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
object - 用途：创建深层响应式对象，适合聚合状态。
- 说明：对嵌套对象也会做代理；适合表单、复杂页面状态。
shallowRef()
类型签名： typeof import('wevu')['shallowRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
ShallowRef<T> - 用途：只追踪
.value本身是否变更，不做深层代理。 - 说明：用于大对象/第三方实例，减少深层响应式开销。
shallowReactive()
类型签名： typeof import('wevu')['shallowReactive']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
object - 用途：仅顶层属性响应式，内部对象保持原值。
- 说明：常用于“只关心顶层替换”的场景。
readonly()
类型签名： typeof import('wevu')['readonly']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
Readonly<T> - 用途：创建只读代理，防止误修改。
- 说明：常用于向下游暴露状态快照。
shallowReadonly()
类型签名： typeof import('wevu')['shallowReadonly']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
Readonly<T> - 用途：创建浅层只读代理。
- 说明：仅保护顶层字段；嵌套对象仍保持原始语义。
computed()
类型签名： typeof import('wevu')['computed']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
ComputedRef<T>/WritableComputedRef<T> - 用途：声明派生状态，自动缓存并按依赖更新。
- 说明：支持只读与可写两种形式；优先用于“纯函数派生”。
本组示例
组合深层状态、独立 Ref 和派生值时，只把可序列化数据交给模板。
<script setup lang="ts">
import { computed, reactive, readonly, ref, shallowRef } from 'wevu'
const count = ref(0)
const form = reactive({ price: 20, quantity: 1 })
const sdk = shallowRef<{ refresh: () => void }>()
const total = computed(() => form.price * form.quantity)
const publicForm = readonly(form)
</script>监听与副作用
watch()
类型签名： typeof import('wevu')['watch']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
WatchOptions/WatchStopHandle - 用途：侦听 source 变化并执行回调。
- 说明：适合精确观察某个字段、computed 或 getter。
watchEffect()
类型签名： typeof import('wevu')['watchEffect']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
WatchStopHandle - 用途：自动收集依赖并立即执行副作用。
- 说明：适合快速联动逻辑与调试输出。
watchPostEffect()
类型签名： typeof import('wevu')['watchPostEffect']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
WatchStopHandle - 用途：以 post flush 语义注册自动依赖副作用。
- 说明：用于希望等待当前更新批次之后再执行的副作用；业务侧仍要避免在高频页面滚动里写重逻辑。
watchSyncEffect()
类型签名： typeof import('wevu')['watchSyncEffect']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
WatchStopHandle - 用途：以 sync flush 语义注册自动依赖副作用。
- 说明：适合极少数需要同步响应状态变化的组合式工具；普通业务优先使用
watchEffect()。
effect()
类型签名： typeof import('wevu')['effect']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
WatchStopHandle - 用途：底层副作用 API，通常框架层/高级场景使用。
- 说明：业务代码优先使用
watchEffect。
effectScope()
类型签名： typeof import('wevu')['effectScope']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
EffectScope - 用途：把一组 effect/watch 放在同一作用域统一管理。
- 说明：在组件外组合逻辑、插件场景很有用。
getCurrentScope()
类型签名： typeof import('wevu')['getCurrentScope']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
EffectScope | undefined - 用途：获取当前激活的 effect scope。
- 说明：常与
onScopeDispose配合使用。
onScopeDispose()
类型签名： typeof import('wevu')['onScopeDispose']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
() => void - 用途：在 scope 销毁时执行清理逻辑。
- 说明：适合解绑事件、释放资源。
stop()
类型签名： typeof import('wevu')['stop']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
void - 用途：停止指定 effect/watch。
- 说明：用于手动中断监听链路。
本组示例
把相关监听放进同一 scope，可以在页面卸载或业务结束时统一停止。
import { effectScope, onScopeDispose, ref, watch, watchEffect } from 'wevu'
const count = ref(0)
const scope = effectScope()
scope.run(() => {
const stopWatch = watch(count, value => console.log(value))
watchEffect(() => documentTitle(count.value))
onScopeDispose(stopWatch)
})
scope.stop()Ref / Proxy 工具
toRef()
类型签名： typeof import('wevu')['toRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
Ref<T> - 用途：把对象某个属性映射为 ref。
- 说明：常用于解构后保持响应式引用。
toRefs()
类型签名： typeof import('wevu')['toRefs']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
ToRefs<T> - 用途：批量把对象属性转换为 ref。
- 说明：适合从
reactive安全解构。
unref()
类型签名： typeof import('wevu')['unref']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
T - 用途：统一读取
ref.value或普通值。 - 说明：减少“值/Ref 双形态”判断分支。
toValue()
类型签名： typeof import('wevu')['toValue']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
MaybeRefOrGetter<T> - 用途：统一展开普通值、Ref 或 getter。
- 说明：编写可复用工具函数时很常见。
triggerRef()
类型签名： typeof import('wevu')['triggerRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
void - 用途：手动触发
shallowRef依赖更新。 - 说明：用于“对象内部变更但引用未变”场景。
toRaw()
类型签名： typeof import('wevu')['toRaw']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
T - 用途：拿到代理前的原始对象。
- 说明：调试或与第三方库交互时使用。
markRaw()
类型签名： typeof import('wevu')['markRaw']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
T - 用途：标记对象跳过响应式代理。
- 说明：适用于大型类实例、SDK 对象。
本组示例
工具函数让组合式函数同时接受普通值、Ref 或 getter。
import { reactive, shallowRef, toRaw, toRef, toRefs, toValue, triggerRef } from 'wevu'
const state = reactive({ count: 0, name: 'Ada' })
const count = toRef(state, 'count')
const fields = toRefs(state)
const config = shallowRef({ enabled: true })
config.value.enabled = false
triggerRef(config)
console.log(toValue(count), fields.name.value, toRaw(state))响应式判定
isRef()
类型签名： typeof import('wevu')['isRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：type predicate
- 用途：判断某值是否为 Ref。
isReactive()
类型签名： typeof import('wevu')['isReactive']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：type predicate
- 用途：判断对象是否是
reactive代理。
isShallowRef()
类型签名： typeof import('wevu')['isShallowRef']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：type predicate
- 用途：判断是否为
shallowRef。
isShallowReactive()
类型签名： typeof import('wevu')['isShallowReactive']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：type predicate
- 用途：判断是否为
shallowReactive。
isRaw()
类型签名： typeof import('wevu')['isRaw']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
boolean - 用途：判断对象是否被
markRaw标记。
isReadonly()
类型签名： typeof import('wevu')['isReadonly']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
boolean - 用途：判断值是否来自
readonly()或shallowReadonly()。
isProxy()
类型签名： typeof import('wevu')['isProxy']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
boolean - 用途：判断值是否为 Wevu 响应式/只读代理。
本组示例
判定函数适合库边界和调试，不应代替清晰的数据建模。
import { isProxy, isRaw, isReactive, isReadonly, isRef, markRaw, reactive, readonly, ref } from 'wevu'
const count = ref(0)
const state = reactive({ count: 0 })
const locked = readonly(state)
const sdk = markRaw({ version: 1 })
console.log(isRef(count), isReactive(state), isReadonly(locked))
console.log(isProxy(state), isRaw(sdk))批处理与调度
nextTick()
类型签名： typeof import('wevu')['nextTick']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
Promise<void> - 用途：等待当前批次响应式更新完成。
- 说明：常用于更新后读取最新渲染状态。
batch()
类型签名： typeof import('wevu')['batch']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
() => void - 用途：在同一批处理中执行一组状态改动。
- 说明：减少中间态触发的无效计算与更新。
startBatch()
类型签名： typeof import('wevu')['startBatch']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
void - 用途：手动开启批处理。
- 说明：需要与
endBatch成对调用。
endBatch()
类型签名： typeof import('wevu')['endBatch']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
void - 用途：手动结束批处理并触发提交。
traverse()
类型签名： typeof import('wevu')['traverse']
运行时说明： 依赖变化进入 Wevu 调度队列，并最终收敛为小程序 setData 更新；模板状态必须保持可序列化。
示例： 见 本组示例。
- 类型入口：
unknown - 用途：显式遍历响应式值及其嵌套成员，建立深层依赖。
- 说明：主要用于组合式工具和调试能力；普通业务的深层监听优先使用
watch()的deep选项。
本组示例
业务代码优先使用 batch()；手动批处理必须用 finally 保证配对结束。
import { batch, endBatch, nextTick, ref, startBatch } from 'wevu'
const count = ref(0)
batch(() => {
count.value += 1
count.value += 1
})
await nextTick()
startBatch()
try {
count.value += 1
}
finally {
endBatch()
}内部能力说明
响应式内部调度与调试函数（如 reactive 树预链接、深度策略切换）属于框架内部能力，文档页不再展开展示。若你在业务侧需要类似能力，建议优先使用本页已列出的公开 API 组合实现。