minutool 1.0.19 → 1.0.21

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 /**
  * 拓展原生 Fetch API 实现可中止的请求，支持超时设置
- * @param {string} url - 请求 URL
- * @param {RequestInit} [fetchOption={}] - fetch请求选项，包括 method、headers、body 等
- * @param {number} [timeout=0] - 超时时间，单位毫秒，0 表示不设置超时
- * @returns {AbortablePromise<any>} 返回可中止的 Promise 对象
+ * @param url - 请求 URL
+ * @param fetchOption - fetch请求选项，包括 method、headers、body 等
+ * @param timeout - 超时时间，单位毫秒，0 表示不设置超时
+ * @returns AbortablePromise<any> 返回可中止的 Promise 对象
  * @example
  * const req = abortableFetch('/api/data');
- * req.abort('cancled'); // 中止请求
+ * req.abort('canceled'); // 中止请求
  */
-export declare const abortableFetch: (url: string, fetchOption?: RequestInit, timeout?: number) => AbortablePromise<any>;
+export declare const abortableFetch: (url: string, fetchOption?: RequestOption) => AbortablePromise<any>;
 
 /**
  * 可中止的 Fetch 请求
@@ -129,6 +129,54 @@ export declare const base64UrlSafeEncode: (text: string) => string;
  */
 export declare const between: (val: number, min: number, max: number, includeEqual?: boolean) => boolean;
 
+/**
+ * 绑定点击事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param callback - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindClick: (element: HTMLElement | string, callback: (event: Event) => void) => () => void;
+
+/**
+ * 绑定DOM事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param eventName - 事件名称
+ * @param callback - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindDomEvent: (element: HTMLElement | string, eventName: string, callback: (event: Event) => void) => () => void;
+
+/**
+ * 绑定双击事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param callback - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindDoubleClick: (element: HTMLElement | string, callback: (event: Event) => void) => () => void;
+
+/**
+ * 绑定键盘按键按下事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param callback - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindKeyDown: (element: HTMLElement | string, callback: (event: Event) => void) => () => void;
+
+/**
+ * 绑定键盘按键抬起事件，并返回一个解绑函数
+ * @param element - 要绑定事件的元素
+ * @param callback - 事件回调函数
+ * @returns 解绑函数
+ */
+export declare const bindKeyUp: (element: HTMLElement | string, callback: (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 对象
@@ -150,9 +198,8 @@ export declare const blobToDataUri: (blob: Blob) => Promise<string>;
 /**
  * 块元素
  * 用大写定义，方便直接匹配 node.tagName
- * @type {string[]}
  */
-export declare const BLOCK_TAGS: string[];
+export declare const BLOCK_TAGS: readonly ["ADDRESS", "ARTICLE", "ASIDE", "BLOCKQUOTE", "CANVAS", "DD", "DIV", "DL", "DT", "FIELDSET", "FIGCAPTION", "FIGURE", "FOOTER", "FORM", "H1", "H2", "H3", "H4", "H5", "H6", "HEADER", "HR", "LI", "MAIN", "NAV", "NOSCRIPT", "OL", "P", "PRE", "SECTION", "TABLE", "TFOOT", "UL", "VIDEO"];
 
 /**
  * 构建 HTML Input:hidden 标签
@@ -360,8 +407,8 @@ export declare const disabled: (el: HTMLElement | string, disabledClass?: string
 
 /**
  * 发布事件，event 可以是字符串或 Symbol，detail 是事件详情
- * @param {string | symbol} event 事件名称
- * @param {any} detail 事件详情
+ * @param event 事件名称
+ * @param detail 事件详情
  */
 declare const dispatchEvent_2: (event: string | symbol, detail?: any) => void;
 export { dispatchEvent_2 as dispatchEvent }
@@ -423,6 +470,16 @@ export declare const escapeAttr: (s: string, preserveCR?: string) => string;
  */
 export declare const escapeHtml: (str: string, tabSize?: number, allowLineBreaker?: boolean) => string;
 
+/**
+ * 事件委托，parent 是父元素，selector 是子元素选择器，event 是事件名称，handler 是事件处理函数
+ * @param parent 父元素
+ * @param selector 子元素选择器
+ * @param event 事件名称
+ * @param handler 事件处理函数, 参数为事件对象和匹配的子元素 (event, target)
+ * @return 返回一个取消事件委托的函数
+ */
+export declare const eventDelegate: (parent: HTMLElement | string, selector: string, event: string, handler: (event: Event, target: HTMLElement) => void) => () => void;
+
 /**
  * 退出全屏模式
  * @returns {Promise<void>} 返回 Promise，退出全屏操作完成后 resolve
@@ -492,6 +549,17 @@ export declare const floatVal: (str: any, defaultVal?: number) => number;
  */
 export declare const formatDate: (format: string, date?: Date | number | string | null) => string;
 
+/**
+ * 格式化文件大小
+ * @param bytes 文件大小（字节数）
+ * @param toUnit 目标单位（B/KB/MB/GB/TB/PB）
+ * @param decimalPlaces 小数位数，默认为 2
+ * @return 转换后的数值
+ * @example
+ * formatSize(1024) // 1
+ */
+export declare const formatSize: (bytes: number, toUnit?: string, decimalPlaces?: number) => number;
+
 /**
  * 获取元素的位置（相对于视口）
  * @param {HTMLElement} el - DOM 元素
@@ -525,10 +593,10 @@ export declare const getDomDimension: (dom: HTMLElement) => {
 
 /**
  * 发送 GET 请求并获取 JSON 响应
- * @param {string} url - 请求 URL
- * @param {any} [data=null] - 请求数据
- * @param {RequestOption} [option={}] - 请求选项
- * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @param url - 请求 URL
+ * @param data - 请求数据
+ * @param option - 请求选项
+ * @returns Promise<any> 返回解析后的 JSON 数据
  * @example
  * getJson('/api/users').then(data => console.log(data))
  */
@@ -612,12 +680,17 @@ export declare const highlightText: (text: string, kw: string, replaceTpl?: stri
 
 /**
  * 将 HTML 转换为纯文本（移除所有标签和样式）
- * @param {string} html - HTML 字符串
- * @returns {string} 返回纯文本
+ * @param html - HTML 字符串
+ * @param option - 转换选项
+ * @returns 返回纯文本
  * @example
  * html2Text('<p>Hello <b>World</b></p>') // 'Hello World'
  */
-export declare const html2Text: (html: string) => string;
+export declare const html2Text: (html: string, option?: {
+    keepLineBreak?: boolean;
+    imgReplacer?: string | ((src: string, alt: string) => string);
+    videoReplacer?: string | ((src: string, alt: string) => string);
+}) => string;
 
 /**
  * 通过 Image 元素获取 Base64 数据
@@ -674,7 +747,7 @@ export declare const isFirefox: () => boolean;
 /**
  * 检测元素是否可聚焦
  * @param {HTMLElement} el - DOM 元素
- * @returns {boolean} 如果元素可聚焦返回 true，否则返回 false
+ * @returns 如果元素可聚焦返回 true，否则返回 false
  * @example
  * isFocusable(inputElement) // true
  */
@@ -821,8 +894,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;
 
@@ -1305,11 +1378,17 @@ export declare const objToQuery: (data: Record<string, any>) => string;
 
 /**
  * 取消订阅事件，event 可以是字符串或 Symbol，handler 是事件处理函数
- * @param {string | symbol} event 事件名称
- * @param {Function} handler 事件处理函数
+ * @param event 事件名称
+ * @param handler 事件处理函数
  */
 export declare const offEvent: (event: string | symbol, handler: EventListenerOrEventListenerObject) => void;
 
+/**
+ * 文档就绪事件，handler 是文档就绪时的回调函数
+ * @param handler 文档就绪时的回调函数
+ */
+export declare const onDocReady: (handler: () => void) => void;
+
 /**
  * 监听节点树变更
  * @param {HTMLElement} dom - 要监听的 DOM 节点
@@ -1339,20 +1418,26 @@ export declare const ONE_YEAR366: number;
 
 /**
  * 订阅事件，event 可以是字符串或 Symbol，handler 是事件处理函数
- * @param {string | symbol} event 事件名称
- * @param {Function} handler 事件处理函数
- * @return {Function} 返回一个取消订阅的函数
+ * @param event 事件名称
+ * @param handler 事件处理函数
+ * @return 返回一个取消订阅的函数
  */
 export declare const onEvent: (event: string | symbol, handler: EventListenerOrEventListenerObject) => () => void;
 
 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;
 
 /**
  * 非自关闭标签
  * https://www.w3schools.com/html/html_blocks.asp
- * @type {*[]}
  */
 export declare const PAIR_TAGS: string[];
 
@@ -1366,11 +1451,11 @@ export declare const parseUnit: (value: string | number, defaultUnit?: string) =
 
 /**
  * 上传文件
- * @param {string} url - 请求 URL
- * @param {Record<string, File>} fileMap - 文件对象映射
- * @param {any} [data=null] - 额外的表单数据
- * @param {RequestOption} [option={}] - 请求选项
- * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @param url - 请求 URL
+ * @param fileMap - 文件对象映射
+ * @param data - 额外的表单数据
+ * @param option - 请求选项
+ * @returns Promise<any> 返回解析后的 JSON 数据
  * @example
  * postFiles('/api/upload', {avatar: fileObject})
  */
@@ -1378,10 +1463,10 @@ export declare const postFiles: (url: string, fileMap: Record<string, File>, dat
 
 /**
  * 发送 POST 请求并获取 JSON 响应
- * @param {string} url - 请求 URL
- * @param {any} [data=null] - 请求数据
- * @param {RequestOption} [option={}] - 请求选项
- * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @param url - 请求 URL
+ * @param data - 请求数据
+ * @param option - 请求选项
+ * @returns Promise<any> 返回解析后的 JSON 数据
  * @example
  * postJson('/api/users', {name: 'John'}).then(data => console.log(data))
  */
@@ -1506,7 +1591,6 @@ export declare const regQuote: (str: string) => string;
 
 /**
  * 非内容可清理标签
- * @type {string[]}
  */
 export declare const REMOVABLE_TAGS: string[];
 
@@ -1528,8 +1612,11 @@ export declare const remove: (dom: HTMLElement | string) => Node | null;
  * @example
  * request('/api/data', null, {method: 'GET'})
  */
-export declare const request: (url: string, data: (BodyInit | null) | undefined, option: RequestOption) => AbortablePromise<Response>;
+export declare const request: (url: string, data: (BodyInit | null) | undefined, requestOption: RequestOption) => AbortablePromise<Response>;
 
+/**
+ * 扩展 RequestInit，添加 timeout 和其他自定义属性，timeout 用于设置请求超时时间，其他自定义属性可以直接添加到 headers 中
+ */
 declare interface RequestOption extends RequestInit {
     timeout?: number;
     [key: string]: any;
@@ -1556,7 +1643,6 @@ export declare const SCREEN_DPI: number;
 
 /**
  * 自关闭标签
- * @type {string[]}
  */
 export declare const SELF_CLOSING_TAGS: string[];
 
@@ -1737,6 +1823,13 @@ export declare const toggleDisabled: (el: HTMLElement | string, disabledClass?:
  */
 export declare const toggleFullScreen: (element: any) => Promise<unknown>;
 
+/**
+ * 触发HTML节点事件
+ * @param node HTML节点
+ * @param event 事件名称
+ */
+export declare const triggerDomEvent: (node: HTMLElement, event: string) => void;
+
 /**
  * 去除字符串首尾指定字符或空白
  * @param {string} str - 源字符串