minutool 1.0.20 → 1.0.22

package/dist/index.d.ts

@@ -12,9 +12,16 @@ export declare const abortableFetch: (url: string, fetchOption?: RequestOption)
 
 /**
  * 可中止的 Fetch 请求
+ * 完全独立定义，避免与 Promise 类型混淆
  */
-export declare interface AbortablePromise<T> extends Promise<T> {
+export declare interface AbortablePromise<T> extends PromiseLike<T> {
     abort: () => void;
+    abortSilently: () => void;
+    aborted: boolean;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): AbortablePromise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): AbortablePromise<T | TResult>;
+    finally(onfinally?: (() => void) | undefined | null): AbortablePromise<T>;
+    readonly [Symbol.toStringTag]: "Promise";
 }
 
 export declare class AbortError extends Error {
@@ -92,6 +99,16 @@ export declare const arraySortByKey: <T extends Record<string, any>>(obj: T) =>
  */
 export declare const arrayTrimTail: (arr: any[]) => any[];
 
+/**
+ * 类型断言辅助函数：明确告诉 TypeScript 某个值是 AbortablePromise
+ * 用于解决 TypeScript 类型推导在某些情况下无法识别 AbortablePromise 的问题
+ * @param promise - 实际上是 AbortablePromise 的对象
+ * @returns 带有正确类型的 AbortablePromise
+ * @example
+ * const req = asAbortable(abortableFetch('/api').then(res => res.json()));
+ */
+export declare const asAbortable: <T>(promise: any) => AbortablePromise<T>;
+
 /**
  * Base64 解码
  * @param {string} text - Base64 编码的字符串
@@ -129,6 +146,54 @@ export declare const base64UrlSafeEncode: (text: string) => string;
  */
 export declare const between: (val: number, min: number, max: number, includeEqual?: boolean) => boolean;
 
+/**
+ * 绑定点击事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param payload - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindClick: (element: HTMLElement | string, payload: (event: Event) => void) => () => void;
+
+/**
+ * 绑定DOM事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param eventName - 事件名称
+ * @param payload - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindDomEvent: (element: HTMLElement | string, eventName: string, payload: (event: Event) => void) => () => void;
+
+/**
+ * 绑定双击事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param payload - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindDoubleClick: (element: HTMLElement | string, payload: (event: Event) => void) => () => void;
+
+/**
+ * 绑定键盘按键按下事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param payload - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindKeyDown: (element: HTMLElement | string, payload: (event: Event) => void) => () => void;
+
+/**
+ * 绑定键盘按键抬起事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param payload - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindKeyUp: (element: HTMLElement | string, payload: (event: Event) => void) => () => void;
+
+/**
+ * 绑定对象移动事件
+ * @param element - 要移动的元素
+ * @param handle - 拖动句柄，默认为元素本身
+ */
+export declare function bindNodeMove(element: HTMLElement | string, handle?: HTMLElement | string | null): () => void;
+
 /**
  * 转换 Blob 数据到 Base64 Data URL
  * @param {Blob} blob - Blob 对象
@@ -430,7 +495,7 @@ export declare const escapeHtml: (str: string, tabSize?: number, allowLineBreake
  * @param handler 事件处理函数, 参数为事件对象和匹配的子元素 (event, target)
  * @return 返回一个取消事件委托的函数
  */
-export declare const eventDelegate: (parent: HTMLElement, selector: string, event: string, handler: (event: Event, target: HTMLElement) => void) => () => void;
+export declare const eventDelegate: (parent: HTMLElement | string, selector: string, event: string, handler: (event: Event, target: HTMLElement) => void) => () => void;
 
 /**
  * 退出全屏模式
@@ -552,7 +617,7 @@ export declare const getDomDimension: (dom: HTMLElement) => {
  * @example
  * getJson('/api/users').then(data => console.log(data))
  */
-export declare const getJson: (url: string, data?: any, option?: RequestOption) => Promise<any>;
+export declare const getJson: (url: string, data?: any, option?: RequestOption) => AbortablePromise<any>;
 
 /**
  * 获取节点的 XPath
@@ -846,8 +911,8 @@ export declare const loadScript: (src: string, forceReload?: boolean) => Promise
 
 /**
  * 绑定元素，禁止交互
- * @param {Node} el
- * @param {Function} payload 处理函数，参数为 reset
+ * @param el - DOM 元素或选择器
+ * @param payload - 处理函数，参数为 reset
  */
 export declare const lockElementInteraction: (el: HTMLElement | string, payload: (reset: () => void) => void) => void;
 
@@ -1343,14 +1408,14 @@ export declare const onDocReady: (handler: () => void) => void;
 
 /**
  * 监听节点树变更
- * @param {HTMLElement} dom - 要监听的 DOM 节点
- * @param {Function} callback - 回调函数
- * @param {boolean} [includeElementChanged=true] - 是否包含表单元素的值变更
+ * @param dom - 要监听的 DOM 节点
+ * @param payload - 回调函数
+ * @param includeElementChanged - 是否包含表单元素的值变更
  * @returns {void}
  * @example
  * onDomTreeChange(container, () => console.log('changed'))
  */
-export declare const onDomTreeChange: (dom: HTMLElement, callback: () => void, includeElementChanged?: boolean) => void;
+export declare const onDomTreeChange: (dom: HTMLElement, payload: () => void, includeElementChanged?: boolean) => void;
 
 export declare const ONE_DAY: number;
 
@@ -1378,7 +1443,14 @@ export declare const onEvent: (event: string | symbol, handler: EventListenerOrE
 
 export declare const onEvents: (events: (string | symbol)[], handler: EventListenerOrEventListenerObject) => () => void;
 
-export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void, onHoverOut: () => void) => void;
+/**
+ * 绑定元素 hover 事件，返回解绑函数
+ * @param el - DOM 元素或选择器
+ * @param onHoverIn - 鼠标进入回调函数
+ * @param onHoverOut - 鼠标离开回调函数
+ * @returns 返回解绑函数
+ */
+export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void, onHoverOut: () => void) => () => void;
 
 /**
  * 非自关闭标签
@@ -1404,7 +1476,7 @@ export declare const parseUnit: (value: string | number, defaultUnit?: string) =
  * @example
  * postFiles('/api/upload', {avatar: fileObject})
  */
-export declare const postFiles: (url: string, fileMap: Record<string, File>, data?: any, option?: RequestOption) => Promise<any>;
+export declare const postFiles: (url: string, fileMap: Record<string, File>, data?: any, option?: RequestOption) => AbortablePromise<any>;
 
 /**
  * 发送 POST 请求并获取 JSON 响应
@@ -1415,7 +1487,7 @@ export declare const postFiles: (url: string, fileMap: Record<string, File>, dat
  * @example
  * postJson('/api/users', {name: 'John'}).then(data => console.log(data))
  */
-export declare const postJson: (url: string, data?: any, option?: RequestOption) => Promise<any>;
+export declare const postJson: (url: string, data?: any, option?: RequestOption) => AbortablePromise<any>;
 
 /**
  * 精度位数转小数表示法