• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

useIntervalFn是 VueUse 提供的setInterval响应式封装，它把原生定时器包装成带pause、resume、isActive控制句柄的组合式函数，并在组件卸载时自动清理定时器。在 airi 这个自托管 AI 伴侣项目中，它被广泛用于轮询远端状态、驱动动画寻帧、周期刷新 UI 等场景，是理解 VueUse 定时类 API 的最佳切入点。读完本文，你将掌握useIntervalFn的完整签名、两个关键配置项的行为差异，以及如何在轮询、节流式寻帧、生命周期管理等真实业务中正确使用它。

一、认识 useIntervalFn：带控制句柄的 setInterval 封装

在 vueuse-functions skill 的 SKILL.md 中，useIntervalFn被归类在Animation（动画）分类下，描述为 "Wrapper forsetIntervalwith controls"，调用级别为AUTO（适用时自动使用）。它的核心价值不是"换一种写法调用setInterval"，而是解决原生定时器三大痛点：

1. 生命周期管理：原生setInterval需要手动clearInterval，而useIntervalFn会在组件卸载（或 effect scope 销毁）时自动清理，避免内存泄漏；
2. 可暂停/恢复：通过返回的pause()/resume()可以随时挂起和恢复定时任务，不必销毁后重建；
3. 响应式间隔：第二个参数interval支持MaybeRefOrGetter<number>类型，意味着可以传入 ref 或 getter，间隔变化时定时器会自动重置。

airi 工作区通过 pnpm-workspace.yaml 的 catalog 统一管理依赖版本，@vueuse/core与@vueuse/shared均为^14.4.0，下文的类型声明与行为均以该版本为准。

二、基础用法与返回结构

参考文档 useIntervalFn.md 给出的最小用法如下：

import { useIntervalFn } from '@vueuse/core' const { pause, resume, isActive } = useIntervalFn(() => { /* your function */ }, 1000)

调用后，回调每1000ms执行一次。返回对象类型是UseIntervalFnReturn = Pausable，这是 VueUse 在@vueuse/shared中定义的通用可暂停接口，标准结构为：

export interface Pausable { /** * 指示当前实例是否处于激活（运行）状态的 ref */ isActive: Readonly<Ref<boolean>> /** * 暂停效果执行 */ pause: () => void /** * 恢复效果执行 */ resume: () => void }

• isActive是响应式 ref，可用于驱动 UI（例如显示"正在同步中"的状态）；
• pause()会清除底层的定时器，isActive变为false；
• resume()会重新创建定时器并继续执行，isActive变为true。默认情况下resume不会立即执行回调，而是从下一次间隔开始；只有开启immediateCallback后才在恢复瞬间先执行一次。

三、完整签名与参数详解

参考文档给出了useIntervalFn的完整类型声明：

export interface UseIntervalFnOptions { /** * 是否立即启动定时器 * * @default true */ immediate?: boolean /** * 调用 resume 后是否立即执行一次回调 * * @default false */ immediateCallback?: boolean } export type UseIntervalFnReturn = Pausable export declare function useIntervalFn( cb: Fn, interval?: MaybeRefOrGetter<number>, options?: UseIntervalFnOptions, ): UseIntervalFnReturn

三个参数逐一说明：

两个选项的组合决定了定时任务的实际触发时机，这是实战中最容易踩坑的地方：

• immediate: true（默认）：组件挂载即开始计时，第一个回调在首个interval周期结束后才触发；
• immediate: false：定时器初始处于暂停状态，必须手动调用resume()才开始；适合"需要等到某个条件满足（如登录、菜单展开）再启动"的场景；
• immediateCallback: true：与immediate或resume配合时，在启动/恢复的当下立刻执行一次回调，常用于需要"启动即拿一次数据、随后周期刷新"的轮询模式。

四、与相邻定时 API 的选型对比

在 airi 的源码中，VueUse 定时类 API 常成组出现，理解它们的差异有助于正确选型：

例如在 use-playback-keys.ts 中，useIntervalFn与useTimeoutFn被刻意组合：useTimeoutFn负责"按键按住 300ms 后进入连续寻帧"的延迟门控，useIntervalFn则负责随后每 80ms 步进一次，二者各司其职。这正是"定时器语义不同就选不同 API"的典型示范。

五、airi 中的真实应用场景剖析

1. 轮询外部状态：Electron 显示器列表

use-electron-all-displays.ts 展示了最朴素的轮询用法——用useIntervalFn每 5000ms 重新执行一次useAsyncState的execute，让 Electron 屏幕列表保持新鲜：

useIntervalFn(() => { void execute() }, 5000)

这里完全使用默认配置（immediate: true），进入 setup 即开始轮询，组件卸载自动清理。注意void execute()的写法：回调不等待异步完成，周期与请求耗时解耦，避免轮询被慢请求阻塞。

2. 登录态驱动的拉取：暂停/恢复控制

config.ts 是 provider 配置云同步的拉取逻辑，用useIntervalFn实现"登录后每 5 分钟拉取一次远端配置"：

const PULL_INTERVAL_MS = 5 * 60 * 1000 const periodicSync = useIntervalFn( () => { void syncProviders() }, PULL_INTERVAL_MS, { immediate: false }, ) authStore.onAuthenticated(() => { void syncProviders() periodicSync.resume() }) authStore.onLogout(() => { periodicSync.pause() })

这里immediate: false是关键：用户未登录时定时器保持暂停，登录后resume()启动周期拉取，登出后pause()挂起，彻底避免未认证状态下发起无效请求。注释中还特别说明了间隔与 VS Code Settings Sync 保持一致的工程决策。

3. 周期强制校验：resume 手动启动 + force 请求

provider.ts 为每个已配置的 provider 建立周期校验循环，使用useIntervalFn同时显式关闭两个选项并手动resume：

const loop = useIntervalFn(() => { void useProviderStore().validateProvider(providerId, { force: true }) }, intervalMs, { immediate: false, immediateCallback: false }) loop.resume() providerRevalidationLoops.set(providerId, loop)

immediateCallback: false在此有明确工程意图：周期校验会消耗 API 额度，绝不能在校验循环刚建立时就立即打一次请求，必须等第一个完整周期结束后再执行。这个 store 还维护了providerRevalidationLoops映射来集中管理各循环的pause/resume（如resetProviderSettings中统一loop.pause()），展示了"把 controls 句柄存起来以便统一管理"的可复用模式。

4. 动画驱动的连续寻帧：80ms 加速步进

use-playback-keys.ts 与 use-gamepad-actions.ts 实现了同一套"按住寻帧并加速"交互（分别由键盘和手柄驱动）：

const holdInterval = useIntervalFn(() => { if (activeDirection !== 0) step(activeDirection, heldStepCount()) }, holdSeekPolicy.intervalMs, { immediate: false }) const holdDelay = useTimeoutFn(() => { if (activeDirection === 0) return holdStarted = true step(activeDirection, heldStepCount()) holdInterval.resume() }, holdSeekPolicy.delayMs, { immediate: false })

流程是：按键按下 →useTimeoutFn延迟 300ms 判定为"长按" → 调用holdInterval.resume()启动 80ms 周期的连续步进 → 按住的时长越久，heldStepCount()依据accelerationWindowMs二次方加速返回的步数越多。松开或窗口失焦时调用holdInterval.pause()与holdDelay.stop()复位。useIntervalFn在这里扮演的是"高频但受控"的执行引擎，与immediate: false配合确保定时器在无操作期间完全静默，不做无谓的逐帧计算。

5. 可见性感知的轻量刷新：250ms 主题色采样

theme-color.ts 为动态波浪背景保持<meta name="theme-color">新鲜度：

const { pause, resume } = useIntervalFn(() => { if (visibility.value !== 'visible') return if (selectedOption.value?.kind === BackgroundKind.Wave && themeColorsHueDynamic.value) void updateThemeColor() }, 250, { immediate: false }) watch([() => selectedOption.value?.kind, () => themeColorsHueDynamic.value], ([kind, dynamic]) => { if (kind === BackgroundKind.Wave && dynamic) { void updateThemeColor() resume() } else { pause() } }, { immediate: true })

这里把"是否需要轮询"的决策交给watch：只有选中动态波浪背景时才resume()开始 250ms 一次的主题色刷新，切换到静态背景立即pause()。回调内部再用useDocumentVisibility判断页面是否可见，双重保险避免后台标签页空转。这就是"按需启停 + 可见性兜底"的低功耗轮询范式。

6. 菜单打开期间的麦克风电平监测

voice-input-button.vue 展示了immediateCallback: true的典型价值——语音输入按钮的悬停菜单需要实时电平条：

const monitor = useIntervalFn(() => { if (navigator.userActivation?.hasBeenActive ?? true) controls.monitorLevel(LEVEL_MONITOR_RENEW_MS * 1.5) }, LEVEL_MONITOR_RENEW_MS, { immediate: false, immediateCallback: true }) watch(menuOpen, async (open) => { monitor.pause() if (!open) return const permission = await navigator.permissions?.query({ name: 'microphone' as PermissionName }).catch(() => undefined) if (menuOpen.value && (!permission || permission.state === 'granted')) monitor.resume() })

每次resume()（即菜单重新打开）都会因immediateCallback: true立即发起一次电平监测请求，保证电平条"打开即有值、无空窗"，随后每 1000ms 续期一次（监测请求时长取 1.5 倍间隔以覆盖续期间隙）。回调中还利用navigator.userActivation判断浏览器是否已获得用户激活，避免在无手势的 hover 场景触发麦克风权限弹窗。

7. 后台诊断数据的周期请求

use-screen-ambient-light-diagnostics.ts 用useIntervalFn(requestWhenVisible, screenAmbientLightDiagnosticsRequestMs)周期向主渲染进程广播请求环境光诊断快照，requestWhenVisible内部用document.visibilityState过滤：页面隐藏时不做任何请求，主进程也随即停止发送帧数据，从源头规避了隐藏窗口的无谓渲染开销。

六、使用建议与注意事项

综合以上源码实践，在项目中引入useIntervalFn时有几条可复用的经验：

1. 默认先关immediate：需要"等条件满足再启动"的轮询（登录、菜单展开、设备就绪）务必显式传{ immediate: false }，避免组件挂载瞬间就打无意义请求；
2. 需要"启动即执行"时开immediateCallback：轮询场景常希望恢复瞬间立刻拿一次数据再进入周期，此时{ immediate: false, immediateCallback: true }组合最顺手；
3. 把返回的 controls 存起来：像 provider.ts 那样用 Map 或 ref 统一持有各实例的pause/resume，便于在登出、重置、切页等时机批量管理；
4. 回调保持轻量或异步解耦：void execute()的模式让周期不被异步耗时阻塞；若任务较重，考虑与useTimeoutPoll配合按需调整节奏；
5. 无需手动清理：useIntervalFn在作用域销毁时自动pause，这也是它相对于原生setInterval的最大优势——无需像 use-screen-ambient-light-diagnostics.ts 中手动addEventListener那样配套removeEventListener；
6. 间隔可以是响应式的：利用MaybeRefOrGetter<number>签名，把间隔写成 ref/getter 即可在运行期动态调速（如后台自动降频），无需重建定时器。

七、小结

useIntervalFn以极小的 API 面积覆盖了定时器从"创建—运行—暂停—恢复—销毁"的完整生命周期，并通过Pausable控制接口把定时任务的启停权交还给业务逻辑。从 airi 的实践可以看到：无论是 Electron 状态轮询、Provider 凭据周期校验，还是 Live2D 动画连续寻帧、麦克风电平监测，它都能以统一且可组合的方式落地。掌握它，就等于掌握了 VueUse 全部定时类 API 的设计范式——useTimeoutFn、useTimeoutPoll、useRafFn都是同一套"controls + 自动清理"心智模型的变体。更多相邻函数的详细说明，可继续阅读 vueuse-functions skill 的 Animation 分类参考文档。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手