@whitesev/domutils 1.9.4 → 1.9.6

package/dist/types/src/ElementEvent.d.ts

@@ -255,7 +255,7 @@ declare class ElementEvent extends ElementAnimate {
      *  console.log("触发click事件成功")
      * })
      * */
-    click(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["click"]) => void, details?: object, useDispatchToEmit?: boolean): void;
+    click(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["click"]) => void, details?: object, useDispatchToEmit?: boolean): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 监听或触发元素的blur事件
      * @param element 目标元素
@@ -270,7 +270,7 @@ declare class ElementEvent extends ElementAnimate {
      *  console.log("触发blur事件成功")
      * })
      * */
-    blur(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["blur"]) => void, details?: object, useDispatchToEmit?: boolean): void;
+    blur(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["blur"]) => void, details?: object, useDispatchToEmit?: boolean): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 监听或触发元素的focus事件
      * @param element 目标元素
@@ -285,7 +285,7 @@ declare class ElementEvent extends ElementAnimate {
      *  console.log("触发focus事件成功")
      * })
      * */
-    focus(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["focus"]) => void, details?: object, useDispatchToEmit?: boolean): void;
+    focus(element: DOMUtilsTargetElementType | Element | DocumentFragment | typeof globalThis | Window, handler?: (this: HTMLElement, event: DOMUtils_Event["focus"]) => void, details?: object, useDispatchToEmit?: boolean): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 当鼠标移入或移出元素时触发事件
      * @param element 当前元素
@@ -300,7 +300,7 @@ declare class ElementEvent extends ElementAnimate {
      *   console.log("移入/移除");
      * })
      */
-    onHover(element: DOMUtilsTargetElementType | Element | DocumentFragment | Node, handler: (this: HTMLElement, event: DOMUtils_Event["hover"]) => void, option?: boolean | DOMUtilsEventListenerOption): void;
+    onHover(element: DOMUtilsTargetElementType | Element | DocumentFragment | Node, handler: (this: HTMLElement, event: DOMUtils_Event["hover"]) => void, option?: boolean | DOMUtilsEventListenerOption): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 监听动画结束
      * @param element 监听的元素
@@ -334,7 +334,7 @@ declare class ElementEvent extends ElementAnimate {
      *   console.log("按键松开");
      * })
      */
-    onKeyup(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keyup"]) => void, option?: boolean | DOMUtilsEventListenerOption): void;
+    onKeyup(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keyup"]) => void, option?: boolean | DOMUtilsEventListenerOption): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 当按键按下时触发事件
      * keydown - > keypress - > keyup
@@ -350,7 +350,7 @@ declare class ElementEvent extends ElementAnimate {
      *   console.log("按键按下");
      * })
      */
-    onKeydown(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keydown"]) => void, option?: boolean | DOMUtilsEventListenerOption): void;
+    onKeydown(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keydown"]) => void, option?: boolean | DOMUtilsEventListenerOption): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 当按键按下时触发事件
      * keydown - > keypress - > keyup
@@ -366,7 +366,7 @@ declare class ElementEvent extends ElementAnimate {
      *   console.log("按键按下");
      * })
      */
-    onKeypress(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keypress"]) => void, option?: boolean | DOMUtilsEventListenerOption): void;
+    onKeypress(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, handler: (this: HTMLElement, event: DOMUtils_Event["keypress"]) => void, option?: boolean | DOMUtilsEventListenerOption): DOMUtilsAddEventListenerResult | undefined;
     /**
      * 监听某个元素键盘按键事件或window全局按键事件
      * 按下有值的键时触发，按下Ctrl\Alt\Shift\Meta是无值键。按下先触发keydown事件，再触发keypress事件。
@@ -430,18 +430,14 @@ declare class ElementEvent extends ElementAnimate {
          搜索		170
          收藏		171
       **/
-    onKeyboard(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, eventName: "keydown" | "keypress" | "keyup" | undefined, handler: (keyName: string, keyValue: number, otherCodeList: string[], event: KeyboardEvent) => void, options?: DOMUtilsEventListenerOption | boolean): {
-        removeListen(): void;
-    };
+    onKeyboard(element: DOMUtilsTargetElementType | Element | DocumentFragment | Window | Node | typeof globalThis, eventName: "keydown" | "keypress" | "keyup" | undefined, handler: (keyName: string, keyValue: number, otherCodeList: string[], event: KeyboardEvent) => void, options?: DOMUtilsEventListenerOption | boolean): DOMUtilsAddEventListenerResult;
     /**
      * 监input、textarea的输入框值改变的事件（当输入法输入时，不会触发该监听）
      * @param $el 输入框元素
      * @param handler 回调函数
      * @param option 配置
      */
-    onInput($el: HTMLInputElement | HTMLTextAreaElement, handler: (evt: InputEvent) => void | Promise<void>, option?: DOMUtilsEventListenerOption | boolean): {
-        off: () => void;
-    };
+    onInput($el: HTMLInputElement | HTMLTextAreaElement, handler: (evt: InputEvent) => void | Promise<void>, option?: DOMUtilsEventListenerOption | boolean): DOMUtilsAddEventListenerResult;
     /**
      * 双击监听，适配移动端
      * @param $el 监听的元素
@@ -463,20 +459,76 @@ declare class ElementEvent extends ElementAnimate {
     };
     /**
      * 阻止事件传递
+     *
+     * + `.preventDefault()`: 阻止事件的默认行为发生。例如，当点击一个链接时，浏览器会默认打开链接的URL，或者在输入框内输入文字
+     * + `.stopPropagation()`: 停止事件的传播，阻止它继续向更上层的元素冒泡，事件将不会再传播给其他的元素
+     * + `.stopImmediatePropagation()`: 阻止事件传播，并且还能阻止元素上的其他事件处理程序被触发
      * @param event 要阻止传递的事件
      * @example
      * DOMUtils.preventEvent(event);
      */
-    preventEvent(event: Event): boolean;
+    preventEvent(event: Event): false;
+    /**
+     * 阻止事件传递
+     * @param event 要阻止传递的事件
+     * @param onlyStopPropagation （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()`
+     * @example
+     * DOMUtils.preventEvent(event, true);
+     */
+    preventEvent<T extends boolean>(event: Event, onlyStopPropagation: T): T extends true ? void : false;
     /**
      * 通过监听事件来主动阻止事件的传递
      * @param $el 要进行处理的元素
-     * @param eventNameList （可选）要阻止的事件名|列表
-     * @param capture （可选）是否捕获，默认false
+     * @param eventNameList 要阻止的事件名|列表
+     * @param option （可选）配置项
      * @example
-     * DOMUtils.preventEvent(document.querySelector("a"),"click")
+     * DOMUtils.preventEvent(document.querySelector("a"), "click")
+     * @example
+     * DOMUtils.preventEvent(document.querySelector("a"), "click", undefined, {
+     *   capture: true,
+     * })
+     * @example
+     * DOMUtils.preventEvent(document, "click", "a.xxx", {
+     *   capture: true,
+     *   onlyStopPropagation: true,
+     * })
      */
-    preventEvent($el: HTMLElement, eventNameList?: string | string[], capture?: boolean): void;
+    preventEvent($el: HTMLElement, eventNameList: string | string[], option?: {
+        /** （可选）是否捕获，默认false */
+        capture?: boolean;
+        /** （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()` */
+        onlyStopPropagation?: boolean;
+    }): {
+        /** 移除监听事件 */
+        off(): void;
+    };
+    /**
+     * 通过监听事件来主动阻止事件的传递
+     * @param $el 要进行处理的元素
+     * @param eventNameList 要阻止的事件名|列表
+     * @param selector 子元素选择器
+     * @param option （可选）配置项
+     * @example
+     * DOMUtils.preventEvent(document.querySelector("a"), "click")
+     * @example
+     * DOMUtils.preventEvent(document.querySelector("a"), "click", undefined, {
+     *   capture: true,
+     * })
+     * @example
+     * DOMUtils.preventEvent(document, "click", "a.xxx", {
+     *   capture: true,
+     *   onlyStopPropagation: true,
+     * })
+     */
+    preventEvent($el: HTMLElement, eventNameList: string | string[], selector: string | string[] | null | undefined, option?: {
+        /** （可选）是否捕获，默认false */
+        capture?: boolean;
+        /** （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()` */
+        onlyStopPropagation?: boolean;
+    }): {
+        /** 移除监听事件 */
+        off(): void;
+    };
 }
 declare const elementEvent: ElementEvent;
 export { elementEvent, ElementEvent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@whitesev/domutils",
-  "version": "1.9.4",
+  "version": "1.9.6",
   "description": "适合在浏览器中操作DOM的常用工具类",
   "keywords": [
     "typescript",

package/src/ElementEvent.ts

@@ -957,7 +957,8 @@ class ElementEvent extends ElementAnimate {
     if (handler == null) {
       that.emit(element, "click", details, useDispatchToEmit);
     } else {
-      that.on(element, "click", null, handler);
+      const listener = that.on(element, "click", null, handler);
+      return listener;
     }
   }
   /**
@@ -997,7 +998,8 @@ class ElementEvent extends ElementAnimate {
     if (handler === null) {
       that.emit(element, "blur", details, useDispatchToEmit);
     } else {
-      that.on(element, "blur", null, handler as (event: Event) => void);
+      const listener = that.on(element, "blur", null, handler as (event: Event) => void);
+      return listener;
     }
   }
   /**
@@ -1037,7 +1039,8 @@ class ElementEvent extends ElementAnimate {
     if (handler == null) {
       that.emit(element, "focus", details, useDispatchToEmit);
     } else {
-      that.on(element, "focus", null, handler);
+      const listener = that.on(element, "focus", null, handler);
+      return listener;
     }
   }
   /**
@@ -1068,13 +1071,31 @@ class ElementEvent extends ElementAnimate {
     }
     if (CommonUtils.isNodeList(element)) {
       // 设置
+      const listenerList: (DOMUtilsAddEventListenerResult | undefined)[] = [];
       element.forEach(($ele) => {
-        that.onHover($ele as HTMLElement, handler, option);
+        const listener = that.onHover($ele as HTMLElement, handler, option);
+        listenerList.push(listener);
       });
-      return;
+      return {
+        off() {
+          listenerList.forEach((listener) => {
+            if (!listener) {
+              return;
+            }
+            listener.off();
+          });
+        },
+      } as DOMUtilsAddEventListenerResult;
     }
-    that.on(element, "mouseenter", null, handler, option);
-    that.on(element, "mouseleave", null, handler, option);
+    const mouseenter_listener = that.on(element, "mouseenter", null, handler, option);
+    const mouseleave_listener = that.on(element, "mouseleave", null, handler, option);
+
+    return {
+      off() {
+        mouseenter_listener.off();
+        mouseleave_listener.off();
+      },
+    } as DOMUtilsAddEventListenerResult;
   }
   /**
    * 监听动画结束
@@ -1169,12 +1190,23 @@ class ElementEvent extends ElementAnimate {
     }
     if (CommonUtils.isNodeList(element)) {
       // 设置
+      const listenerList: (DOMUtilsAddEventListenerResult | undefined)[] = [];
       element.forEach(($ele) => {
-        that.onKeyup($ele as HTMLElement, handler, option);
+        const listener = that.onKeyup($ele as HTMLElement, handler, option);
+        listenerList.push(listener);
       });
-      return;
+      return {
+        off() {
+          listenerList.forEach((listener) => {
+            if (!listener) {
+              return;
+            }
+            listener.off();
+          });
+        },
+      } as DOMUtilsAddEventListenerResult;
     }
-    that.on(element, "keyup", null, handler, option);
+    return that.on(element, "keyup", null, handler, option);
   }
   /**
    * 当按键按下时触发事件
@@ -1205,12 +1237,23 @@ class ElementEvent extends ElementAnimate {
     }
     if (CommonUtils.isNodeList(element)) {
       // 设置
+      const listenerList: (DOMUtilsAddEventListenerResult | undefined)[] = [];
       element.forEach(($ele) => {
-        that.onKeydown($ele as HTMLElement, handler, option);
+        const listener = that.onKeydown($ele as HTMLElement, handler, option);
+        listenerList.push(listener);
       });
-      return;
+      return {
+        off() {
+          listenerList.forEach((listener) => {
+            if (!listener) {
+              return;
+            }
+            listener.off();
+          });
+        },
+      } as DOMUtilsAddEventListenerResult;
     }
-    that.on(element, "keydown", null, handler, option);
+    return that.on(element, "keydown", null, handler, option);
   }
   /**
    * 当按键按下时触发事件
@@ -1241,12 +1284,23 @@ class ElementEvent extends ElementAnimate {
     }
     if (CommonUtils.isNodeList(element)) {
       // 设置
+      const listenerList: (DOMUtilsAddEventListenerResult | undefined)[] = [];
       element.forEach(($ele) => {
-        that.onKeypress($ele as HTMLElement, handler, option);
+        const listener = that.onKeypress($ele as HTMLElement, handler, option);
+        listenerList.push(listener);
       });
-      return;
+      return {
+        off() {
+          listenerList.forEach((listener) => {
+            if (!listener) {
+              return;
+            }
+            listener.off();
+          });
+        },
+      } as DOMUtilsAddEventListenerResult;
     }
-    that.on(element, "keypress", null, handler, option);
+    return that.on(element, "keypress", null, handler, option);
   }
   /**
    * 监听某个元素键盘按键事件或window全局按键事件
@@ -1316,9 +1370,7 @@ class ElementEvent extends ElementAnimate {
     eventName: "keydown" | "keypress" | "keyup" = "keypress",
     handler: (keyName: string, keyValue: number, otherCodeList: string[], event: KeyboardEvent) => void,
     options?: DOMUtilsEventListenerOption | boolean
-  ): {
-    removeListen(): void;
-  } {
+  ): DOMUtilsAddEventListenerResult {
     const that = this;
     if (typeof element === "string") {
       element = that.selectorAll(element);
@@ -1346,12 +1398,8 @@ class ElementEvent extends ElementAnimate {
         handler(keyName, keyValue, otherCodeList, event);
       }
     };
-    that.on(element, eventName, keyboardEventCallBack, options);
-    return {
-      removeListen: () => {
-        that.off(element, eventName, keyboardEventCallBack, options);
-      },
-    };
+    const listener = that.on(element, eventName, keyboardEventCallBack, options);
+    return listener;
   }
   /**
    * 监input、textarea的输入框值改变的事件（当输入法输入时，不会触发该监听）
@@ -1363,7 +1411,7 @@ class ElementEvent extends ElementAnimate {
     $el: HTMLInputElement | HTMLTextAreaElement,
     handler: (evt: InputEvent) => void | Promise<void>,
     option?: DOMUtilsEventListenerOption | boolean
-  ) {
+  ): DOMUtilsAddEventListenerResult {
     /**
      * 是否正在输入中
      */
@@ -1386,11 +1434,14 @@ class ElementEvent extends ElementAnimate {
     const compositionEndListener = this.on($el, "compositionend", __composition_end_callback, option);
 
     return {
-      off: () => {
+      off() {
         inputListener.off();
         compositionStartListener.off();
         compositionEndListener.off();
       },
+      emit(details?, useDispatchToEmit?) {
+        inputListener.emit(details, useDispatchToEmit);
+      },
     };
   }
   /**
@@ -1454,60 +1505,35 @@ class ElementEvent extends ElementAnimate {
       throw new Error("args length error");
     }
 
-    let $click: Element | null = null;
+    let clickMap = new WeakMap<Element, PointerEvent>();
     let isDoubleClick = false;
     let timer: number | undefined = void 0;
-    /** 是否是移动端点击 */
-    let isMobileTouch = false;
     /** 检测是否是单击的延迟时间 */
     const checkClickTime = 200;
 
-    const dblclick_handler = async (
+    const dblclick_handler = (
       evt: MouseEvent | PointerEvent | TouchEvent,
       option: DOMUtilsDoubleClickOption,
       $selector?: HTMLElement
     ) => {
-      if (evt.type === "dblclick" && isMobileTouch) {
-        // 禁止在移动端触发dblclick事件
-        return;
-      }
       if ($selector) {
-        await (<DOMUtilsDoubleClickHandlerWithSelector>handler)(evt, $selector, option);
+        return (<DOMUtilsDoubleClickHandlerWithSelector>handler)(evt, $selector, option);
       } else {
-        await (<DOMUtilsDoubleClickHandler>handler)(evt, option);
+        return (<DOMUtilsDoubleClickHandler>handler)(evt, option);
       }
     };
 
-    const dblClickListener = this.on(
-      $el,
-      "dblclick",
-      selector,
-      (evt, $selector) => {
-        this.preventEvent(evt);
-        dblclick_handler(
-          evt,
-          {
-            isDoubleClick: true,
-          },
-          $selector
-        );
-      },
-      options
-    );
     const pointerUpListener = this.on(
       $el,
       "pointerup",
       selector,
       (evt, $selector) => {
-        this.preventEvent(evt);
-        if (evt.pointerType === "touch") {
-          isMobileTouch = true;
-        }
+        // this.preventEvent(evt);
         clearTimeout(timer);
         timer = void 0;
-        if (isDoubleClick && $click === $selector) {
+        if (isDoubleClick && clickMap.has($selector as Element)) {
           isDoubleClick = false;
-          $click = null;
+          clickMap.delete($selector);
           /* 判定为双击 */
           dblclick_handler(
             evt,
@@ -1529,7 +1555,7 @@ class ElementEvent extends ElementAnimate {
             );
           }, checkClickTime);
           isDoubleClick = true;
-          $click = $selector;
+          clickMap.set($selector as Element, evt);
         }
       },
       options
@@ -1537,53 +1563,157 @@ class ElementEvent extends ElementAnimate {
 
     return {
       off() {
-        $click = null;
-        dblClickListener.off();
         pointerUpListener.off();
+        // @ts-expect-error
+        clickMap = null;
       },
     };
   }
   /**
    * 阻止事件传递
+   *
+   * + `.preventDefault()`: 阻止事件的默认行为发生。例如，当点击一个链接时，浏览器会默认打开链接的URL，或者在输入框内输入文字
+   * + `.stopPropagation()`: 停止事件的传播，阻止它继续向更上层的元素冒泡，事件将不会再传播给其他的元素
+   * + `.stopImmediatePropagation()`: 阻止事件传播，并且还能阻止元素上的其他事件处理程序被触发
    * @param event 要阻止传递的事件
    * @example
    * DOMUtils.preventEvent(event);
    */
-  preventEvent(event: Event): boolean;
+  preventEvent(event: Event): false;
+  /**
+   * 阻止事件传递
+   * @param event 要阻止传递的事件
+   * @param onlyStopPropagation （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()`
+   * @example
+   * DOMUtils.preventEvent(event, true);
+   */
+  preventEvent<T extends boolean>(event: Event, onlyStopPropagation: T): T extends true ? void : false;
+  /**
+   * 通过监听事件来主动阻止事件的传递
+   * @param $el 要进行处理的元素
+   * @param eventNameList 要阻止的事件名|列表
+   * @param option （可选）配置项
+   * @example
+   * DOMUtils.preventEvent(document.querySelector("a"), "click")
+   * @example
+   * DOMUtils.preventEvent(document.querySelector("a"), "click", undefined, {
+   *   capture: true,
+   * })
+   * @example
+   * DOMUtils.preventEvent(document, "click", "a.xxx", {
+   *   capture: true,
+   *   onlyStopPropagation: true,
+   * })
+   */
+  preventEvent(
+    $el: HTMLElement,
+    eventNameList: string | string[],
+    option?: {
+      /** （可选）是否捕获，默认false */
+      capture?: boolean;
+      /** （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()` */
+      onlyStopPropagation?: boolean;
+    }
+  ): {
+    /** 移除监听事件 */
+    off(): void;
+  };
   /**
    * 通过监听事件来主动阻止事件的传递
    * @param $el 要进行处理的元素
-   * @param eventNameList （可选）要阻止的事件名|列表
-   * @param capture （可选）是否捕获，默认false
+   * @param eventNameList 要阻止的事件名|列表
+   * @param selector 子元素选择器
+   * @param option （可选）配置项
+   * @example
+   * DOMUtils.preventEvent(document.querySelector("a"), "click")
+   * @example
+   * DOMUtils.preventEvent(document.querySelector("a"), "click", undefined, {
+   *   capture: true,
+   * })
    * @example
-   * DOMUtils.preventEvent(document.querySelector("a"),"click")
+   * DOMUtils.preventEvent(document, "click", "a.xxx", {
+   *   capture: true,
+   *   onlyStopPropagation: true,
+   * })
    */
-  preventEvent($el: HTMLElement, eventNameList?: string | string[], capture?: boolean): void;
-  preventEvent(...args: any[]) {
+  preventEvent(
+    $el: HTMLElement,
+    eventNameList: string | string[],
+    selector: string | string[] | null | undefined,
+    option?: {
+      /** （可选）是否捕获，默认false */
+      capture?: boolean;
+      /** （可选）是否仅阻止事件的传播，默认false，不调用`.preventDefault()` */
+      onlyStopPropagation?: boolean;
+    }
+  ): {
+    /** 移除监听事件 */
+    off(): void;
+  };
+  preventEvent(...args: any[]): boolean | void | { off(): void } {
     /**
      * 阻止事件的默认行为发生，并阻止事件传播
      */
-    const stopEvent = (event: Event) => {
-      /* 阻止事件的默认行为发生。例如，当点击一个链接时，浏览器会默认打开链接的URL */
+    const stopEvent = (event: Event, onlyStopPropagation?: boolean) => {
+      if (typeof onlyStopPropagation === "boolean" && onlyStopPropagation) {
+        // 停止事件的传播，阻止它继续向更上层的元素冒泡，事件将不会再传播给其他的元素
+        event?.stopPropagation();
+        // 阻止事件传播，并且还能阻止元素上的其他事件处理程序被触发
+        event?.stopImmediatePropagation();
+        return;
+      }
+      // 阻止事件的默认行为发生。例如，当点击一个链接时，浏览器会默认打开链接的URL，或者在输入框内输入文字
       event?.preventDefault();
-      /* 停止事件的传播，阻止它继续向更上层的元素冒泡，事件将不会再传播给其他的元素 */
-      event?.stopPropagation();
-      /* 阻止事件传播，并且还能阻止元素上的其他事件处理程序被触发 */
-      event?.stopImmediatePropagation();
       return false;
     };
-    if (args.length === 1) {
-      /* 直接阻止事件 */
-      return stopEvent(args[0]);
+    if (args[0] instanceof Event) {
+      // 直接阻止事件
+      const onlyStopPropagation: boolean = args[1];
+      return stopEvent(args[0], onlyStopPropagation);
     } else {
       const $el: HTMLElement = args[0];
       let eventNameList: string | string[] = args[1];
-      const capture: boolean = args[2];
-      /* 添加对应的事件来阻止触发 */
+      let selector: string | string[] | null | undefined = void 0;
+      let capture = false;
+      let onlyStopPropagation = false;
+      // 添加对应的事件来阻止触发
       if (typeof eventNameList === "string") {
         eventNameList = [eventNameList];
       }
-      this.on($el, eventNameList, stopEvent, { capture: Boolean(capture) });
+
+      let option:
+        | {
+            capture?: boolean;
+            onlyStopPropagation?: boolean;
+          }
+        | undefined = void 0;
+      if (typeof args[2] === "string" || Array.isArray(args[2])) {
+        // selector
+        selector = args[2];
+        if (typeof args[3] === "object" && args[3] != null) {
+          option = args[3];
+        }
+      } else if (typeof args[2] === "object" && args[2] != null && !Array.isArray(args[2])) {
+        // option
+        option = args[2];
+      } else {
+        throw new TypeError("Invalid argument");
+      }
+      if (option) {
+        capture = Boolean(option.capture);
+        onlyStopPropagation = Boolean(option.onlyStopPropagation);
+      }
+
+      const listener = this.on(
+        $el,
+        eventNameList,
+        selector,
+        (evt) => {
+          return stopEvent(evt, onlyStopPropagation);
+        },
+        { capture: capture }
+      );
+      return listener;
     }
   }
 }

package/src/Utils.ts

@@ -156,10 +156,7 @@ class Utils {
         "slideDown",
         "slideToggle",
         "slideUp",
-        "sort",
-        "splice",
         "text",
-        "toArray",
         "toggle",
         "toggleClass",
         "trigger",