useEventListener

通用事件监听器管理 Hook，提供统一的事件监听器管理功能，支持多种目标类型和自动生命周期管理。

基础用法

最简单的用法是监听元素的点击事件。

点击我 (0)

显示代码

监听窗口事件

可以监听全局事件，如窗口大小变化。

窗口大小: 0 × 0

显示代码

实际应用场景

键盘事件处理

最后按键: 无

显示代码

鼠标悬停效果

鼠标移入试试

显示代码

条件监听

启用点击监听

监听已禁用

点击次数: 0

显示代码

手动控制监听器

监听已禁用

点击次数: 0

显示代码

API

参数

参数名	类型	默认值	说明
target	EventTargetRef	-	事件目标，支持响应式引用或函数
event	string	-	事件名称
handler	EventHandler<T>	-	事件处理函数
options	UseEventListenerOptions	{}	配置选项

配置选项

选项名	类型	默认值	说明
immediate	boolean	true	是否立即添加监听器
autoRemove	boolean	true	是否在组件卸载时自动移除监听器
passive	boolean	-	是否为被动监听器
capture	boolean	-	是否在捕获阶段处理事件
once	boolean	-	是否只触发一次

返回值

返回一个数组，包含以下元素：

索引	类型	说明
0	AddListenerFunction	手动添加事件监听器的函数
1	RemoveListenerFunction	手动移除事件监听器的函数
2	SetEnabledFunction	启用/禁用事件监听器的函数

类型定义

/**
 * 事件监听器的目标类型
 */
export type EventTarget = Window | Document | HTMLElement | null;

/**
 * 事件监听器的目标引用类型
 */
export type EventTargetRef = Ref<EventTarget> | (() => EventTarget);

/**
 * 通用事件处理函数类型
 */
export type EventHandler<T extends Event = Event> = (event: T) => void;

/**
 * 添加事件监听器的函数类型
 */
export type AddListenerFunction = () => void;

/**
 * 移除事件监听器的函数类型
 */
export type RemoveListenerFunction = () => void;

/**
 * useEventListener 钩子函数的返回值类型
 */
export type UseEventListenerReturn = [
  /** 手动添加事件监听器的函数 */
  AddListenerFunction,
  /** 手动移除事件监听器的函数 */
  RemoveListenerFunction,
  /** 启用/禁用事件监听器的函数 */
  SetEnabledFunction,
];

/**
 * 事件监听器配置选项
 */
export interface UseEventListenerOptions extends AddEventListenerOptions {
  /** 是否立即添加监听器，默认为 true */
  immediate?: boolean;
  /** 是否在组件卸载时自动移除监听器，默认为 true */
  autoRemove?: boolean;
}

/**
 * 通用事件监听器管理 Hook
 * @param target - 事件目标，支持响应式引用或函数
 * @param event - 事件名称
 * @param handler - 事件处理函数
 * @param options - 配置选项
 * @returns 返回包含控制函数的数组
 * @example
 * ```typescript
 * // 基础用法
 * const [addListener, removeListener, setEnabled] = useEventListener(
 *   buttonRef,
 *   'click',
 *   () => console.log('clicked')
 * );
 *
 * // 监听窗口事件
 * const [, , setResizeEnabled] = useEventListener(
 *   window,
 *   'resize',
 *   () => console.log('resized'),
 *   { passive: true }
 * );
 *
 * // 条件监听
 * const [, , setEnabled] = useEventListener(
 *   elementRef,
 *   'scroll',
 *   handleScroll,
 *   { immediate: false }
 * );
 * ```
 */
export function useEventListener<T extends Event = Event>(
  target: EventTargetRef,
  event: string,
  handler: EventHandler<T>,
  options?: UseEventListenerOptions,
): UseEventListenerReturn;

注意事项

1. 目标类型: 支持 Window、Document、HTMLElement 等多种目标类型
2. 响应式目标: 当目标元素发生变化时，会自动重新绑定事件监听器
3. 生命周期管理: 默认在组件卸载时自动清理监听器，防止内存泄漏
4. 性能优化: 使用 setEnabled 可以动态启用/禁用监听器，避免不必要的事件处理
5. 类型安全: 完整的 TypeScript 类型支持，提供良好的开发体验
6. 选项配置: 支持所有原生 addEventListener 的选项，如 passive、capture、once 等