minutool 1.0.18 → 1.0.20

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 请求
@@ -150,9 +150,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 +359,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 +422,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, selector: string, event: string, handler: (event: Event, target: HTMLElement) => void) => () => void;
+
 /**
  * 退出全屏模式
  * @returns {Promise<void>} 返回 Promise，退出全屏操作完成后 resolve
@@ -492,6 +501,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 +545,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 +632,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 +699,7 @@ export declare const isFirefox: () => boolean;
 /**
  * 检测元素是否可聚焦
  * @param {HTMLElement} el - DOM 元素
- * @returns {boolean} 如果元素可聚焦返回 true，否则返回 false
+ * @returns 如果元素可聚焦返回 true，否则返回 false
  * @example
  * isFocusable(inputElement) // true
  */
@@ -721,6 +746,11 @@ export declare const isLandscape: () => boolean;
  * 判断一个值是否为数字
  * @param val - 要判断的值
  * @returns 如果是数字返回 true，否则返回 false
+ * @example
+ * isNumberic(123) // true
+ * isNumberic('123.45') // true
+ * isNumberic('-123') // true
+ * isNumberic('210mm') // false
  */
 export declare const isNumberic: (val: any) => boolean;
 
@@ -1220,6 +1250,24 @@ export declare const mutationEffective: (dom: HTMLElement, option: MutationObser
  */
 export declare const nodeIndex: (node: HTMLElement) => number;
 
+/**
+ * 获取对象的键值对数组，代替 Object.entries，如果key是数字，则转换为数字类型
+ * @param obj - 要获取键值对的对象
+ * @returns 键值对数组
+ * @example
+ * objectEntries({ a: 1, b: 2 }) // [['a', 1], ['b', 2]]
+ */
+export declare const objectEntries: <T extends Record<string | number | symbol, any>>(obj: T) => [keyof T, T[keyof T]][];
+
+/**
+ * 从键值对数组创建对象，代替 Object.fromEntries，如果key是数字字符串，则转换为数字类型
+ * @param entries - 键值对数组
+ * @returns 创建的对象
+ * @example
+ * objectFromEntries([['a', 1], ['b', 2]]) // { a: 1, b: 2 }
+ */
+export declare const objectFromEntries: <T extends Record<string | number | symbol, any>>(entries: Iterable<readonly [string | number, T[keyof T]]>) => T;
+
 /**
  * 获取对象指定路径的值
  * @param obj - 对象
@@ -1233,22 +1281,15 @@ export declare const nodeIndex: (node: HTMLElement) => number;
 export declare function objectGet<T = any>(obj: any, path: string, defaultValue?: T): T;
 
 /**
- * 对象属性名转换（根据映射表重命名属性）
- * @param {Record<string, any>} obj - 源对象
- * @param {Record<string, string>} mapping - 属性名映射表
- * @returns {Record<string, any>} 返回转换后的对象
+ * 根据映射关系替换对象的键
+ * @param obj - 要替换键的对象
+ * @param mapping - 键映射关系，例如 { oldKey: 'newKey' }
+ * @returns 替换键后的新对象
  * @example
- * objectKeyMapping({a: 1, b: 2}, {a: 'x'}) // {x: 1, b: 2}
+ * objectKeyReplace({ a: 1, b: 2 }, { a: 'x' }) // { x: 1, b: 2 }
  */
 export declare const objectKeyReplace: (obj: Record<string, any>, mapping: Record<string, string>) => Record<string, any>;
 
-/**
- * 交换对象中的键值对
- * @param {Object} obj
- * @returns
- */
-export declare const objectKeyValSwap: (obj: object) => any;
-
 /**
  * 合并对象
  * @param target - 目标对象
@@ -1269,6 +1310,15 @@ export declare function objectMerge<T extends object>(target: T, ...sources: Par
  */
 export declare function objectSet(obj: any, path: string, value: any): void;
 
+/**
+ * 交换对象中的键值对
+ * @param obj - 要交换键值对的对象
+ * @returns 交换后的对象
+ * @example
+ * objectSwitchKV({a: 1, b: 2}) // {1: 'a', 2: 'b'}
+ */
+export declare const objectSwitchKV: (obj: object) => any;
+
 /**
  * 将对象转换为 URL 查询字符串
  * @param {Record<string, any>} data - 数据对象
@@ -1280,11 +1330,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 节点
@@ -1314,9 +1370,9 @@ 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;
 
@@ -1327,7 +1383,6 @@ export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void,
 /**
  * 非自关闭标签
  * https://www.w3schools.com/html/html_blocks.asp
- * @type {*[]}
  */
 export declare const PAIR_TAGS: string[];
 
@@ -1341,11 +1396,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})
  */
@@ -1353,10 +1408,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))
  */
@@ -1481,7 +1536,6 @@ export declare const regQuote: (str: string) => string;
 
 /**
  * 非内容可清理标签
- * @type {string[]}
  */
 export declare const REMOVABLE_TAGS: string[];
 
@@ -1503,8 +1557,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;
@@ -1531,7 +1588,6 @@ export declare const SCREEN_DPI: number;
 
 /**
  * 自关闭标签
- * @type {string[]}
  */
 export declare const SELF_CLOSING_TAGS: string[];
 
@@ -1625,14 +1681,14 @@ export declare const stripSlashes: (str: string) => string;
 export declare const strToPascalCase: (str: string, capitalize_first?: boolean) => string;
 
 /**
- * 兼容方式获取svg的BBox，避免Firefox获取svg尺寸时，额外考虑了父容器的zoom
- * @param {SVGSVGElement} svg
- * @returns {DOMRect}
- * @returns {DOMRect.width} 单位px
- * @returns {DOMRect.height} 单位px
- * @see https://stackoverflow.com/questions/60814803/getboundingbox-of-svg-element-in-firefox
+ * 获取 SVG 的尺寸（像素单位）
+ * 优先级：width/height 属性 > viewBox > getBoundingClientRect
+ * @param {SVGSVGElement} svg - SVG 元素
+ * @returns {DOMRect} 返回包含像素单位的尺寸对象
+ * @returns {number} DOMRect.width - 宽度（像素）
+ * @returns {number} DOMRect.height - 高度（像素）
  */
-export declare const svgGetBBox: (svg: SVGSVGElement) => DOMRect;
+export declare const svgGetDimension: (svg: SVGSVGElement) => [number, number];
 
 /**
  * svg 对象转换为图片对象
@@ -1712,6 +1768,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 - 源字符串
@@ -1749,6 +1812,16 @@ export declare function truncate(str: string, length: number, suffix?: string):
  */
 export declare const unescapeHtml: (html: string) => string;
 
+/**
+ * 单位转换工具，支持px、mm、cm、in等常见单位之间的转换
+ * @returns {Number} 转换后的数值（以目标单位为准）
+ */
+export declare const unitConvert: (value: string | number, toUnit: string, extOption?: {
+    dpi?: number;
+    fontSize?: number | null;
+    lineHeight?: number | null;
+}) => number;
+
 /**
  * URL 转 Base64 Data URL 数据缓存
  * @param {string} url - 文件 URL