@whitesev/domutils 1.8.0 → 1.8.2

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

@@ -14,44 +14,114 @@ export type DOMUtilsCreateElementAttributesMap = {
  * 鼠标事件
  * + https://blog.csdn.net/weixin_68658847/article/details/126939879
  */
-
 export interface DOMUtils_MouseEvent {
+  /** 鼠标点击事件 */
   click: MouseEvent | PointerEvent;
+  /** 鼠标中键点击事件 */
   auxclick: PointerEvent;
+  /** 右键菜单事件 */
   contextmenu: MouseEvent | PointerEvent;
+  /** 鼠标双击事件 */
   dblclick: MouseEvent | PointerEvent;
+  /** 鼠标按下事件 */
   mousedown: MouseEvent | PointerEvent;
+  /** 鼠标进入元素事件 */
   mouseenter: MouseEvent | PointerEvent;
+  /** 鼠标离开元素事件 */
   mouseleave: MouseEvent | PointerEvent;
+  /** 鼠标移动事件 */
   mousemove: MouseEvent | PointerEvent;
+  /** 鼠标悬停在元素上事件 */
   mouseover: MouseEvent | PointerEvent;
+  /** 鼠标从元素上移出事件 */
   mouseout: MouseEvent | PointerEvent;
+  /** 鼠标按键释放事件 */
   mouseup: MouseEvent | PointerEvent;
+  /** 鼠标悬停事件 */
   hover: MouseEvent;
 }
 export type DOMUtils_MouseEventType = keyof DOMUtils_MouseEvent;
 /**
- * 鼠标事件
+ * 键盘事件
  */
 export interface DOMUtils_KeyboardEvent {
+  /** 键盘按下事件 */
   keydown: KeyboardEvent;
+  /** 键盘按压事件(字符键) */
   keypress: KeyboardEvent;
+  /** 键盘释放事件 */
   keyup: KeyboardEvent;
 }
 export type DOMUtils_KeyboardEventType = keyof DOMUtils_KeyboardEvent;
+/**
+ * 指针事件
+ */
+export interface DOMUtils_PointerEvent {
+  /**
+   * 当定点设备进入某个元素的命中检测 范围时触发。
+   */
+  pointerover: PointerEvent;
+  /**
+   * 当定点设备进入某个元素或其子元素的命中检测范围时，或做为某一类不支悬停（hover）状态的设备所触发的 poinerdown 事件的后续事件时所触发。（详情可见 pointerdown 事件类型）。
+   */
+  pointerenter: PointerEvent;
+  /**
+   * 当某指针得以激活时触发。
+   */
+  pointerdown: PointerEvent;
+  /**
+   * 当某指针改变其坐标时触发。
+   */
+  pointermove: PointerEvent;
+  /**
+   * 当某指针不再活跃时触发。
+   */
+  pointerup: PointerEvent;
+  /**
+   * 当浏览器认为某指针不会再生成新的后续事件时触发（例如某设备不再活跃）
+   */
+  pointercancel: PointerEvent;
+  /**
+   * 可能由若干原因触发该事件，包括：定位设备移出了某命中检测的边界；不支持悬浮状态的设备发生 pointerup 事件（见 pointerup 事件）；作为 pointercancel 事件的后续事件（见 pointercancel 事件）；当数位板检测到数位笔离开了悬浮区域时。
+   */
+  pointerout: PointerEvent;
+  /**
+   * 当定点设备移出某元素的命中检测边界时触发。对于笔形设备来说，当数位板检测到笔移出了悬浮范围时触发。
+   */
+  pointerleave: PointerEvent;
+  /**
+   * 当某元素接受到一个指针捕捉时触发。
+   */
+  gotpointercapture: PointerEvent;
+  /**
+   * 当针对某个指针的指针捕捉得到释放时触发。
+   */
+  lostpointercapture: PointerEvent;
+}
+export type DOMUtils_PointerEventType = keyof DOMUtils_PointerEvent;
 /**
  * 框架/对象事件
  */
 export interface DOMUtils_Frame_Object_Event {
+  /** 资源加载被中止事件 */
   abort: Event;
+  /** 页面即将卸载前事件 */
   beforeunload: Event;
+  /** JavaScript错误事件 */
   error: Event;
+  /** URL哈希值改变事件 */
   hashchange: Event;
+  /** 页面加载完成事件 */
   load: Event;
+  /** 页面显示事件(包括缓存页面) */
   pageshow: Event;
+  /** 页面隐藏事件 */
   pagehide: Event;
+  /** 窗口大小调整事件 */
   resize: Event;
+  /** 滚动事件 */
   scroll: Event;
+  /** 页面卸载事件 */
   unload: Event;
 }
 export type DOMUtils_Frame_Object_EventType = keyof DOMUtils_Frame_Object_Event;
@@ -59,13 +129,21 @@ export type DOMUtils_Frame_Object_EventType = keyof DOMUtils_Frame_Object_Event;
  * 表单事件
  */
 export interface DOMUtils_FormEvent {
+  /** 元素失去焦点事件 */
   blur: Event;
+  /** 表单控件值改变事件 */
   change: Event;
+  /** 元素获得焦点事件 */
   focus: Event;
+  /** 元素将要获得焦点事件(不冒泡) */
   focusin: Event;
+  /** 元素将要失去焦点事件(不冒泡) */
   focusout: Event;
+  /** 输入框内容改变事件 */
   input: Event;
+  /** 表单重置事件 */
   reset: Event;
+  /** 搜索框搜索事件 */
   search: Event;
 }
 export type DOMUtils_FormEventType = keyof DOMUtils_FormEvent;
@@ -74,8 +152,11 @@ export type DOMUtils_FormEventType = keyof DOMUtils_FormEvent;
  * 剪贴板事件
  */
 export interface DOMUtils_ClipboardEvent {
+  /** 复制事件 */
   copy: ClipboardEvent;
+  /** 剪切事件 */
   cut: ClipboardEvent;
+  /** 粘贴事件 */
   paste: ClipboardEvent;
 }
 export type DOMUtils_ClipboardEventType = keyof DOMUtils_ClipboardEvent;
@@ -84,7 +165,9 @@ export type DOMUtils_ClipboardEventType = keyof DOMUtils_ClipboardEvent;
  * 打印事件
  */
 export interface DOMUtils_PrintEvent {
+  /** 打印之后事件 */
   afterprint: Event;
+  /** 打印之前事件 */
   beforeprint: Event;
 }
 export type DOMUtils_PrintEventType = keyof DOMUtils_PrintEvent;
@@ -93,12 +176,19 @@ export type DOMUtils_PrintEventType = keyof DOMUtils_PrintEvent;
  * 拖动事件
  */
 export interface DOMUtils_DragEvent {
+  /** 拖动元素时触发事件 */
   drag: DragEvent;
+  /** 拖动结束事件 */
   dragend: DragEvent;
+  /** 拖动进入有效放置目标事件 */
   dragenter: DragEvent;
+  /** 拖动离开有效放置目标事件 */
   dragleave: DragEvent;
+  /** 拖动在有效放置目标上移动事件 */
   dragover: DragEvent;
+  /** 开始拖动元素事件 */
   dragstart: DragEvent;
+  /** 拖动元素被放置事件 */
   drop: DragEvent;
 }
 export type DOMUtils_DragEventType = keyof DOMUtils_DragEvent;
@@ -107,27 +197,49 @@ export type DOMUtils_DragEventType = keyof DOMUtils_DragEvent;
  * 多媒体（Media）事件
  */
 export interface DOMUtils_MediaEvent {
+  /** 音频/视频加载过程中被中断事件 */
   abort: Event;
+  /** 可以开始播放时触发事件 */
   canplay: Event;
+  /** 可以流畅播放到结尾时触发事件 */
   canplaythrough: Event;
+  /** 媒体时长发生变化事件 */
   durationchange: Event;
+  /** 媒体资源变为空时触发事件 */
   emptied: Event;
+  /** 媒体播放完毕事件 */
   ended: Event;
+  /** 加载媒体时发生错误事件 */
   error: Event;
+  /** 媒体第一帧加载完成事件 */
   loadeddata: Event;
+  /** 媒体元数据加载完成事件 */
   loadedmetadata: Event;
+  /** 开始寻找媒体文件时触发事件 */
   loadstart: Event;
+  /** 媒体暂停事件 */
   pause: Event;
+  /** 媒体开始播放事件 */
   play: Event;
+  /** 媒体实际开始播放事件 */
   playing: Event;
+  /** 浏览器正在获取媒体数据事件 */
   progress: Event;
+  /** 播放速度改变事件 */
   ratechange: Event;
+  /** 完成跳转到新位置事件 */
   seeked: Event;
+  /** 正在跳转到新位置事件 */
   seeking: Event;
+  /** 获取媒体数据异常缓慢事件 */
   stalled: Event;
+  /** 浏览器故意停止下载媒体事件 */
   suspend: Event;
+  /** 播放位置改变事件 */
   timeupdate: Event;
+  /** 音量改变事件 */
   volumechange: Event;
+  /** 等待数据时触发事件 */
   waiting: Event;
 }
 export type DOMUtils_MediaEventType = keyof DOMUtils_MediaEvent;
@@ -136,8 +248,11 @@ export type DOMUtils_MediaEventType = keyof DOMUtils_MediaEvent;
  * 动画事件
  */
 export interface DOMUtils_AnimationEvent {
+  /** CSS动画结束事件 */
   animationend: AnimationEvent;
+  /** CSS动画重复播放事件 */
   animationiteration: AnimationEvent;
+  /** CSS动画开始事件 */
   animationstart: AnimationEvent;
 }
 export type DOMUtils_AnimationEventType = keyof DOMUtils_AnimationEvent;
@@ -154,11 +269,17 @@ export type DOMUtils_TransitionEventType = keyof DOMUtils_TransitionEvent;
  * 触摸事件
  */
 export interface DOMUtils_TouchEvent {
+  /** 触摸开始事件 */
   touchstart: TouchEvent;
+  /** 触摸移动事件 */
   touchmove: TouchEvent;
+  /** 触摸结束事件 */
   touchend: TouchEvent;
+  /** 触摸被中断事件 */
   touchcancel: TouchEvent;
+  /** 触摸进入元素事件 */
   touchenter: TouchEvent;
+  /** 触摸离开元素事件 */
   touchleave: TouchEvent;
 }
 export type DOMUtils_TouchEventType = keyof DOMUtils_TouchEvent;
@@ -166,16 +287,27 @@ export type DOMUtils_TouchEventType = keyof DOMUtils_TouchEvent;
  * 其它事件
  */
 export interface DOMUtils_OtherEvent {
+  /** 接收到消息事件 */
   message: Event;
+  /** 浏览器上线事件 */
   online: Event;
+  /** 浏览器离线事件 */
   offline: Event;
+  /** 浏览器历史记录改变事件 */
   popstate: Event;
+  /** 上下文菜单显示事件 */
   show: Event;
+  /** Web Storage变化事件 */
   storage: Event;
+  /** details元素打开/关闭事件 */
   toggle: Event;
+  /** 鼠标滚轮滚动事件 */
   wheel: Event;
+  /** IE特有属性改变事件 */
   propertychange: Event;
+  /** 全屏状态改变事件 */
   fullscreenchange: Event;
+  /** DOM内容加载完成事件 */
   DOMContentLoaded: Event;
 }
 export type DOMUtils_OtherEventType = keyof DOMUtils_OtherEvent;
@@ -185,6 +317,7 @@ export type DOMUtils_OtherEventType = keyof DOMUtils_OtherEvent;
  */
 export declare type DOMUtils_Event = DOMUtils_MouseEvent &
   DOMUtils_KeyboardEvent &
+  DOMUtils_PointerEvent &
   DOMUtils_Frame_Object_Event &
   DOMUtils_FormEvent &
   DOMUtils_ClipboardEvent &
@@ -272,3 +405,16 @@ export declare interface DOMUtilsAddEventListenerResult {
    */
   emit(details?: object, useDispatchToEmit?: boolean): void;
 }
+
+/**
+ * 传递的双击配置信息
+ */
+export declare type DOMUtilsDoubleClickOption = {
+  /**
+   * 是否是双击
+   *
+   * + `true`：双击
+   * + `false`：单击
+   */
+  isDoubleClick: boolean;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@whitesev/domutils",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "type": "module",
   "description": "适合在浏览器中操作DOM的常用工具类",
   "main": "dist/index.cjs.js",
@@ -32,27 +32,27 @@
   "author": "WhiteSev",
   "license": "MIT",
   "dependencies": {
-    "worker-timers": "^8.0.25"
+    "worker-timers": "^8.0.27"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.3.0",
-    "browserslist": "^4.28.0",
-    "caniuse-lite": "^1.0.30001757",
-    "eslint": "^9.39.1",
+    "browserslist": "^4.28.1",
+    "caniuse-lite": "^1.0.30001761",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-compat": "^6.0.2",
     "eslint-plugin-prettier": "^5.5.4",
     "globals": "^16.5.0",
-    "rollup": "^4.53.3",
+    "rollup": "^4.54.0",
     "rollup-plugin-clear": "^2.0.7",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.48.0"
+    "typescript-eslint": "^8.50.0"
   },
   "scripts": {
     "lint": "eslint .",

package/src/ElementEvent.ts

@@ -6,6 +6,7 @@ import type {
   DOMUtils_Event,
   DOMUtils_EventType,
   DOMUtilsAddEventListenerResult,
+  DOMUtilsDoubleClickOption,
   DOMUtilsElementEventType,
   DOMUtilsEventListenerOption,
   DOMUtilsEventListenerOptionsAttribute,
@@ -1345,18 +1346,28 @@ class ElementEvent extends ElementAnimate {
   }
   /**
    * 双击监听，适配移动端
+   * @param $el 监听的元素
+   * @param handler 处理的回调函数
+   * @param options 监听器的配置
    */
   onDoubleClick(
     $el: DOMUtilsTargetElementType,
-    handler: (event: MouseEvent | PointerEvent | TouchEvent) => void | Promise<void>,
+    handler: (event: MouseEvent | PointerEvent | TouchEvent, option: DOMUtilsDoubleClickOption) => void | Promise<void>,
     options?: DOMUtilsEventListenerOption | boolean
   ): {
     off(): void;
   };
+  /**
+   * 双击监听，适配移动端
+   * @param $el 监听的元素
+   * @param selector 子元素选择器
+   * @param handler 处理的回调函数
+   * @param options 监听器的配置
+   */
   onDoubleClick(
     $el: DOMUtilsTargetElementType,
     selector: string | string[] | undefined | null,
-    handler: (event: MouseEvent | PointerEvent | TouchEvent) => void | Promise<void>,
+    handler: (event: MouseEvent | PointerEvent | TouchEvent, option: DOMUtilsDoubleClickOption) => void | Promise<void>,
     options?: DOMUtilsEventListenerOption | boolean
   ): {
     off(): void;
@@ -1366,7 +1377,10 @@ class ElementEvent extends ElementAnimate {
   } {
     const $el: DOMUtilsTargetElementType = args[0];
     let selector: string | string[] | undefined | null = void 0;
-    let handler: (event: MouseEvent | PointerEvent | TouchEvent) => void | Promise<void>;
+    let handler: (
+      event: MouseEvent | PointerEvent | TouchEvent,
+      option: DOMUtilsDoubleClickOption
+    ) => void | Promise<void>;
     let options: DOMUtilsEventListenerOption | boolean | undefined;
     if (args.length === 2) {
       if (typeof args[1] === "function") {
@@ -1395,34 +1409,52 @@ class ElementEvent extends ElementAnimate {
     let timer: number | undefined = void 0;
     /** 是否是移动端点击 */
     let isMobileTouch = false;
+    /** 检测是否是单击的延迟时间 */
+    const checkClickTime = 200;
 
-    const dblclick_handler = async (evt: MouseEvent | PointerEvent | TouchEvent) => {
+    const dblclick_handler = async (evt: MouseEvent | PointerEvent | TouchEvent, option: DOMUtilsDoubleClickOption) => {
       if (evt.type === "dblclick" && isMobileTouch) {
         // 禁止在移动端触发dblclick事件
         return;
       }
-      await handler(evt);
+      await handler(evt, option);
     };
 
-    const dblClickListener = this.on($el, "dblclick", dblclick_handler, options);
+    const dblClickListener = this.on(
+      $el,
+      "dblclick",
+      (evt) => {
+        dblclick_handler(evt, {
+          isDoubleClick: true,
+        });
+      },
+      options
+    );
     const touchEndListener = this.on(
       $el,
-      "touchend",
+      "pointerup",
       selector,
       (evt, selectorTarget) => {
-        isMobileTouch = true;
+        if (evt.pointerType === "touch") {
+          isMobileTouch = true;
+        }
         CommonUtils.clearTimeout(timer);
         timer = void 0;
         if (isDoubleClick && $click === selectorTarget) {
           isDoubleClick = false;
           $click = null;
           /* 判定为双击 */
-          dblclick_handler(evt);
+          dblclick_handler(evt, {
+            isDoubleClick: true,
+          });
         } else {
           timer = CommonUtils.setTimeout(() => {
             isDoubleClick = false;
             // 判断为单击
-          }, 200);
+            dblclick_handler(evt, {
+              isDoubleClick: false,
+            });
+          }, checkClickTime);
           isDoubleClick = true;
           $click = selectorTarget;
         }