@composy/idle-vue

@composy/idle-vue

Vue integration for @composy/idle-core.

Installation

pnpm add @composy/idle-vue

useIdle

useIdle creates a detector when its component mounts, exposes reactive state, and destroys that detector when the component unmounts.

<script setup lang="ts">
import { useIdle } from '@composy/idle-vue'

const { status, isIdle, isPaused, pause, resume, activity } = useIdle({
  timeout: 60_000,
  onIdle: () => console.log('idle'),
})
</script>

<template>
  <p>状态：{{ status }}</p>
  <p v-if="isIdle">用户暂时没有操作</p>
  <p v-if="isPaused">检测已暂停</p>
  <button type="button" @click="pause">暂停检测</button>
  <button type="button" @click="resume">恢复检测</button>
  <button type="button" @click="activity">手动续期</button>
</template>

status is a Ref<'active' | 'idle' | 'away'>; isIdle is true for both idle and away; isPaused reflects the detector pause state. activity, pause, and resume are safe before mount and after unmount. The options are passed to IdleDetector, including the optional activity target.

createIdlePlugin

The plugin provides a detector through IDLE_DETECTOR_KEY, the ldesign-idle string key, and $idle.

import { createApp, inject } from 'vue'
import { createIdlePlugin, IDLE_DETECTOR_KEY } from '@composy/idle-vue'

const app = createApp(App)
app.use(createIdlePlugin({ timeout: 60_000 }))

const detector = inject(IDLE_DETECTOR_KEY)

Detector creation is deferred until install, so creating a plugin does not start timers. Each app gets its own detector. A detector supplied as detector is borrowed and remains owned by the caller; an existing detector already provided by the app is reused. Only a detector created by the plugin is destroyed when the app unmounts.

Validation commands

The @composy/builder / Rolldown configuration, ESLint config, and TypeScript configurations live under this package's .ldesign/. The package-root ESLint and TypeScript files remain compatibility shims. The workspace build runs Core first, then Vue, and checks this package's output contract.

pnpm build
pnpm type-check
pnpm lint:check
pnpm test:run
```## 真实 API 用法

```ts
import { createApp } from 'vue'
import { createIdlePlugin, IdleDetector } from '@composy/idle-vue'

const app = createApp(App)
app.use(createIdlePlugin({ timeout: 60_000, awayTimeout: 300_000 }))

插件在 install 时才创建检测器；每个 app 拥有独立实例，并在 app 卸载时销毁。若传入 detector，插件只负责 provide 和全局属性，不会销毁调用方拥有的实例：

const detector = new IdleDetector({ timeout: 60_000 })
app.use(createIdlePlugin({ detector }))

useIdle 会在组件挂载时创建检测器，在卸载时自动销毁，并暴露响应式的 status 与 isIdle。

当前 composable 还返回 isPaused、activity()、pause() 和 resume()：可以在无 DOM 事件的业务操作中手动续期，也可以在模态框、视频或批处理期间暂停计时。组件卸载后这些方法会变成安全 no-op，避免异步回调持有已销毁实例。