customRef() 自定义 ref 的读写行为
最后更新：2026-10-22
customRef() 自定义 ref 的读写行为
customRef() 用工厂函数自定义依赖追踪与触发时机，典型用途是给输入框加防抖。
| 分组 | 响应式·进阶 |
|---|---|
| 类型 | API |
| 作用域 | 组件内 |
| Vue 版本 | 3.0+ |
| SSR 支持 | 支持 |
📝 语法
function useDebounced(value, delay) {
return customRef((track, trigger) => {
let t
return {
get() { track(); return value },
set(v) { clearTimeout(t); t = setTimeout(() => { value = v; trigger() }, delay) }
}
})
}⚙️ 参数
| factory | (track, trigger) => { get, set }，track 收集依赖、trigger 通知更新 |
|---|
返回值：自定义行为的 ref
▶ 示例
修改下面的代码，在预览区实时查看效果：
输出：
快速输入时下方文字延迟 400ms 才跟上——中间过程被防抖合并。💡 要点
⚠️ 注意 必须调用 track() 与 trigger()：漏掉 track 依赖不被收集，漏掉 trigger 更新不触发。
💡 提示 封装成组合式函数（useDebounced）复用，是 customRef 的标准用法。
ℹ️ 说明 适合防抖、节流、带校验的输入模型等自定义同步策略。
🏷️ 相关进阶
💡 相关案例
更多案例即将上线。
📚 相关教程
❓ 常见问题
Q 为什么依赖要手动 track？
A customRef 给了你完全控制权：何时收集依赖、何时通知由你决定，因此必须显式声明。
Q 防抖场景一定要用它吗？
A 不是：也可以用 watch + setTimeout 手动维护一个普通 ref，但 customRef 写法更内聚。
Q 能实现节流吗？
A 能，在 set 里控制首次立刻执行、后续按间隔触发即可。
