# ldesign-idle

**Repository Path**: ldesign-v1/ldesign-idle

## Basic Information

- **Project Name**: ldesign-idle
- **Description**: LDesign ???? - Idle detection for user inactivity
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/idle

> 用户空闲检测库 — 监听用户不活动状态，支持可配置超时、多事件源和页面可见性检测。

## ✨ 特性

- **三段状态** — `active`（活跃）→ `idle`（空闲）→ `away`（离开）
- **多事件源** — 监听鼠标、键盘、触摸、滚轮等多种交互事件
- **页面可见性** — 页面切换到后台时自动标记为空闲
- **可配置超时** — 分别设置空闲超时和离开超时
- **Vue 集成** — 提供 `useIdle` 组合式函数和 Vue 插件

## 📦 安装

```bash
# 核心
pnpm add @ldesign/idle

# Vue 适配器
pnpm add @ldesign/idle @ldesign/idle-vue
```

## 🚀 快速开始

### 原生 JavaScript

```ts
import { IdleDetector } from '@ldesign/idle'

const detector = new IdleDetector({
  timeout: 5 * 60 * 1000,       // 5 分钟进入空闲
  awayTimeout: 30 * 60 * 1000,  // 30 分钟标记为离开
  onIdle: () => console.log('用户空闲了'),
  onActive: () => console.log('用户回来了'),
  onStatusChange: (status) => console.log('状态:', status),
})

// 获取当前状态
detector.getStatus() // 'active' | 'idle' | 'away'

// 销毁
detector.destroy()
```

### Vue 3

```vue
<script setup>
import { useIdle } from '@ldesign/idle-vue'

const { status, isIdle, isAway } = useIdle({
  timeout: 5 * 60 * 1000,
  onIdle: () => {
    // 显示"您已空闲"提示
  },
})
</script>

<template>
  <p>当前状态: {{ status }}</p>
  <p v-if="isIdle">⚠️ 您已空闲</p>
</template>
```

## 📖 API

### IdleOptions

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `timeout` | `number` | `300000` | 空闲超时（ms），默认 5 分钟 |
| `awayTimeout` | `number` | `1800000` | 离开超时（ms），默认 30 分钟 |
| `events` | `string[]` | `[mousemove, mousedown, keydown, scroll, touchstart, pointerdown]` | 监听的 DOM 事件 |
| `detectVisibility` | `boolean` | `true` | 是否检测页面可见性 |
| `onStatusChange` | `(status) => void` | - | 状态变化回调 |
| `onIdle` | `() => void` | - | 进入空闲回调 |
| `onActive` | `() => void` | - | 恢复活跃回调 |

### IdleDetector

| 方法 | 说明 |
|------|------|
| `getStatus()` | 获取当前状态 (`'active'` \| `'idle'` \| `'away'`) |
| `start()` | 启动监听 |
| `destroy()` | 停止监听并清理资源 |

## 📄 License

MIT © LDesign Team