tiny-event-intercept/README_zh-CN.md

Lightweight (~1.0KB) TypeScript library for conditional event interception with browser-standard API. Zero dependencies, SSR compatible, robust edge case handling.

# tiny-event-intercept

[![npm version](https://badge.fury.io/js/tiny-event-intercept.svg)](https://badge.fury.io/js/tiny-event-intercept)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/tiny-event-intercept)](https://bundlephobia.com/package/tiny-event-intercept)

轻量级（约 1.0KB）、零依赖的 TypeScript 条件性事件拦截库，采用浏览器标准 API。专为现代 Web 应用中的条件事件处理而设计。

**语言**: [English](./README.md) | 简体中文

## 特性

- **🔒 类型安全**: 完整 TypeScript 支持，严格类型检查和智能提示
- **🌐 通用性**: SSR 兼容，支持 Node.js 和浏览器环境
- **🧹 内存安全**: 自动清理机制，防止内存泄漏
- **⚡ 高性能**: 优化的事件处理，最小开销（约 70万 ops/sec）
- **📦 轻量级**: 仅约 1.0KB 压缩后大小，零依赖
- **🎯 浏览器标准**: 扩展原生 `AddEventListenerOptions` API
- **🔄 框架无关**: 支持 React、Vue、Svelte 或原生 JavaScript

## 安装

```bash
npm install tiny-event-intercept
```

## 快速开始

```typescript
import { interceptEvents } from 'tiny-event-intercept'

// 功能禁用时阻止点击
let isEnabled = false

const cleanup = interceptEvents(document, {
  events: 'click',
  when: () => !isEnabled,
  listener: (event) => {
    console.log('功能已禁用')
    event.preventDefault()
  },
})

// 稍后启用功能
isEnabled = true

// 完成后清理
cleanup()
```

## API

### `interceptEvents(target, options): CleanupFunction`

使用符合浏览器标准的 API 创建条件性事件拦截器。

```typescript
function interceptEvents(target: TargetElement, options: InterceptOptions): CleanupFunction

// 类型定义
type TargetElement = EventTarget | (() => EventTarget | null) | null
type EventTypes = keyof GlobalEventHandlersEventMap | readonly (keyof GlobalEventHandlersEventMap)[]

interface InterceptOptions extends AddEventListenerOptions {
  events: EventTypes // 要拦截的事件类型
  when: () => boolean // 条件函数
  listener: EventListener // 事件处理函数
  // 继承: capture?, once?, passive?, signal?
}

type EventTarget = Element | Document | Window
type CleanupFunction = () => void
```

**参数:**

- `target` - 目标元素、返回元素的函数或 null（默认为 document）
- `options` - 拦截选项，包含事件类型、条件函数和监听器

**返回值:**

- `CleanupFunction` - 移除所有事件监听器的函数

## 使用示例

### 基础拦截

```typescript
const cleanup = interceptEvents(document, {
  events: ['click', 'keydown'],
  when: () => !isReady,
  listener: (event) => {
    console.log(`${event.type} 被拦截`)
    event.preventDefault()
  },
})
```

### 单个事件类型

```typescript
let isSpecialMode = false

const cleanup = interceptEvents(document, {
  events: 'click', // 单个事件作为字符串
  when: () => isSpecialMode,
  listener: (event) => {
    console.log('特殊模式点击被拦截')
    event.preventDefault()
  },
})

// 启用特殊模式
isSpecialMode = true
```

### 针对特定元素

```typescript
const button = document.querySelector<HTMLButtonElement>('#submit')

const cleanup = interceptEvents(button, {
  events: 'click',
  when: () => !isFormValid,
  listener: (event) => {
    showValidationError()
    event.preventDefault()
  },
})
```

### 动态目标函数

```typescript
const cleanup = interceptEvents(
  () => document.querySelector('.active-element'), // 动态目标
  {
    events: 'click',
    when: () => isInterceptMode,
    listener: (event) => {
      console.log('动态目标被点击')
      event.preventDefault()
    },
  },
)
```

### 浏览器标准选项

```typescript
const cleanup = interceptEvents(document.body, {
  events: ['click', 'touchstart'],
  when: () => isInterceptMode,
  listener: (event) => {
    console.log('事件被拦截')
  },
  capture: true, // 捕获阶段
  once: true, // 只执行一次
  passive: true, // 被动监听器
})
```

## 框架集成

### React

```typescript
import { useEffect, useState } from 'react'
import { interceptEvents } from 'tiny-event-intercept'

function FeatureToggle() {
  const [isEnabled, setIsEnabled] = useState(false)

  useEffect(() => {
    const cleanup = interceptEvents(document, {
      events: 'click',
      when: () => !isEnabled,
      listener: (event) => {
        console.log('功能已禁用')
        event.preventDefault()
      }
    })

    return cleanup // 组件卸载时清理
  }, [isEnabled])

  return (
    <button onClick={() => setIsEnabled(!isEnabled)}>
      {isEnabled ? '禁用' : '启用'} 功能
    </button>
  )
}
```

### Vue

```typescript
import { onMounted, onUnmounted, ref } from 'vue'
import { interceptEvents } from 'tiny-event-intercept'

export default {
  setup() {
    const isEnabled = ref(false)
    let cleanup: (() => void) | null = null

    onMounted(() => {
      cleanup = interceptEvents(document, {
        events: 'click',
        when: () => !isEnabled.value,
        listener: (event) => event.preventDefault(),
      })
    })

    onUnmounted(() => {
      cleanup?.()
    })

    return { isEnabled }
  },
}
```

## 内存管理

库提供强大的清理机制：

- **手动清理**: 调用返回的清理函数
- **自动清理**: 页面卸载时移除监听器
- **幂等性**: 安全地多次调用清理函数

```typescript
const cleanup = interceptEvents(document, {
  events: 'click',
  when: () => true,
  listener: () => {},
})

// 安全地多次调用
cleanup()
cleanup() // 不会出错
```

## 许可证

MIT