人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载watchOnce是 VueUse 为 Vue 官方watch的{ once: true }选项提供的简写封装监听器回调最多触发一次触发后自动停止监听。本文以 airi 仓库 .agents/skills/vueuse-functions 技能体系中的 watchOnce 参考文档 为主体结合仓库内 VueUse 的实际使用证据讲透它的类型签名、可选参数、与watchImmediate、until等 Watch 家族成员的关系以及一次性初始化、首跳状态等待等典型实战场景。读完你将能正确选用并落地 once watcher避免监听器永远不清理这类常见内存隐患。什么是 watchOnceVue 官方 once watcher 的 VueUse 封装在 Vue 3.4 中官方watch新增了once选项回调执行一次后监听器会被自动销毁。VueUse 的watchOnce就是这一选项的语法糖文档对其的定义是Shorthand for watching value with{ once: true }. Once the callback fires once, the watcher will be stopped.即它内部等价于watch(source, cb, { once: true })回调一旦触发监听即被停止。在 airi 的技能体系里watchOnce属于 SKILL.md 中Watch分类与until、watchImmediate、watchDebounced、watchDeep、watchPausable、whenever等同属一族其调用策略为AUTO只要适用即可自动选用并优先使用 VueUse 组合式函数而非手写一次性监听逻辑以保持代码简洁、可维护且性能良好。基础用法与 watch 同构的单次监听watchOnce的调用方式与watch几乎完全一致区别只在于不需要也不能再传once选项import { watchOnce } from vueuse/core watchOnce(source, () { // triggers only once console.log(source changed!) })当source首次发生变化时回调执行一次并打印source changed!随后该 watcher 立即停止——之后无论source再变化多少次回调都不会再次触发。它同样支持数组形式的多个数据源。此时任一数据源首次变化回调即触发一次watchOnce([volume, enabled], () { // 只会在 volume 或 enabled 任一首次变化时触发一次 console.log(first change detected) })类型声明逐行解读三个重载与 Omit 语义参考文档给出的完整类型声明如下继承自 VueUse 官方类型export declare function watchOnceT( source: WatchSourceT, cb: WatchCallbackT, T | undefined, options?: OmitWatchOptionstrue, once, ): WatchHandle export declare function watchOnceT extends ReadonlyMultiWatchSources( source: [...T], cb: WatchCallbackMapSourcesT, MapOldSourcesT, true, options?: OmitWatchOptionstrue, once, ): WatchHandle export declare function watchOnceT extends object( source: T, cb: WatchCallbackT, T | undefined, options?: OmitWatchOptionstrue, once, ): WatchHandle三个重载分别对应watch支持的三类数据源形态重载source 形态回调参数典型场景第 1 个单个WatchSourceTref / getter / 响应式对象属性新值与旧值T \| undefined监听单个状态变量的首次变化第 2 个元组[...T]ReadonlyMultiWatchSources只读多数据源MapSourcesT新值数组、MapOldSourcesT, true旧值数组任一数据源首次变化即触发第 3 个对象T extends object如 reactive 对象整个对象的新值与旧值监听响应式对象的首次变化关键点在于options?: OmitWatchOptionstrue, onceonce已被 Omit 移除——你无法也不需要重复指定once因为watchOnce内部已固定为true。Omit保证了其余所有watch选项仍然开放这正是它与手写watch(source, cb, { once: true })完全等价的类型层证明。可选参数详解除 once 之外仍可用的 watch 选项由于once被内部锁定你仍然可以通过options控制其余WatchOptions对应 Vue 官方watch选项immediate: boolean默认false设为true时回调会立即执行一次。在 once watcher 语义下立即执行的那一次同样计入触发一次因此回调依然最多只跑一次随后监听器停止。适合挂载后立刻执行一次初始化且此后不再响应变化的场合。deep: boolean默认false深度监听。对深层嵌套的响应式对象/数组需要显式开启watchOnce的第二个重载在回调类型层面直接使用了WatchOptionstrue便于配合深层源做类型推导。flush: pre | post | sync默认pre控制回调刷新时机。默认在组件更新前排队执行post在组件更新后执行适合读取更新后的 DOMsync在依赖变化时同步立即执行。onTrack/onTrigger调试依赖追踪用与watch行为一致。组合示例——只在首次从无状态变为有数据时做一次后置处理watchOnce(payload, (value) { // 仅一次拿到首个数据后渲染一次并停止 renderOnce(value) }, { flush: post, })返回值 WatchHandle自动清理与手动停止三个重载统一返回WatchHandle即 Vue 标准 watcher 句柄其上带有stop()方法。由于watchOnce在回调触发后会自动stop()绝大多数情况下你无需手动清理这正是它防止监听器泄漏的核心价值。若在某些提前退出分支里想主动终止尚未触发的监听可安全调用handle.stop()const stop watchOnce(token, () { flashNotice() }) // 若组件提前销毁或条件提前满足可手动终止 stop()适用场景与典型用例在 airi 这类以实时交互语音输入、聊天流、桌面悬浮窗、Live2D 舞台为核心的应用中once watcher 的典型落地场景包括一次性初始化某个状态从空变为首次有值时只做一次启动逻辑如首次建立会话时初始化上下文。等待首个可用数据数据源首次就绪后立即消费一次之后交由常规watch接管。事件型 ref 的首跳处理把某个内部以 ref 形式暴露的一次性事件消费掉避免留下残留监听导致重复副作用。守卫型副作用某些副作用只允许发生一次如首次错误上报、首次引导提示用watchOnce从语义上杜绝重复执行。需要留意的是watchOnce与until的定位不同——前者是回调式的一次性监听后者是Promise 式的一次性等待详见下文。若你的逻辑天然是await形态例如先等一个条件成立再继续往下走until往往更合适而watchOnce更贴合触发一次副作用即可的命令式写法。Watch 家族对照watchImmediate / watchDeep / whenever / untilwatchOnce并非孤立函数它是 VueUse Watch 分类中的一员。理解它与近邻函数的差异能避免选错工具函数语义与 watchOnce 的区别watchOnceonce: true触发一次后自动停止watchImmediateimmediate: true立即执行但不停止后续继续监听参考 watchImmediate.mdwatchDeepdeep: true仅深度监听不涉及一次性语义watchDebounced/watchThrottled防抖 / 节流控制触发频率不自动停止watchPausable/watchIgnorable可暂停 / 可忽略提供手动控制默认持续监听whenever值为真值才触发条件触发但持续监听不自动停止untilPromise 化的一次性等待同样是一次性但以 Promise 方式表达条件等待参考 until.md特别值得对照的是watchImmediate它同样省略了immediate选项类型为OmitWatchOptionstrue, immediate但语义相反——回调会立即执行且持续监听。在参考文档的示例中watchImmediate(obj, cb)会因外部赋值 立即执行打印两次日志而watchOnce无论是否加immediate都至多执行一次。两者一个管起始时机一个管结束条件可组合使用。until则是 Promise 化的 one-time watch。参考文档展示了三种典型用法等待异步数据就绪await until(isReady).toBe(true)、等待自定义条件await until(count).toMatch(v v 7)、以及带超时保护await until(ref).toBe(true, { timeout: 1000, throwOnTimeout: true })。此外还提供toBeTruthy、toBeNull、toBeUndefined、changed()、changedTimes(n)以及.not取反链式 API。在 airi 仓库中的实际使用证据airi 的整个 Vue 应用栈Web / Electron / Pocket 等多端统一通过 pnpm workspace 的 catalog 管理 VueUse 版本见 pnpm-workspace.yamlvueuse/core: ^14.4.0虽然从仓库源码检索来看业务代码中暂未直接出现watchOnce的调用该技能将其标为AUTO即按需自动选用但同属 Watch 分类的工具已被广泛采用可作为选用watchOnce的直接佐证performance-visualizer.vue 组合使用useMagicKeys与whenever用快捷键一次性/持续性地切换性能可视化开关import { useMagicKeys, whenever } from vueuse/core const magicKeys useMagicKeys() whenever(magicKeys[ctrlaltl], () lagStore.toggleAll(true)) whenever(magicKeys[ctrlaltk], () lagStore.toggleAll(false))audio-record.ts 用 Promise 化的until等待媒体流就绪后再创建MediaRecorderasync function startRecord() { await start() await until(mediaRef).toBeTruthy() // ... audioRecorder.value new MediaRecorder(mediaRef.value) }InteractiveArea.vue 用until(...).toBe(0)等待挂起图片队列清空并用until(activeSessionId).toMatch(Boolean, { timeout: 5000 })带超时地等待会话激活——这正是在真实交互场景里一次性等待条件成立的标准写法。chat-bubble-minimalism.vue 同样用until等待气泡容器 ref 挂载后再执行后续定位逻辑。这些证据说明在 airi 的代码实践中等待某个状态首次满足既可以用回调式的watchOnce也可以用 Promise 式的until。选择原则很简单——后续逻辑是执行一次副作用并结束选watchOnce后续逻辑是异步流程的中间等待选until。注意事项与最佳实践不要重复传once类型层面once已被Omit传了反而报错一次性语义由函数名与内部实现保证。immediate与一次性的关系加了immediate: true立即执行也算作唯一一次触发回调至多执行一次。副作用要幂等且单次watchOnce天然防重入适合引导提示、首次上报、单次初始化若回调本身需要多次响应应改用普通watch或其他家族成员。与until的取舍回调式选watchOnceawait流程选until需要超时保护时用until的{ timeout, throwOnTimeout }默认 0 表示永不超时。组件销毁安全回调触发后 watcher 自毁不会产生跨组件残留即便未触发也建议在组件卸载路径调用stop()兜底或用tryOnUnmounted包裹。在技能体系中的定位airi 的 SKILL.md 明确要求先检查 VueUse 是否能实现需求优先组合式函数而非自造代码。watchOnce正是把手动watch 手动stop() 触发标记这段样板代码压缩为一行声明式调用的最佳替代品。小结watchOnce用极简的 API 把 Vue 3.4 的oncewatcher 语义带到了 VueUse 生态回调触发一次即自动停止类型签名与watch完全同构三个重载覆盖单源、多源元组与对象源OmitWatchOptionstrue, once在类型层锁死了一次性语义同时保留immediate、deep、flush等全部扩展选项。在 airi 这样的多端 Vue 应用中它与until、whenever、watchImmediate等家族成员共同构成Watch 工具箱理解各自的触发时机与停止策略就能用最少的代码写出无泄漏、语义清晰的一次性监听逻辑。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐airi 中的 VueUse watchOnce一次性监听器once watcher的原理、类型签名与工程实践airi 中的 VueUse watchOnce一次性监听器once watcher的原理、类型签名与工程实践 本篇技术指南围绕 airi 仓库中 .ag人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务VueUse watchOnce 详解只触发一次的单次监听器从用法到源码实现VueUse watchOnce 详解只触发一次的单次监听器从用法到源码实现 VueUse 的 watchOnce 是 Vue 3 watch 的一个简洁封前端深入解析 VueUse useMutationObserver在 Airi 中响应式监听 DOM 变化的工程实践深入解析 VueUse useMutationObserver在 Airi 中响应式监听 DOM 变化的工程实践 useMutationObserver 是人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务上一篇终极解决TranslucentTB任务栏透明工具依赖问题完整指南下一篇TranslucentTB完全指南Windows任务栏透明化终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/16 2:09:24 · 阅读 1.2k VueUse watchOnce 深入实践：airi 项目中的一次性监听器（once watcher）详解
人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载watchOnce是 VueUse 为 Vue 官方watch的{ once: true }选项提供的简写封装监听器回调最多触发一次触发后自动停止监听。本文以 airi 仓库 .agents/skills/vueuse-functions 技能体系中的 watchOnce 参考文档 为主体结合仓库内 VueUse 的实际使用证据讲透它的类型签名、可选参数、与watchImmediate、until等 Watch 家族成员的关系以及一次性初始化、首跳状态等待等典型实战场景。读完你将能正确选用并落地 once watcher避免监听器永远不清理这类常见内存隐患。什么是 watchOnceVue 官方 once watcher 的 VueUse 封装在 Vue 3.4 中官方watch新增了once选项回调执行一次后监听器会被自动销毁。VueUse 的watchOnce就是这一选项的语法糖文档对其的定义是Shorthand for watching value with{ once: true }. Once the callback fires once, the watcher will be stopped.即它内部等价于watch(source, cb, { once: true })回调一旦触发监听即被停止。在 airi 的技能体系里watchOnce属于 SKILL.md 中Watch分类与until、watchImmediate、watchDebounced、watchDeep、watchPausable、whenever等同属一族其调用策略为AUTO只要适用即可自动选用并优先使用 VueUse 组合式函数而非手写一次性监听逻辑以保持代码简洁、可维护且性能良好。基础用法与 watch 同构的单次监听watchOnce的调用方式与watch几乎完全一致区别只在于不需要也不能再传once选项import { watchOnce } from vueuse/core watchOnce(source, () { // triggers only once console.log(source changed!) })当source首次发生变化时回调执行一次并打印source changed!随后该 watcher 立即停止——之后无论source再变化多少次回调都不会再次触发。它同样支持数组形式的多个数据源。此时任一数据源首次变化回调即触发一次watchOnce([volume, enabled], () { // 只会在 volume 或 enabled 任一首次变化时触发一次 console.log(first change detected) })类型声明逐行解读三个重载与 Omit 语义参考文档给出的完整类型声明如下继承自 VueUse 官方类型export declare function watchOnceT( source: WatchSourceT, cb: WatchCallbackT, T | undefined, options?: OmitWatchOptionstrue, once, ): WatchHandle export declare function watchOnceT extends ReadonlyMultiWatchSources( source: [...T], cb: WatchCallbackMapSourcesT, MapOldSourcesT, true, options?: OmitWatchOptionstrue, once, ): WatchHandle export declare function watchOnceT extends object( source: T, cb: WatchCallbackT, T | undefined, options?: OmitWatchOptionstrue, once, ): WatchHandle三个重载分别对应watch支持的三类数据源形态重载source 形态回调参数典型场景第 1 个单个WatchSourceTref / getter / 响应式对象属性新值与旧值T \| undefined监听单个状态变量的首次变化第 2 个元组[...T]ReadonlyMultiWatchSources只读多数据源MapSourcesT新值数组、MapOldSourcesT, true旧值数组任一数据源首次变化即触发第 3 个对象T extends object如 reactive 对象整个对象的新值与旧值监听响应式对象的首次变化关键点在于options?: OmitWatchOptionstrue, onceonce已被 Omit 移除——你无法也不需要重复指定once因为watchOnce内部已固定为true。Omit保证了其余所有watch选项仍然开放这正是它与手写watch(source, cb, { once: true })完全等价的类型层证明。可选参数详解除 once 之外仍可用的 watch 选项由于once被内部锁定你仍然可以通过options控制其余WatchOptions对应 Vue 官方watch选项immediate: boolean默认false设为true时回调会立即执行一次。在 once watcher 语义下立即执行的那一次同样计入触发一次因此回调依然最多只跑一次随后监听器停止。适合挂载后立刻执行一次初始化且此后不再响应变化的场合。deep: boolean默认false深度监听。对深层嵌套的响应式对象/数组需要显式开启watchOnce的第二个重载在回调类型层面直接使用了WatchOptionstrue便于配合深层源做类型推导。flush: pre | post | sync默认pre控制回调刷新时机。默认在组件更新前排队执行post在组件更新后执行适合读取更新后的 DOMsync在依赖变化时同步立即执行。onTrack/onTrigger调试依赖追踪用与watch行为一致。组合示例——只在首次从无状态变为有数据时做一次后置处理watchOnce(payload, (value) { // 仅一次拿到首个数据后渲染一次并停止 renderOnce(value) }, { flush: post, })返回值 WatchHandle自动清理与手动停止三个重载统一返回WatchHandle即 Vue 标准 watcher 句柄其上带有stop()方法。由于watchOnce在回调触发后会自动stop()绝大多数情况下你无需手动清理这正是它防止监听器泄漏的核心价值。若在某些提前退出分支里想主动终止尚未触发的监听可安全调用handle.stop()const stop watchOnce(token, () { flashNotice() }) // 若组件提前销毁或条件提前满足可手动终止 stop()适用场景与典型用例在 airi 这类以实时交互语音输入、聊天流、桌面悬浮窗、Live2D 舞台为核心的应用中once watcher 的典型落地场景包括一次性初始化某个状态从空变为首次有值时只做一次启动逻辑如首次建立会话时初始化上下文。等待首个可用数据数据源首次就绪后立即消费一次之后交由常规watch接管。事件型 ref 的首跳处理把某个内部以 ref 形式暴露的一次性事件消费掉避免留下残留监听导致重复副作用。守卫型副作用某些副作用只允许发生一次如首次错误上报、首次引导提示用watchOnce从语义上杜绝重复执行。需要留意的是watchOnce与until的定位不同——前者是回调式的一次性监听后者是Promise 式的一次性等待详见下文。若你的逻辑天然是await形态例如先等一个条件成立再继续往下走until往往更合适而watchOnce更贴合触发一次副作用即可的命令式写法。Watch 家族对照watchImmediate / watchDeep / whenever / untilwatchOnce并非孤立函数它是 VueUse Watch 分类中的一员。理解它与近邻函数的差异能避免选错工具函数语义与 watchOnce 的区别watchOnceonce: true触发一次后自动停止watchImmediateimmediate: true立即执行但不停止后续继续监听参考 watchImmediate.mdwatchDeepdeep: true仅深度监听不涉及一次性语义watchDebounced/watchThrottled防抖 / 节流控制触发频率不自动停止watchPausable/watchIgnorable可暂停 / 可忽略提供手动控制默认持续监听whenever值为真值才触发条件触发但持续监听不自动停止untilPromise 化的一次性等待同样是一次性但以 Promise 方式表达条件等待参考 until.md特别值得对照的是watchImmediate它同样省略了immediate选项类型为OmitWatchOptionstrue, immediate但语义相反——回调会立即执行且持续监听。在参考文档的示例中watchImmediate(obj, cb)会因外部赋值 立即执行打印两次日志而watchOnce无论是否加immediate都至多执行一次。两者一个管起始时机一个管结束条件可组合使用。until则是 Promise 化的 one-time watch。参考文档展示了三种典型用法等待异步数据就绪await until(isReady).toBe(true)、等待自定义条件await until(count).toMatch(v v 7)、以及带超时保护await until(ref).toBe(true, { timeout: 1000, throwOnTimeout: true })。此外还提供toBeTruthy、toBeNull、toBeUndefined、changed()、changedTimes(n)以及.not取反链式 API。在 airi 仓库中的实际使用证据airi 的整个 Vue 应用栈Web / Electron / Pocket 等多端统一通过 pnpm workspace 的 catalog 管理 VueUse 版本见 pnpm-workspace.yamlvueuse/core: ^14.4.0虽然从仓库源码检索来看业务代码中暂未直接出现watchOnce的调用该技能将其标为AUTO即按需自动选用但同属 Watch 分类的工具已被广泛采用可作为选用watchOnce的直接佐证performance-visualizer.vue 组合使用useMagicKeys与whenever用快捷键一次性/持续性地切换性能可视化开关import { useMagicKeys, whenever } from vueuse/core const magicKeys useMagicKeys() whenever(magicKeys[ctrlaltl], () lagStore.toggleAll(true)) whenever(magicKeys[ctrlaltk], () lagStore.toggleAll(false))audio-record.ts 用 Promise 化的until等待媒体流就绪后再创建MediaRecorderasync function startRecord() { await start() await until(mediaRef).toBeTruthy() // ... audioRecorder.value new MediaRecorder(mediaRef.value) }InteractiveArea.vue 用until(...).toBe(0)等待挂起图片队列清空并用until(activeSessionId).toMatch(Boolean, { timeout: 5000 })带超时地等待会话激活——这正是在真实交互场景里一次性等待条件成立的标准写法。chat-bubble-minimalism.vue 同样用until等待气泡容器 ref 挂载后再执行后续定位逻辑。这些证据说明在 airi 的代码实践中等待某个状态首次满足既可以用回调式的watchOnce也可以用 Promise 式的until。选择原则很简单——后续逻辑是执行一次副作用并结束选watchOnce后续逻辑是异步流程的中间等待选until。注意事项与最佳实践不要重复传once类型层面once已被Omit传了反而报错一次性语义由函数名与内部实现保证。immediate与一次性的关系加了immediate: true立即执行也算作唯一一次触发回调至多执行一次。副作用要幂等且单次watchOnce天然防重入适合引导提示、首次上报、单次初始化若回调本身需要多次响应应改用普通watch或其他家族成员。与until的取舍回调式选watchOnceawait流程选until需要超时保护时用until的{ timeout, throwOnTimeout }默认 0 表示永不超时。组件销毁安全回调触发后 watcher 自毁不会产生跨组件残留即便未触发也建议在组件卸载路径调用stop()兜底或用tryOnUnmounted包裹。在技能体系中的定位airi 的 SKILL.md 明确要求先检查 VueUse 是否能实现需求优先组合式函数而非自造代码。watchOnce正是把手动watch 手动stop() 触发标记这段样板代码压缩为一行声明式调用的最佳替代品。小结watchOnce用极简的 API 把 Vue 3.4 的oncewatcher 语义带到了 VueUse 生态回调触发一次即自动停止类型签名与watch完全同构三个重载覆盖单源、多源元组与对象源OmitWatchOptionstrue, once在类型层锁死了一次性语义同时保留immediate、deep、flush等全部扩展选项。在 airi 这样的多端 Vue 应用中它与until、whenever、watchImmediate等家族成员共同构成Watch 工具箱理解各自的触发时机与停止策略就能用最少的代码写出无泄漏、语义清晰的一次性监听逻辑。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐airi 中的 VueUse watchOnce一次性监听器once watcher的原理、类型签名与工程实践airi 中的 VueUse watchOnce一次性监听器once watcher的原理、类型签名与工程实践 本篇技术指南围绕 airi 仓库中 .ag人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务VueUse watchOnce 详解只触发一次的单次监听器从用法到源码实现VueUse watchOnce 详解只触发一次的单次监听器从用法到源码实现 VueUse 的 watchOnce 是 Vue 3 watch 的一个简洁封前端深入解析 VueUse useMutationObserver在 Airi 中响应式监听 DOM 变化的工程实践深入解析 VueUse useMutationObserver在 Airi 中响应式监听 DOM 变化的工程实践 useMutationObserver 是人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务上一篇终极解决TranslucentTB任务栏透明工具依赖问题完整指南下一篇TranslucentTB完全指南Windows任务栏透明化终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考