庫(kù)中的 VueUse watchWithFilter：給 Vue watch 裝上 eventFilter 事件過濾器)
airi 倉(cāng)庫(kù)中的 VueUse watchWithFilter給 Vue watch 裝上 eventFilter 事件過濾器【免費(fèi)下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ai/airi本文基于 airi 倉(cāng)庫(kù)中維護(hù)的 VueUse 函數(shù)技能文檔 .agents/skills/vueuse-functions/references/watchWithFilter.md完整講解watchWithFilter的用法、eventFilter選項(xiàng)與三組類型聲明并結(jié)合 airi 工作區(qū)的依賴配置與真實(shí)過濾型響應(yīng)式用法說明如何把防抖、節(jié)流等“過濾器”掛到watch回調(diào)上以及它在 airi 這類多端Web / Electron / Capacitor應(yīng)用中的定位。一、watchWithFilter 是什么在 airi 倉(cāng)庫(kù)的 VueUse 技能索引 SKILL.md 中watchWithFilter被歸類于Watch類別其描述為watchwith additional EventFilter control也就是說它是對(duì) Vue 原生watch的增強(qiáng)API 簽名與watch基本一致但額外提供一個(gè)eventFilter選項(xiàng)讓回調(diào)函數(shù)在真正執(zhí)行前經(jīng)過一層“事件過濾器”防抖、節(jié)流、可暫停等。它在索引中的 Invocation 規(guī)則為AUTO——即當(dāng)需求匹配時(shí)可直接采用優(yōu)先于手寫定時(shí)器方案。官方文檔給出的定義一句話概括watchwith additional EventFilter control.二、基本用法完整示例與watch類似但多出一個(gè)eventFilter選項(xiàng)該過濾器會(huì)作用于回調(diào)函數(shù)。倉(cāng)庫(kù)文檔中的完整示例如下import { debounceFilter, watchWithFilter } from vueuse/core watchWithFilter( source, () { console.log(changed!) }, // callback will be called in 500ms debounced manner { eventFilter: debounceFilter(500), // throttledFilter, pausableFilter or custom filters }, )要點(diǎn)拆解第一個(gè)參數(shù)source與普通watch一致可以是 ref、reactive 對(duì)象、getter 或 sources 數(shù)組第二個(gè)參數(shù)watch 回調(diào)這里被包在“500ms 防抖”語(yǔ)義下——source 連續(xù)變化時(shí)只有停止變化 500ms 后回調(diào)才會(huì)執(zhí)行一次第三個(gè)參數(shù)options繼承自watch的選項(xiàng)immediate、deep、flush等并額外支持eventFilter。eventFilter支持的內(nèi)置過濾器見示例注釋過濾器語(yǔ)義debounceFilter(ms)防抖變化停止后才觸發(fā)回調(diào)適合搜索輸入、窗口拖拽等“落定后處理”場(chǎng)景throttledFilter(ms)節(jié)流固定間隔最多觸發(fā)一次回調(diào)適合高頻事件滾動(dòng)、指針移動(dòng)pausableFilter()可暫停返回{ eventFilter, pause, resume }可運(yùn)行時(shí)掛起/恢復(fù)回調(diào)自定義過濾器任意符合ConfigurableEventFilter語(yǔ)義的函數(shù)均可傳入這意味著不需要在業(yè)務(wù)代碼里手寫setTimeout管理或自實(shí)現(xiàn)節(jié)流器過濾器生命周期隨 watch 自動(dòng)管理。三、類型聲明逐條解讀關(guān)聯(lián)文檔給出了watchWithFilter的完整類型聲明共三組重載export interface WatchWithFilterOptionsImmediate extends WatchOptionsImmediate, ConfigurableEventFilter {} export declare function watchWithFilter T, Immediate extends Readonlyboolean false, ( source: WatchSourceT, cb: WatchCallbackT, Immediate extends true ? T | undefined : T, options?: WatchWithFilterOptionsImmediate, ): WatchHandle export declare function watchWithFilter T extends ReadonlyMultiWatchSources, Immediate extends Readonlyboolean false, ( sources: [...T], cb: WatchCallbackMapSourcesT, MapOldSourcesT, Immediate, options?: WatchWithFilterOptionsImmediate, ): WatchHandle export declare function watchWithFilter T extends object, Immediate extends Readonlyboolean false, ( source: T, cb: WatchCallbackT, Immediate extends true ? T | undefined : T, options?: WatchWithFilterOptionsImmediate, ): WatchHandle逐項(xiàng)說明WatchWithFilterOptionsImmediate直接擴(kuò)展WatchOptionsImmediate即原生 watch 的全部選項(xiàng)再交叉混入ConfigurableEventFilter這正是“watch 選項(xiàng) eventFilter”這一核心能力的類型表達(dá)第一個(gè)重載單一 WatchSource接受任意WatchSourceTref / reactive / getter回調(diào)簽名為WatchCallbackT, ...Immediate extends true時(shí) old 值允許為undefined與immediate: true時(shí)回調(diào)首次執(zhí)行沒有舊值的行為一致第二個(gè)重載多源數(shù)組sources: [...T]接受元組形式回調(diào)通過MapSourcesT/MapOldSourcesT, Immediate得到與數(shù)組一一對(duì)應(yīng)的新舊值列表第三個(gè)重載對(duì)象深觀察直接傳T extends object等價(jià)于對(duì) reactive 對(duì)象做深度監(jiān)聽返回值WatchHandle即watch的停止句柄調(diào)用后同時(shí)取消回調(diào)與過濾器的定時(shí)邏輯。三個(gè)重載與原生watch的三組簽名一一對(duì)應(yīng)因此在類型層面watchWithFilter可以視為“drop-in 增強(qiáng)版 watch”——從watch遷移過來只需在 options 里加eventFilter一行。四、airi 倉(cāng)庫(kù)中的落地證據(jù)1. 依賴版本與引入方式airi 是一個(gè) pnpm monorepo根目錄 pnpm-workspace.yaml 中通過 catalog 統(tǒng)一管理版本vueuse/core: ^14.4.0各子包如 apps/stage-web/package.json、packages/stage-pages/package.json中聲明為vueuse/core: catalog:即繼承該版本。因此上文中import { ... } from vueuse/core的寫法在 airi 各應(yīng)用內(nèi)直接可用。2. 過濾型響應(yīng)式在本倉(cāng)庫(kù)的真實(shí)用法在本倉(cāng)庫(kù)源碼中檢索watchWithFilter本身未找到直接調(diào)用即當(dāng)前代碼未直接使用該 API但同一套 EventFilter 機(jī)制的“ref 版”等價(jià)物被大量使用可作為eventFilter思想的對(duì)照佐證apps/stage-pocket/src/pages/devtools/gesture-circle.vue 中同時(shí)使用refThrottled(pointComputed, 50)與refDebounced(pointComputed, 50)對(duì)同一指針坐標(biāo)分別做 50ms 節(jié)流與 50ms 防抖用于 devtools 手勢(shì)調(diào)試面板apps/stage-tamagotchi/src/renderer/pages/index.vue 中const isOutsideFor250Ms refDebounced(isOutside, 250)把“鼠標(biāo)移出窗口”的瞬時(shí)抖動(dòng)過濾為“持續(xù) 250ms 才算真的移出”這是桌面端懸浮窗口stage-tamagotchi Electron 端的典型防誤判模式apps/stage-tamagotchi/src/renderer/pages/settings/connection/index.vue 中const authTokenInputDebounced refDebounced(authTokenInput, 500)對(duì)設(shè)置頁(yè) token 輸入做 500ms 防抖后再參與后續(xù)邏輯apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-root.vue 中refDebounced(liveWindowBounds, placementSettleDelayMs)將高頻變化的窗口邊界“落定”后再用于放置計(jì)算。從源碼結(jié)構(gòu)看這些場(chǎng)景的共同點(diǎn)是高頻響應(yīng)量窗口邊界、指針位置、輸入框→ 過濾器降噪 → 穩(wěn)定值驅(qū)動(dòng) UI/副作用。watchWithFilter正是把同一套 EventFilterdebounceFilter/throttledFilter/pausableFilter掛到watch回調(diào)側(cè)的版本refDebounced解決的是“得到穩(wěn)定的值”watchWithFilter解決的是“在值變化時(shí)按過濾策略執(zhí)行回調(diào)”。3. 與 Watch 類別其他組合的關(guān)系SKILL.md 的 Watch 類別同時(shí)列出了同族函數(shù)可幫助選型函數(shù)定位watchDebouncedwatch 內(nèi)置防抖的快捷方式watchThrottledwatch 內(nèi)置節(jié)流的快捷方式watchPausable可暫停的 watchwatchWithFilter通用出口任意 EventFilter含自定義都能掛入即watchDebounced/watchThrottled/watchPausable可視為watchWithFilter配固定過濾器的快捷形式需要自定義過濾邏輯例如“忽略相等值”“忽略前 N 次”時(shí)直接走watchWithFilter即可。五、小結(jié)什么時(shí)候該用 watchWithFilter結(jié)合 airi 倉(cāng)庫(kù)文檔與源碼選型建議如下需要防抖/節(jié)流的 watch 回調(diào)首選watchWithFilterdebounceFilter/throttledFilter無需手寫setTimeout或自管定時(shí)器清理需要運(yùn)行時(shí)暫停監(jiān)聽pausableFilter比手動(dòng)stop()/watch()更細(xì)粒度回調(diào)句柄仍保留需要自定義過濾規(guī)則eventFilter是唯一的通用插槽其他 watch 快捷函數(shù)做不到只需要“過濾后的值”而非副作用回調(diào)改用refDebounced/refThrottled這是 airi 各應(yīng)用中目前更常見的寫法見第四節(jié)示例路徑。以上所有示例均基于vueuse/coreairi 工作區(qū)當(dāng)前 catalog 版本為^14.4.0見 pnpm-workspace.yaml在 Vue 3 / Nuxt 3 環(huán)境下可直接運(yùn)行?！久赓M(fèi)下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ai/airi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 airi 倉(cāng)庫(kù)中的 VueUse watchWithFilter：給 Vue watch 裝上 eventFilter 事件過濾器
airi 倉(cāng)庫(kù)中的 VueUse watchWithFilter給 Vue watch 裝上 eventFilter 事件過濾器【免費(fèi)下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ai/airi本文基于 airi 倉(cāng)庫(kù)中維護(hù)的 VueUse 函數(shù)技能文檔 .agents/skills/vueuse-functions/references/watchWithFilter.md完整講解watchWithFilter的用法、eventFilter選項(xiàng)與三組類型聲明并結(jié)合 airi 工作區(qū)的依賴配置與真實(shí)過濾型響應(yīng)式用法說明如何把防抖、節(jié)流等“過濾器”掛到watch回調(diào)上以及它在 airi 這類多端Web / Electron / Capacitor應(yīng)用中的定位。一、watchWithFilter 是什么在 airi 倉(cāng)庫(kù)的 VueUse 技能索引 SKILL.md 中watchWithFilter被歸類于Watch類別其描述為watchwith additional EventFilter control也就是說它是對(duì) Vue 原生watch的增強(qiáng)API 簽名與watch基本一致但額外提供一個(gè)eventFilter選項(xiàng)讓回調(diào)函數(shù)在真正執(zhí)行前經(jīng)過一層“事件過濾器”防抖、節(jié)流、可暫停等。它在索引中的 Invocation 規(guī)則為AUTO——即當(dāng)需求匹配時(shí)可直接采用優(yōu)先于手寫定時(shí)器方案。官方文檔給出的定義一句話概括watchwith additional EventFilter control.二、基本用法完整示例與watch類似但多出一個(gè)eventFilter選項(xiàng)該過濾器會(huì)作用于回調(diào)函數(shù)。倉(cāng)庫(kù)文檔中的完整示例如下import { debounceFilter, watchWithFilter } from vueuse/core watchWithFilter( source, () { console.log(changed!) }, // callback will be called in 500ms debounced manner { eventFilter: debounceFilter(500), // throttledFilter, pausableFilter or custom filters }, )要點(diǎn)拆解第一個(gè)參數(shù)source與普通watch一致可以是 ref、reactive 對(duì)象、getter 或 sources 數(shù)組第二個(gè)參數(shù)watch 回調(diào)這里被包在“500ms 防抖”語(yǔ)義下——source 連續(xù)變化時(shí)只有停止變化 500ms 后回調(diào)才會(huì)執(zhí)行一次第三個(gè)參數(shù)options繼承自watch的選項(xiàng)immediate、deep、flush等并額外支持eventFilter。eventFilter支持的內(nèi)置過濾器見示例注釋過濾器語(yǔ)義debounceFilter(ms)防抖變化停止后才觸發(fā)回調(diào)適合搜索輸入、窗口拖拽等“落定后處理”場(chǎng)景throttledFilter(ms)節(jié)流固定間隔最多觸發(fā)一次回調(diào)適合高頻事件滾動(dòng)、指針移動(dòng)pausableFilter()可暫停返回{ eventFilter, pause, resume }可運(yùn)行時(shí)掛起/恢復(fù)回調(diào)自定義過濾器任意符合ConfigurableEventFilter語(yǔ)義的函數(shù)均可傳入這意味著不需要在業(yè)務(wù)代碼里手寫setTimeout管理或自實(shí)現(xiàn)節(jié)流器過濾器生命周期隨 watch 自動(dòng)管理。三、類型聲明逐條解讀關(guān)聯(lián)文檔給出了watchWithFilter的完整類型聲明共三組重載export interface WatchWithFilterOptionsImmediate extends WatchOptionsImmediate, ConfigurableEventFilter {} export declare function watchWithFilter T, Immediate extends Readonlyboolean false, ( source: WatchSourceT, cb: WatchCallbackT, Immediate extends true ? T | undefined : T, options?: WatchWithFilterOptionsImmediate, ): WatchHandle export declare function watchWithFilter T extends ReadonlyMultiWatchSources, Immediate extends Readonlyboolean false, ( sources: [...T], cb: WatchCallbackMapSourcesT, MapOldSourcesT, Immediate, options?: WatchWithFilterOptionsImmediate, ): WatchHandle export declare function watchWithFilter T extends object, Immediate extends Readonlyboolean false, ( source: T, cb: WatchCallbackT, Immediate extends true ? T | undefined : T, options?: WatchWithFilterOptionsImmediate, ): WatchHandle逐項(xiàng)說明WatchWithFilterOptionsImmediate直接擴(kuò)展WatchOptionsImmediate即原生 watch 的全部選項(xiàng)再交叉混入ConfigurableEventFilter這正是“watch 選項(xiàng) eventFilter”這一核心能力的類型表達(dá)第一個(gè)重載單一 WatchSource接受任意WatchSourceTref / reactive / getter回調(diào)簽名為WatchCallbackT, ...Immediate extends true時(shí) old 值允許為undefined與immediate: true時(shí)回調(diào)首次執(zhí)行沒有舊值的行為一致第二個(gè)重載多源數(shù)組sources: [...T]接受元組形式回調(diào)通過MapSourcesT/MapOldSourcesT, Immediate得到與數(shù)組一一對(duì)應(yīng)的新舊值列表第三個(gè)重載對(duì)象深觀察直接傳T extends object等價(jià)于對(duì) reactive 對(duì)象做深度監(jiān)聽返回值WatchHandle即watch的停止句柄調(diào)用后同時(shí)取消回調(diào)與過濾器的定時(shí)邏輯。三個(gè)重載與原生watch的三組簽名一一對(duì)應(yīng)因此在類型層面watchWithFilter可以視為“drop-in 增強(qiáng)版 watch”——從watch遷移過來只需在 options 里加eventFilter一行。四、airi 倉(cāng)庫(kù)中的落地證據(jù)1. 依賴版本與引入方式airi 是一個(gè) pnpm monorepo根目錄 pnpm-workspace.yaml 中通過 catalog 統(tǒng)一管理版本vueuse/core: ^14.4.0各子包如 apps/stage-web/package.json、packages/stage-pages/package.json中聲明為vueuse/core: catalog:即繼承該版本。因此上文中import { ... } from vueuse/core的寫法在 airi 各應(yīng)用內(nèi)直接可用。2. 過濾型響應(yīng)式在本倉(cāng)庫(kù)的真實(shí)用法在本倉(cāng)庫(kù)源碼中檢索watchWithFilter本身未找到直接調(diào)用即當(dāng)前代碼未直接使用該 API但同一套 EventFilter 機(jī)制的“ref 版”等價(jià)物被大量使用可作為eventFilter思想的對(duì)照佐證apps/stage-pocket/src/pages/devtools/gesture-circle.vue 中同時(shí)使用refThrottled(pointComputed, 50)與refDebounced(pointComputed, 50)對(duì)同一指針坐標(biāo)分別做 50ms 節(jié)流與 50ms 防抖用于 devtools 手勢(shì)調(diào)試面板apps/stage-tamagotchi/src/renderer/pages/index.vue 中const isOutsideFor250Ms refDebounced(isOutside, 250)把“鼠標(biāo)移出窗口”的瞬時(shí)抖動(dòng)過濾為“持續(xù) 250ms 才算真的移出”這是桌面端懸浮窗口stage-tamagotchi Electron 端的典型防誤判模式apps/stage-tamagotchi/src/renderer/pages/settings/connection/index.vue 中const authTokenInputDebounced refDebounced(authTokenInput, 500)對(duì)設(shè)置頁(yè) token 輸入做 500ms 防抖后再參與后續(xù)邏輯apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-root.vue 中refDebounced(liveWindowBounds, placementSettleDelayMs)將高頻變化的窗口邊界“落定”后再用于放置計(jì)算。從源碼結(jié)構(gòu)看這些場(chǎng)景的共同點(diǎn)是高頻響應(yīng)量窗口邊界、指針位置、輸入框→ 過濾器降噪 → 穩(wěn)定值驅(qū)動(dòng) UI/副作用。watchWithFilter正是把同一套 EventFilterdebounceFilter/throttledFilter/pausableFilter掛到watch回調(diào)側(cè)的版本refDebounced解決的是“得到穩(wěn)定的值”watchWithFilter解決的是“在值變化時(shí)按過濾策略執(zhí)行回調(diào)”。3. 與 Watch 類別其他組合的關(guān)系SKILL.md 的 Watch 類別同時(shí)列出了同族函數(shù)可幫助選型函數(shù)定位watchDebouncedwatch 內(nèi)置防抖的快捷方式watchThrottledwatch 內(nèi)置節(jié)流的快捷方式watchPausable可暫停的 watchwatchWithFilter通用出口任意 EventFilter含自定義都能掛入即watchDebounced/watchThrottled/watchPausable可視為watchWithFilter配固定過濾器的快捷形式需要自定義過濾邏輯例如“忽略相等值”“忽略前 N 次”時(shí)直接走watchWithFilter即可。五、小結(jié)什么時(shí)候該用 watchWithFilter結(jié)合 airi 倉(cāng)庫(kù)文檔與源碼選型建議如下需要防抖/節(jié)流的 watch 回調(diào)首選watchWithFilterdebounceFilter/throttledFilter無需手寫setTimeout或自管定時(shí)器清理需要運(yùn)行時(shí)暫停監(jiān)聽pausableFilter比手動(dòng)stop()/watch()更細(xì)粒度回調(diào)句柄仍保留需要自定義過濾規(guī)則eventFilter是唯一的通用插槽其他 watch 快捷函數(shù)做不到只需要“過濾后的值”而非副作用回調(diào)改用refDebounced/refThrottled這是 airi 各應(yīng)用中目前更常見的寫法見第四節(jié)示例路徑。以上所有示例均基于vueuse/coreairi 工作區(qū)當(dāng)前 catalog 版本為^14.4.0見 pnpm-workspace.yaml在 Vue 3 / Nuxt 3 環(huán)境下可直接運(yùn)行?！久赓M(fèi)下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ai/airi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考