feat(useClickAway): 支持传入 options 作为 addEventListner 的第三个参数

Author: Xav1erSue

packages/hooks/src/useClickAway/demo/demo7.tsx

@@ -0,0 +1,30 @@
+/**
+ * title: Support event listener options
+ * desc: For scenarios where click is blocked from bubbling, you can use event listener options to change the capture phase.
+ *
+ * title.zh-CN: 支持事件监听选项
+ * desc.zh-CN: 针对点击阻止冒泡的场景，可以使用事件监听选项选择捕获阶段。
+ */
+
+import React, { useState, useRef } from 'react';
+import { useClickAway } from 'ahooks';
+
+export default () => {
+  const [counter, setCounter] = useState(0);
+
+  const ref = useRef<HTMLButtonElement>(null);
+
+  useClickAway(() => setCounter((s) => s + 1), ref, 'click', { capture: true });
+
+  return (
+    <div>
+      <button ref={ref} type='button'>
+        box1
+      </button>
+      <button type='button' style={{ marginLeft: 16 }} onClick={(e) => e.stopPropagation()}>
+        box2
+      </button>
+      <p>counter: {counter}</p>
+    </div>
+  );
+};

packages/hooks/src/useClickAway/index.en-US.md

@@ -33,6 +33,10 @@ Listen for click events outside the target element.
 
 <code src="./demo/demo6.tsx"/>
 
+### Support event listener options
+
+<code src="./demo/demo7.tsx"/>
+
 ## API
 
 ```typescript
@@ -42,7 +46,8 @@ type DocumentEventKey = keyof DocumentEventMap;
 useClickAway<T extends Event = Event>(
   onClickAway: (event: T) => void,
   target: Target | Target[],
-  eventName?: DocumentEventKey | DocumentEventKey[]
+  eventName?: DocumentEventKey | DocumentEventKey[],
+  options?: boolean | AddEventListenerOptions
 );
 ```
 
@@ -53,3 +58,4 @@ useClickAway<T extends Event = Event>(
 | onClickAway | Trigger Function                            | `(event: T) => void`                       | -       |
 | target      | DOM elements or Ref, support array          | `Target` \| `Target[]`                     | -       |
 | eventName   | Set the event to be listened, support array | `DocumentEventKey` \| `DocumentEventKey[]` | `click` |
+| options     | Event listener options                       | `boolean` \| `AddEventListenerOptions`      | `false` |

packages/hooks/src/useClickAway/index.ts

@@ -10,8 +10,10 @@ export default function useClickAway<T extends Event = Event>(
   onClickAway: (event: T) => void,
   target: BasicTarget | BasicTarget[],
   eventName: DocumentEventKey | DocumentEventKey[] = 'click',
+  options?: boolean | AddEventListenerOptions,
 ) {
   const onClickAwayRef = useLatest(onClickAway);
+  const optionsRef = useLatest(options);
 
   useEffectWithTarget(
     () => {
@@ -32,10 +34,14 @@ export default function useClickAway<T extends Event = Event>(
 
       const eventNames = Array.isArray(eventName) ? eventName : [eventName];
 
-      eventNames.forEach((event) => documentOrShadow.addEventListener(event, handler));
+      eventNames.forEach((event) =>
+        documentOrShadow.addEventListener(event, handler, optionsRef.current),
+      );
 
       return () => {
-        eventNames.forEach((event) => documentOrShadow.removeEventListener(event, handler));
+        eventNames.forEach((event) =>
+          documentOrShadow.removeEventListener(event, handler, optionsRef.current),
+        );
       };
     },
     Array.isArray(eventName) ? eventName : [eventName],

packages/hooks/src/useClickAway/index.zh-CN.md

@@ -33,6 +33,10 @@ nav:
 
 <code src="./demo/demo6.tsx" />
 
+### 支持事件监听选项
+
+<code src="./demo/demo7.tsx" />
+
 ## API
 
 ```typescript
@@ -42,7 +46,8 @@ type DocumentEventKey = keyof DocumentEventMap;
 useClickAway<T extends Event = Event>(
   onClickAway: (event: T) => void,
   target: Target | Target[],
-  eventName?: DocumentEventKey | DocumentEventKey[]
+  eventName?: DocumentEventKey | DocumentEventKey[],
+  options?: boolean | AddEventListenerOptions
 );
 ```
 
@@ -53,3 +58,4 @@ useClickAway<T extends Event = Event>(
 | onClickAway | 触发函数                     | `(event: T) => void`                       | -       |
 | target      | DOM 节点或者 Ref，支持数组   | `Target` \| `Target[]`                     | -       |
 | eventName   | 指定需要监听的事件，支持数组 | `DocumentEventKey` \| `DocumentEventKey[]` | `click` |
+| options     | 事件监听选项                 | `boolean` \| `AddEventListenerOptions`      | `false` |