fix(useEventListener): improve types (#4787)

ArthurDarkstone · liliang18 · Alfred-Skyblue · web-flow · commit 6f5658337301 · 2025-06-19T08:05:33.000Z
Co-authored-by: liliang18 &lt;liliang18@tal.com&gt;
Co-authored-by: 远方os &lt;yangpanteng@gmail.com&gt;
diff --git a/packages/core/useEventListener/index.test.ts b/packages/core/useEventListener/index.test.ts
@@ -360,4 +360,51 @@ describe('useEventListener', () => {
     expect(addSpy).toHaveBeenLastCalledWith('click', listener, true)
     expect(removeSpy).toHaveBeenCalledTimes(1)
   })
+
+  it('should check document and shadowRoot', async () => {
+    const element = document.createElement('div')
+    const shadowRoot = element.attachShadow({ mode: 'open' })
+    const listener1 = vi.fn()
+    const listener2 = vi.fn()
+
+    useEventListener(shadowRoot, 'click', listener1)
+    useEventListener(document, 'click', listener2)
+
+    shadowRoot.dispatchEvent(new Event('click'))
+    document.dispatchEvent(new Event('click'))
+    expect(listener1).toHaveBeenCalledTimes(1)
+    expect(listener2).toHaveBeenCalledTimes(1)
+  })
+
+  it('should check multiple shadowRoots + multiple events', async () => {
+    const element1 = document.createElement('div')
+    const shadowRoot1 = element1.attachShadow({ mode: 'open' })
+    const element2 = document.createElement('div')
+    const shadowRoot2 = element2.attachShadow({ mode: 'closed' })
+
+    const listener = vi.fn()
+
+    useEventListener([element1, element2, shadowRoot1, shadowRoot2], ['click', 'slotchange'], listener)
+
+    shadowRoot1.dispatchEvent(new Event('click'))
+    shadowRoot2.dispatchEvent(new Event('click'))
+
+    await nextTick()
+
+    expect(listener).toHaveBeenCalledTimes(2)
+
+    element1.dispatchEvent(new Event('click'))
+    element2.dispatchEvent(new Event('click'))
+
+    await nextTick()
+
+    expect(listener).toHaveBeenCalledTimes(4)
+
+    shadowRoot1.dispatchEvent(new Event('slotchange'))
+    shadowRoot2.dispatchEvent(new Event('slotchange'))
+
+    await nextTick()
+
+    expect(listener).toHaveBeenCalledTimes(6)
+  })
 })
diff --git a/packages/core/useEventListener/index.ts b/packages/core/useEventListener/index.ts
@@ -13,6 +13,7 @@ interface InferEventTarget<Events> {
 
 export type WindowEventName = keyof WindowEventMap
 export type DocumentEventName = keyof DocumentEventMap
+export type ShadowRootEventName = keyof ShadowRootEventMap
 
 export interface GeneralEventListener<E = Event> {
   (evt: E): void
@@ -65,7 +66,7 @@ export function useEventListener<E extends keyof WindowEventMap>(
  * @param options
  */
 export function useEventListener<E extends keyof DocumentEventMap>(
-  target: DocumentOrShadowRoot,
+  target: Document,
   event: MaybeRefOrGetter<Arrayable<E>>,
   listener: MaybeRef<Arrayable<(this: Document, ev: DocumentEventMap[E]) => any>>,
   options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
@@ -74,7 +75,25 @@ export function useEventListener<E extends keyof DocumentEventMap>(
 /**
  * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
  *
- * Overload 4: Explicitly HTMLElement target
+ * Overload 4: Explicitly ShadowRoot target
+ *
+ * @see https://vueuse.org/useEventListener
+ * @param target
+ * @param event
+ * @param listener
+ * @param options
+ */
+export function useEventListener<E extends keyof ShadowRootEventMap>(
+  target: MaybeRefOrGetter<Arrayable<ShadowRoot> | null | undefined>,
+  event: MaybeRefOrGetter<Arrayable<E>>,
+  listener: MaybeRef<Arrayable<(this: ShadowRoot, ev: ShadowRootEventMap[E]) => any>>,
+  options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
+): Fn
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
+ *
+ * Overload 5: Explicitly HTMLElement target
  *
  * @see https://vueuse.org/useEventListener
  * @param target
@@ -87,12 +106,12 @@ export function useEventListener<E extends keyof HTMLElementEventMap>(
   event: MaybeRefOrGetter<Arrayable<E>>,
   listener: MaybeRef<(this: HTMLElement, ev: HTMLElementEventMap[E]) => any>,
   options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
-): () => void
+): Fn
 
 /**
  * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
  *
- * Overload 5: Custom event target with event type infer
+ * Overload 6: Custom event target with event type infer
  *
  * @see https://vueuse.org/useEventListener
  * @param target
@@ -110,7 +129,7 @@ export function useEventListener<Names extends string, EventType = Event>(
 /**
  * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
  *
- * Overload 6: Custom event target fallback
+ * Overload 7: Custom event target fallback
  *
  * @see https://vueuse.org/useEventListener
  * @param target
