useClickOutside

一个点击外部区域检测 Hook，用于检测用户是否点击了指定元素外部的区域。常用于关闭下拉菜单、模态框等组件。

基础用法

📋 下拉菜单

显示代码

模态框示例

🪟 模态框

显示代码

API 参考

参数

参数	类型	默认值	说明
callback	(event: Event) => void	-	点击外部时的回调函数
options	UseClickOutsideOptions	{}	配置选项

UseClickOutsideOptions

属性	类型	默认值	说明
events	string[]	['mousedown', 'touchstart']	监听的事件类型
immediate	boolean	true	是否立即启用检测
capture	boolean	true	是否在捕获阶段监听事件
exclude	MaybeRefOrGetter<HTMLElement>[]	[]	排除的元素列表

返回值

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

const [targetRef, setEnabled] = useClickOutside(callback, options);

索引	名称	类型	说明
0	targetRef	Ref<HTMLElement | null>	目标元素的响应式引用
1	setEnabled	(enabled: boolean) => void	启用/禁用检测的函数

类型定义

export interface UseClickOutsideOptions {
  events?: string[];
  immediate?: boolean;
  capture?: boolean;
  exclude?: MaybeRefOrGetter<HTMLElement>[];
}

export type SetEnabledFunction = (enabled: boolean) => void;

export type UseClickOutsideReturn = [Ref<HTMLElement | null>, SetEnabledFunction];

使用场景

1. 下拉菜单 - 点击外部关闭下拉菜单
2. 模态框 - 点击遮罩层关闭模态框
3. 弹出框 - 点击外部关闭弹出框
4. 侧边栏 - 点击外部收起侧边栏
5. 搜索建议 - 点击外部隐藏搜索建议

高级用法

排除特定元素

const triggerRef = ref<HTMLElement>();
const [targetRef] = useClickOutside(
  () => {
    // 点击外部的回调
  },
  {
    exclude: [triggerRef], // 排除触发元素
  },
);

条件启用

const [targetRef, setEnabled] = useClickOutside(
  () => {
    // 回调函数
  },
  { immediate: false },
);

// 根据条件启用/禁用
watch(isVisible, (visible) => {
  setEnabled(visible);
});

自定义事件

const [targetRef] = useClickOutside(
  () => {
    // 回调函数
  },
  {
    events: ["click", "contextmenu"], // 监听点击和右键菜单
  },
);

注意事项

1. 需要将 targetRef 绑定到目标元素上
2. 回调函数会在点击目标元素外部时触发
3. 可以通过 setEnabled 动态控制检测的启用状态
4. 支持排除特定元素，避免误触发
5. 组件卸载时会自动清理事件监听器