minutool 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,75 +1,114 @@
 /**
- * 数组分块
- * @param {Array} list 数据
- * @param {Number} size 每块大小
- * @return {Array[]}
+ * 使用 Fetch API 实现可中止的请求，支持超时设置
+ * @param {string} url - 请求 URL
+ * @param {any} [options={}] - 请求选项，包括 method、headers、body、timeout 等
+ * @returns {AbortablePromise<any>} 返回可中止的 Promise 对象
+ * @example
+ * const req = abortableFetch('/api/data');
+ * req.abort(); // 中止请求
+ */
+export declare const abortableFetch: (url: string, options?: any) => AbortablePromise<any>;
+
+/**
+ * 可中止的 Fetch 请求
+ */
+export declare interface AbortablePromise<T> extends Promise<T> {
+    abort: () => void;
+}
+
+/**
+ * 将数组分割成指定大小的块
+ * @param {T[]} list - 源数组
+ * @param {number} size - 每块的大小
+ * @returns {T[][]} 分块后的二维数组
+ * @example
+ * arrayChunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
  */
 export declare const arrayChunk: <T = any>(list: T[], size: number) => T[][];
 
 /**
- * array_column
- * @param arr
- * @param col_name
- * @returns {Array}
+ * 从数组中提取指定列的值
+ * @param {T[]} arr - 源数组
+ * @param {keyof T} col_name - 列名（对象的键）
+ * @returns {any[]} 提取的列值数组
+ * @example
+ * arrayColumn([{id: 1, name: 'A'}, {id: 2, name: 'B'}], 'name') // ['A', 'B']
  */
 export declare const arrayColumn: <T = any>(arr: T[], col_name: keyof T) => any[];
 
 /**
  * 数组去重
- * @param {Array} arr
- * @returns {*}
+ * @param {T[]} arr - 源数组
+ * @returns {T[]} 去重后的数组
+ * @example
+ * arrayDistinct([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
  */
 export declare const arrayDistinct: <T = any>(arr: T[]) => T[];
 
 /**
- * array group
- * @param arr
- * @param by_key
- * @param limit limit one child
- * @returns {*}
+ * 按指定键对数组进行分组
+ * @param {T[]} arr - 源数组
+ * @param {keyof T} by_key - 分组依据的键
+ * @param {boolean} [limit] - 是否限制每组只保留一个元素
+ * @returns {Record<string, T[]> | Record<string, T>} 分组后的对象
+ * @example
+ * arrayGroup([{type: 'A', val: 1}, {type: 'A', val: 2}], 'type')
+ * // { A: [{type: 'A', val: 1}, {type: 'A', val: 2}] }
  */
 export declare const arrayGroup: <T extends Record<string, any>>(arr: T[], by_key: keyof T, limit?: boolean) => Record<string, T[]> | Record<string, T>;
 
 /**
- * @param arr
- * @param val
- * @return {string|null}
+ * 查找数组中指定值的索引
+ * @param {T[]} arr - 源数组
+ * @param {T} val - 要查找的值
+ * @returns {string|null} 返回索引字符串，未找到返回 null
+ * @example
+ * arrayIndex(['a', 'b', 'c'], 'b') // '1'
  */
 export declare const arrayIndex: <T = any>(arr: T[], val: T) => string | null;
 
 /**
- * 按照对象 KEY 排序
- * @param {Object} obj
- * @return {{}}
+ * 按照对象的键进行字母顺序排序
+ * @param {T} obj - 源对象
+ * @returns {T} 键排序后的对象
+ * @example
+ * arraySortByKey({c: 3, a: 1, b: 2}) // {a: 1, b: 2, c: 3}
  */
 export declare const arraySortByKey: <T extends Record<string, any>>(obj: T) => T;
 
 /**
  * 从数组末尾开始移除值为 falsy 的元素，直到遇到第一个 truthy 元素
- * @param arr 要处理的数组
- * @returns 处理后的数组
+ * @param {any[]} arr - 要处理的数组
+ * @returns {any[]} 处理后的数组
+ * @example
+ * arrayTrimTail([1, 2, 0, false, null]) // [1, 2]
  */
 export declare const arrayTrimTail: (arr: any[]) => any[];
 
 /**
- * base64 解码
- * @param {string} text
- * @returns {string}
+ * Base64 解码
+ * @param {string} text - Base64 编码的字符串
+ * @returns {string} 解码后的字符串
+ * @example
+ * base64Decode('SGVsbG8=') // 'Hello'
  */
 export declare const base64Decode: (text: string) => string;
 
 /**
- * text 转 base64
- * @param {String} text
- * @return {string}
- * @constructor
+ * 字符串转 Base64 编码
+ * @param {string} text - 要编码的字符串
+ * @returns {string} Base64 编码后的字符串
+ * @example
+ * Base64Encode('Hello') // 'SGVsbG8='
  */
 export declare const Base64Encode: (text: string) => string;
 
 /**
- * URL 安全模式进行 base64 编码
- * @param {String} text
- * @return {string}
+ * URL 安全模式进行 Base64 编码（替换 + 和 / 为 - 和 _）
+ * @param {string} text - 要编码的字符串
+ * @returns {string} URL 安全的 Base64 编码字符串
+ * @example
+ * base64UrlSafeEncode('test') // URL安全的Base64字符串
  */
 export declare const base64UrlSafeEncode: (text: string) => string;
 
@@ -84,12 +123,21 @@ export declare const base64UrlSafeEncode: (text: string) => string;
 export declare const between: (val: number, min: number, max: number, includeEqual?: boolean) => boolean;
 
 /**
- * 转换blob数据到base64
- * @param {Blob} blob
- * @returns {Promise<unknown>}
+ * 转换 Blob 数据到 Base64 Data URL
+ * @param {Blob} blob - Blob 对象
+ * @returns {Promise<unknown>} 返回 Base64 Data URL 字符串的 Promise
+ * @example
+ * blobToBase64(blob).then(base64 => console.log(base64))
  */
 export declare const blobToBase64: (blob: Blob) => Promise<unknown>;
 
+/**
+ * 将 Blob 转换为 Data URI
+ * @param {Blob} blob - Blob 对象
+ * @returns {Promise<string>} 返回 Data URI 字符串
+ * @example
+ * blobToDataUri(blob).then(uri => console.log(uri))
+ */
 export declare const blobToDataUri: (blob: Blob) => Promise<string>;
 
 /**
@@ -101,11 +149,20 @@ export declare const BLOCK_TAGS: string[];
 
 /**
  * 构建 HTML Input:hidden 标签
- * @param {Object} maps {key:value}
- * @return {string}
+ * @param {Record<string, any>} maps - 键值对对象
+ * @returns {string} 返回 HTML 字符串
+ * @example
+ * buildHtmlHidden({name: 'John', age: 30}) // '<input type="hidden" name="name" value="John"/>...'
  */
 export declare const buildHtmlHidden: (maps: Record<string, any>) => string;
 
+/**
+ * 构建 CSS 变量对象（自动添加 -- 前缀和 px 单位）
+ * @param {Record<string, number|string|undefined>} vars - CSS 变量对象
+ * @returns {Record<string, string>} 返回格式化后的 CSS 变量对象
+ * @example
+ * buildStyleVars({width: 100, color: 'red'}) // {'--width': '100px', '--color': 'red'}
+ */
 export declare const buildStyleVars: (vars: Record<string, number | string | undefined>) => Record<string, string>;
 
 /**
@@ -129,38 +186,52 @@ export declare function capitalize(str: string): string;
 
 /**
  * 清理对象中的 null 值
+ * @param {any} obj - 要清理的对象
+ * @param {boolean} [recursive=false] - 是否递归清理子对象
+ * @returns {any} 返回清理后的对象
+ * @example
+ * cleanNull({a: 1, b: null, c: {d: null}}, true) // {a: 1, c: {}}
  */
 export declare const cleanNull: (obj: any, recursive?: boolean) => any;
 
 /**
- * 计时（该方法采用timeout方式，不够精准
- * @param {Number} timeout
- * @param {Function} tickFunc
- * @param {Function} onFinish
+ * 倒计时函数（该方法采用 setTimeout 方式，不够精准）
+ * @param {number} timeout - 倒计时总秒数
+ * @param {Function} [tickFunc] - 每秒回调函数，接收剩余秒数作为参数
+ * @param {Function} [onFinish] - 倒计时结束回调函数
+ * @returns {void}
+ * @example
+ * countDown(10, (sec) => console.log(sec), () => console.log('done'))
  */
 export declare const countDown: (timeout: number, tickFunc?: (timeout: number) => void, onFinish?: () => void) => void;
 
 /**
- * 创建HTML节点
- * @param {String} html
- * @param {HTMLElement|null} parentNode 父级节点
- * @returns {HTMLElement|HTMLElement[]}
+ * 创建 HTML 节点
+ * @param {string} html - HTML 字符串
+ * @param {HTMLElement|null} [parentNode=null] - 父级节点，如果提供则自动添加到父节点
+ * @returns {Node|Node[]} 返回创建的节点，单个或多个
+ * @example
+ * createDomByHtml('<div>Hello</div>')
  */
 export declare const createDomByHtml: (html: string, parentNode?: HTMLElement | null) => Node | Node[];
 
 /**
- * CSS 选择器转义
- * @param {String} str
- * @returns {String}
+ * CSS 选择器转义（处理特殊字符）
+ * @param {string} str - 要转义的字符串
+ * @returns {string} 转义后的字符串
+ * @example
+ * cssSelectorEscape('my#id') // 'my\\#id'
  */
 export declare const cssSelectorEscape: (str: string) => string;
 
 /**
- * 中英文字符串截取（中文按照2个字符长度计算）
- * @param str
- * @param len
- * @param eclipse_text
- * @returns {*}
+ * 中英文字符串截取（中文按照 2 个字符长度计算）
+ * @param {string} str - 要截取的字符串
+ * @param {number} len - 截取长度
+ * @param {string} [eclipse_text='...'] - 省略符，默认为 '...'
+ * @returns {string} 返回截取后的字符串
+ * @example
+ * cutString('中文English', 6, '...') // '中文E...'
  */
 export declare const cutString: (str: string, len: number, eclipse_text?: string) => string;
 
@@ -181,13 +252,23 @@ export declare const DAY_TUESDAY = 2;
 export declare const DAY_WEDNESDAY = 3;
 
 /**
- * 在事件被触发n秒后再执行回调，如果在这n秒内又被触发，则重新计时。
- * @param {Function} fn
- * @param {Number} intervalMiSec
- * @return {(function(): void)|*}
+ * 防抖函数
+ * 在事件被触发 n 秒后再执行回调，如果在这 n 秒内又被触发，则重新计时。
+ * @param {Function} fn - 要防抖的函数
+ * @param {number} intervalMiSec - 间隔时间（毫秒）
+ * @returns {Function} 返回防抖后的函数
+ * @example
+ * const debounced = debounce(() => console.log('called'), 1000)
  */
 export declare const debounce: (fn: Function, intervalMiSec: number) => Function;
 
+/**
+ * 解码 HTML 实体（包括 script 和 HTML 标签过滤）
+ * @param {string} str - 包含 HTML 实体的字符串
+ * @returns {string} 返回解码后的字符串
+ * @example
+ * decodeHTMLEntities('&lt;div&gt;') // '<div>'
+ */
 export declare const decodeHTMLEntities: (str: string) => string;
 
 /**
@@ -200,8 +281,11 @@ export declare const decodeHTMLEntities: (str: string) => string;
 export declare function deepClone<T>(obj: T): T;
 
 /**
- * 删除cookie
- * @param name
+ * 删除 Cookie
+ * @param {string} name - Cookie 名称
+ * @returns {void}
+ * @example
+ * deleteCookie('username')
  */
 export declare const deleteCookie: (name: string) => void;
 
@@ -212,12 +296,21 @@ export declare const deleteCookie: (name: string) => void;
  */
 export declare const detectedPrecision: (...numbers: number[]) => number;
 
+/**
+ * 检测浏览器语言（支持完全匹配和前缀匹配）
+ * @param {string[]} supportedLngs - 支持的语言列表
+ * @returns {string} 返回匹配的语言或第一个支持的语言
+ * @example
+ * detectLanguage(['en', 'zh-CN', 'zh']) // '根据浏览器语言返回匹配的语言'
+ */
 export declare const detectLanguage: (supportedLngs: string[]) => any;
 
 /**
  * 计算数字位数
- * @param {Number} n
- * @returns
+ * @param {number} n - 要计算的数字
+ * @returns {number} 返回数字的位数
+ * @example
+ * digitCount(123) // 3
  */
 export declare const digitCount: (n: number) => number;
 
@@ -237,8 +330,11 @@ export declare const disabled: (el: HTMLElement | string, disabledClass?: string
 
 /**
  * 下载文件
- * @param {String} uri
- * @param {String} fileName
+ * @param {string} uri - 文件 URI（支持 Data URI 和普通 URL）
+ * @param {string} fileName - 保存的文件名
+ * @returns {void}
+ * @example
+ * downloadFile('data:text/plain;base64,SGVsbG8=', 'hello.txt')
  */
 export declare const downloadFile: (uri: string, fileName: string) => void;
 
@@ -251,37 +347,49 @@ export declare const enabled: (el: HTMLElement | string, disabledClass?: string)
 
 /**
  * 进入全屏模式
- * @param {HTMLElement} element
+ * @param {HTMLElement} element - 要全屏显示的元素
+ * @returns {Promise<void>} 返回 Promise，全屏操作完成后 resolve
+ * @throws {string} 如果浏览器不支持全屏，抛出错误
+ * @example
+ * enterFullScreen(document.body)
  */
 export declare const enterFullScreen: (element: any) => Promise<void>;
 
 /**
- * HTML实例转字符串
- * @param {string} entity
- * @returns {string}
+ * HTML 实体转字符串
+ * @param {string} entity - HTML 实体字符串（如 &#72;&#101;&#108;&#108;&#111;）
+ * @returns {string} 返回解码后的字符串
+ * @example
+ * entityToString('&#72;&#101;') // 'He'
  */
 export declare const entityToString: (entity: string) => string;
 
 /**
- * 转义HTML到属性值
- * @param {String} s
- * @param preserveCR
- * @returns {string}
+ * 转义 HTML 到属性值（处理属性中的特殊字符）
+ * @param {string} s - 要转义的字符串
+ * @param {string} [preserveCR=''] - 是否保留回车符
+ * @returns {string} 返回转义后的字符串
+ * @example
+ * escapeAttr('Hello "World"') // 'Hello &quot;World&quot;'
  */
 export declare const escapeAttr: (s: string, preserveCR?: string) => string;
 
 /**
- * 转义HTML
- * @param {string} str
- * @param {Number} tabSize tab宽度，如果设置为0，表示去除tab
- * @param {Boolean} allowLineBreaker 是否允许换行
- * @returns {string}
+ * 转义 HTML（将特殊字符转换为 HTML 实体）
+ * @param {string} str - 要转义的字符串
+ * @param {number} [tabSize=2] - Tab 宽度，如果设置为 0，表示去除 tab
+ * @param {boolean} [allowLineBreaker=true] - 是否允许换行
+ * @returns {string} 返回转义后的 HTML
+ * @example
+ * escapeHtml('<div>Hello</div>') // '&lt;div&gt;Hello&lt;/div&gt;'
  */
 export declare const escapeHtml: (str: string, tabSize?: number, allowLineBreaker?: boolean) => string;
 
 /**
- * 退出全屏
- * @returns {Promise<void>}
+ * 退出全屏模式
+ * @returns {Promise<void>} 返回 Promise，退出全屏操作完成后 resolve
+ * @example
+ * exitFullScreen()
  */
 export declare const exitFullScreen: () => Promise<void>;
 
@@ -295,57 +403,80 @@ export declare const exitFullScreen: () => Promise<void>;
 export declare const extract: (es_template: string, params: Record<string, any>) => string;
 
 /**
- * 将文件转换为 Base64 data URL
+ * 将文件转换为 Base64 Data URI
  * 支持 File/Blob 对象，或字符串 URL（http(s)/相对/blob:）
- * @param {File|Blob|String} file
- * @returns {Promise<String|null>} 返回 data URL 字符串，失败返回 null
+ * @param {File|Blob|string} file - 文件对象或 URL 字符串
+ * @returns {Promise<string|null>} 返回 Data URL 字符串，失败返回 null
+ * @example
+ * fileToBase64DataUri(file).then(uri => console.log(uri))
  */
 export declare const fileToBase64DataUri: (file: File | Blob | string) => Promise<string | null>;
 
 /**
- * 通过选择器查找子节点（强制添加 :scope来约束必须是子节点）
- * @param {String} selector
- * @param {Node} parent
- * @return {Node[]}
+ * 通过选择器查找子节点（强制添加 :scope 来约束必须是子节点）
+ * @param {string|HTMLElement|HTMLElement[]|NodeList|HTMLCollection} selector - 选择器或 DOM 元素
+ * @param {Document|HTMLElement} [parent=document] - 父节点，默认为 document
+ * @returns {HTMLElement[]} 返回查找到的所有元素数组
+ * @example
+ * findAll('.item', container)
  */
 export declare const findAll: (selector: string | HTMLElement | HTMLElement[] | NodeList | HTMLCollection, parent?: Document | HTMLElement) => HTMLElement[];
 
 /**
- * @param {String|Object} selector 选择器，如果是Object，则直接返回Object
- * @param {Node} parent
- * @return {Node}
+ * 通过选择器查找单个节点
+ * @param {string|HTMLElement} selector - 选择器，如果是 HTMLElement，则直接返回
+ * @param {Document|HTMLElement} [parent=document] - 父节点，默认为 document
+ * @returns {HTMLElement} 返回查找到的元素
+ * @example
+ * findOne('.item')
  */
 export declare const findOne: (selector: string | HTMLElement, parent?: Document | HTMLElement) => HTMLElement;
 
+/**
+ * 修复基本 URL（将相对路径转换为绝对 URL）
+ * @param {string} url - 要修复的 URL
+ * @param {string} baseUrl - 基本 URL
+ * @returns {string} 返回修复后的 URL
+ * @example
+ * fixBaseUrl('/path', 'https://example.com') // 'https://example.com/path'
+ */
 export declare const fixBaseUrl: (url: string, baseUrl: string) => string;
 
 /**
- * 格式化日期（以PHP方式格式化）
- * @param {String} format
- * @param {Object,Number,String} date 日期，可以是日期对象、毫秒数或者日期字符串，缺省为今天
- * @return {String}
+ * 格式化日期（以 PHP 方式格式化）
+ * @param {string} format - 格式化字符串（支持 PHP date 函数的格式）
+ * @param {Date|number|string|null} [date=null] - 日期，可以是日期对象、毫秒数或者日期字符串，缺省为今天
+ * @returns {string} 返回格式化后的日期字符串
+ * @example
+ * formatDate('Y-m-d H:i:s') // '2024-03-11 15:30:00'
  */
 export declare const formatDate: (format: string, date?: Date | number | string | null) => string;
 
 /**
- * 获取元素的位置(相对于视口)
- * @param {HTMLElement} el
- * @returns
+ * 获取元素的位置（相对于视口）
+ * @param {HTMLElement} el - DOM 元素
+ * @param {boolean} [autoFixInvisible=false] - 是否自动修正隐藏元素无法测量的 bug
+ * @returns {RectObject} 返回元素的位置和尺寸信息
+ * @example
+ * getBoundingClientRect(element) // {top: 100, left: 50, width: 200, height: 100, ...}
  */
 export declare const getBoundingClientRect: (el: HTMLElement, autoFixInvisible?: boolean) => RectObject;
 
 /**
- * 获取cookie
- * @param {String} name
- * @returns {string|null}
+ * 获取 Cookie
+ * @param {string} name - Cookie 名称
+ * @returns {string|null} 返回 Cookie 值，未找到返回 null
+ * @example
+ * getCookie('username') // 'john'
  */
 export declare const getCookie: (name: string) => string | null;
 
 /**
- * 获取对象宽、高
- * 通过设置 visibility 方式进行获取
- * @param {HTMLElement} dom
- * @return {{width: number, height: number}}
+ * 获取对象宽、高（通过设置 visibility 方式进行获取）
+ * @param {HTMLElement} dom - DOM 元素
+ * @returns {{width: number, height: number}} 返回元素的宽度和高度
+ * @example
+ * getDomDimension(element) // {width: 100, height: 50}
  */
 export declare const getDomDimension: (dom: HTMLElement) => {
     width: number;
@@ -353,62 +484,111 @@ export declare const getDomDimension: (dom: HTMLElement) => {
 };
 
 /**
- * get node xpath
- * @param el
- * @return {String}
+ * 发送 GET 请求并获取 JSON 响应
+ * @param {string} url - 请求 URL
+ * @param {any} [data=null] - 请求数据
+ * @param {RequestOption} [option={}] - 请求选项
+ * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @example
+ * getJson('/api/users').then(data => console.log(data))
+ */
+export declare const getJson: (url: string, data?: any, option?: RequestOption) => Promise<any>;
+
+/**
+ * 获取节点的 XPath
+ * @param {HTMLElement|null} el - DOM 元素
+ * @returns {string|null} 返回 XPath 字符串，失败返回 null
+ * @example
+ * getNodeXPath(element) // '/html[1]/body[1]/div[1]'
  */
 export declare const getNodeXPath: (el: HTMLElement | null) => string | null;
 
 /**
- * 获取u8字符串长度(一个中文字按照3个字数计算)
- * @param str
- * @returns {number}
+ * 获取 UTF-8 字符串长度（一个中文字按照 3 个字数计算）
+ * @param {string} str - 要计算的字符串
+ * @returns {number} 返回字符串长度
+ * @example
+ * getUTF8StrLen('中文') // 6
  */
 export declare const getUTF8StrLen: (str: string) => number;
 
+/**
+ * 获取日期所在周数（ISO 8601 标准）
+ * @param {Date} date - 日期对象
+ * @returns {number} 返回周数
+ * @example
+ * getWeekNumber(new Date('2024-03-11')) // 11
+ */
+export declare const getWeekNumber: (date: Date) => number;
+
 /** 黄金分割比 0.618 **/
 export declare const GOLDEN_RATIO: number;
 
+/**
+ * 生成全局唯一 ID
+ * @param {string} [prefix=''] - ID 前缀
+ * @returns {string} 返回唯一 ID
+ * @example
+ * guid('user') // 'guid_user123_1'
+ */
 export declare const guid: (prefix?: string) => string;
 
 /**
- * 隐藏节点（通过设置display:none方式）
- * @param {Node|String} dom
+ * 隐藏节点（通过设置 display:none 方式）
+ * @param {HTMLElement|string} dom - DOM 元素或选择器
+ * @returns {void}
+ * @example
+ * hide('#myElement')
  */
 export declare const hide: (dom: HTMLElement | string) => void;
 
 /**
- * 高亮文本
- * @param {String} text 文本
- * @param {String} kw 关键字
- * @param {String} replaceTpl 替换模板
- * @returns {void|string|*}
+ * 高亮文本（将关键字用指定模板包裹）
+ * @param {string} text - 原始文本
+ * @param {string} kw - 关键字
+ * @param {string} [replaceTpl='<span class="matched">%s</span>'] - 替换模板，%s 为占位符
+ * @returns {string} 返回高亮后的 HTML
+ * @example
+ * highlightText('Hello World', 'World') // 'Hello <span class="matched">World</span>'
  */
 export declare const highlightText: (text: string, kw: string, replaceTpl?: string) => string;
 
 /**
- * Convert html to plain text
- * @param {String} html
- * @returns {string}
+ * 将 HTML 转换为纯文本（移除所有标签和样式）
+ * @param {string} html - HTML 字符串
+ * @returns {string} 返回纯文本
+ * @example
+ * html2Text('<p>Hello <b>World</b></p>') // 'Hello World'
  */
 export declare const html2Text: (html: string) => string;
 
 /**
- * 通过 Image 获取base64数据
- * @param img
- * @returns {string|string|*|string|null}
+ * 通过 Image 元素获取 Base64 数据
+ * @param {HTMLImageElement} img - 图片元素
+ * @returns {string|null} 返回 Base64 Data URL，失败返回 null
+ * @example
+ * imgToBase64(imageElement) // 'data:image/png;base64,...'
  */
 export declare const imgToBase64: (img: HTMLImageElement) => string | null;
 
 /**
  * 在头部插入样式
- * @param {String} styleSheetStr 样式代码
- * @param {String} id 样式ID，如果提供ID，将会检测是否已经插入，可以避免重复插入
- * @param {Document} doc 文档上下文
- * @return {HTMLStyleElement}
+ * @param {string} styleSheetStr - 样式代码
+ * @param {string} [id=''] - 样式 ID，如果提供 ID，将会检测是否已经插入，可以避免重复插入
+ * @param {Document} [doc=document] - 文档上下文
+ * @returns {HTMLStyleElement|null} 返回创建的 style 元素
+ * @example
+ * insertStyleSheet('.test { color: red; }', 'my-style')
  */
 export declare const insertStyleSheet: (styleSheetStr: string, id?: string, doc?: Document) => HTMLStyleElement | null;
 
+/**
+ * 检测值是否为 BodyInit 可接受的类型
+ * @param {any} value - 要检测的值
+ * @returns {boolean} 如果是 BodyInit 可接受的类型返回 true，否则返回 false
+ */
+export declare const isBodyInit: (value: any) => value is BodyInit;
+
 /**
  * 判断对象是否为空
  * @param obj - 要判断的对象
@@ -419,41 +599,83 @@ export declare const insertStyleSheet: (styleSheetStr: string, id?: string, doc?
  */
 export declare function isEmptyObject(obj: object): boolean;
 
+/**
+ * 检测是否为 Firefox 浏览器
+ * @returns {boolean} 如果是 Firefox 浏览器，返回 true，否则返回 false
+ * @example
+ * isFirefox() // false
+ */
+export declare const isFirefox: () => boolean;
+
+/**
+ * 检测元素是否可聚焦
+ * @param {HTMLElement} el - DOM 元素
+ * @returns {boolean} 如果元素可聚焦返回 true，否则返回 false
+ * @example
+ * isFocusable(inputElement) // true
+ */
 export declare const isFocusable: (el: HTMLElement) => boolean;
 
+/**
+ * 检测是否为函数
+ * @param {any} value - 要检测的值
+ * @returns {boolean} 如果是函数返回 true，否则返回 false
+ * @example
+ * isFunction(() => {}) // true
+ */
 export declare const isFunction: (value: any) => boolean;
 
 /**
  * 检测是否正在全屏
- * @returns {boolean}
+ * @returns {boolean} 如果当前正在全屏模式，返回 true，否则返回 false
+ * @example
+ * isInFullScreen() // false
  */
 export declare const isInFullScreen: () => boolean;
 
 /**
  * 判断字符串是否符合 JSON 标准
- * @param {String} json
- * @returns {boolean}
+ * @param {string} json - 要检测的字符串
+ * @returns {boolean} 如果是有效 JSON 返回 true，否则返回 false
+ * @example
+ * isJSON('{"name":"John"}') // true
  */
 export declare const isJSON: (json: string) => boolean;
 
+/**
+ * 检测字符串是否为有效的 JSON
+ * @param {string} json - 要检测的字符串
+ * @returns {boolean} 如果是有效 JSON 返回 true，否则返回 false
+ * @example
+ * isJson('{"name":"John"}') // true
+ */
 export declare const isJson: (json: string) => boolean;
 
 /**
- * 检测目标是否为 Object
- * @param {*} item
- * @returns {boolean}
+ * 检测目标是否为 Object（非数组的对象）
+ * @param {any} item - 要检测的对象
+ * @returns {boolean} 如果是对象返回 true，否则返回 false
+ * @example
+ * isObject({}) // true
+ * isObject([]) // false
  */
 export declare const isObject: (item: any) => boolean;
 
 /**
- * 检测对象是否为Promise对象
- * @param {*} obj
- * @returns {boolean}
+ * 检测对象是否为 Promise 对象
+ * @param {any} obj - 要检测的对象
+ * @returns {boolean} 如果是 Promise 返回 true，否则返回 false
+ * @example
+ * isPromise(Promise.resolve()) // true
  */
 export declare const isPromise: (obj: any) => boolean;
 
 /**
  * 检测是否为 URL（不包含 blob: data: file: 等协议）
+ * @param {string} str - 要检测的字符串
+ * @returns {boolean} 如果是 URL 返回 true，否则返回 false
+ * @example
+ * isUrl('https://example.com') // true
  */
 export declare const isUrl: (str: string) => boolean;
 
@@ -487,17 +709,33 @@ export declare const keepRectInContainer: (objDim: Dimension, ctnDim?: Dimension
 };
 
 /**
- * 挂载css文件
- * @param {String} file
- * @param {Boolean} forceReload 是否强制重新挂载，缺省不重复挂载
+ * 限制数值在指定范围内
+ * @param {number} num - 要限制的数值
+ * @param {number} min - 最小值
+ * @param {number} max - 最大值
+ * @returns {number} 返回限制后的数值
+ * @example
+ * limit(150, 0, 100) // 100
+ */
+export declare const limit: (num: number, min: number, max: number) => number;
+
+/**
+ * 挂载 CSS 文件
+ * @param {string} file - CSS 文件路径
+ * @param {boolean} [forceReload=false] - 是否强制重新挂载，缺省不重复挂载
+ * @returns {Promise<void>} 返回 Promise，加载完成后 resolve
+ * @example
+ * loadCss('/styles/theme.css')
  */
 export declare const loadCss: (file: string, forceReload?: boolean) => Promise<void>;
 
 /**
- * 加载script脚本
- * @param {String} src 脚本地址
- * @param {Boolean} forceReload 是否强制重新加载，缺省为去重加载
- * @return {Promise}
+ * 加载 Script 脚本
+ * @param {string} src - 脚本地址
+ * @param {boolean} [forceReload=false] - 是否强制重新加载，缺省为去重加载
+ * @returns {Promise<void>} 返回 Promise，加载完成后 resolve
+ * @example
+ * loadScript('/scripts/lib.js')
  */
 export declare const loadScript: (src: string, forceReload?: boolean) => Promise<void>;
 
@@ -508,6 +746,15 @@ export declare const loadScript: (src: string, forceReload?: boolean) => Promise
  */
 export declare const lockElementInteraction: (el: HTMLElement | string, payload: (reset: () => void) => void) => void;
 
+/**
+ * 计算字符串的 MD5 哈希值
+ * @param {string} string - 要计算 MD5 的字符串
+ * @param {string} [key] - HMAC 密钥（可选）
+ * @param {boolean} [raw] - 是否返回原始字符串，默认返回十六进制字符串
+ * @returns {string} 返回 MD5 哈希值
+ * @example
+ * md5('Hello World') // 'b10a8db164e0754105b7a99be72e3fe5'
+ */
 export declare const md5: (string: string, key?: string, raw?: boolean) => string;
 
 /**
@@ -820,38 +1067,77 @@ export declare const MIME_EXTENSION_MAP: {
     zip: string;
 };
 
+export declare const MIME_FORM = "application/x-www-form-urlencoded";
+
+export declare const MIME_HTML = "text/html";
+
+export declare const MIME_JSON = "application/json";
+
+export declare const MIME_MULTIPART = "multipart/form-data";
+
+export declare const MIME_TEXT = "text/plain";
+
+/**
+ * 将 mm 转换为磅（Point）
+ * @param {number} mm - 毫米值
+ * @returns {number} 返回磅值
+ * @example
+ * mmToPt(1) // 2.83
+ */
+export declare const mmToPt: (mm: number) => number;
+
 /**
  * 毫米转换成像素
- * @param {float} dimension
- * @param {int} dpi
- * @returns int
+ * @param {number} dimension - 毫米值
+ * @param {number} [dpi=STAND_DPI] - DPI 值，默认为标准 DPI (96)
+ * @returns {number} 返回像素值
+ * @example
+ * mmToPx(25.4) // 96
  */
 export declare const mmToPx: (dimension: number, dpi?: number) => number;
 
+/**
+ * 将 mm 转换为 TWIP（Twentieth of a Point）
+ * @param {number} mm - 毫米值
+ * @returns {number} 返回 TWIP 值
+ * @example
+ * mmToTwip(1) // 57
+ */
+export declare const mmToTwip: (mm: number) => number;
+
 export declare const MONTH_NAMES_CN: string[];
 
 export declare const MONTH_NAMES_SHORT_CN: string[];
 
 export declare const MONTH_NOW: number;
 
+/**
+ * 毫秒转换为“时分秒前”格式
+ * @param {number} ms - 毫秒数
+ * @returns {string} 返回格式化后的字符串
+ * @example
+ * msToHMS(3661000) // '1小时0分钟1秒前'
+ */
 export declare const msToHMS: (ms: number) => string;
 
 /**
- * 更低占用执行mutation监听，支持指定最小间隔时间执行回调
- * @param {Node} dom
- * @param {Object} option
- * @param {Boolean} option.attributes
- * @param {Boolean} option.subtree
- * @param {Boolean} option.childList
- * @param {Function} payload
- * @param {Number} minInterval 执行回调最小间隔时间（毫秒）
+ * 更低占用执行 mutation 监听，支持指定最小间隔时间执行回调
+ * @param {HTMLElement} dom - 要监听的 DOM 节点
+ * @param {MutationObserverInit} option - MutationObserver 配置选项
+ * @param {Function} payload - 回调函数，接收 MutationObserver 实例作为参数
+ * @param {number} [minInterval=10] - 执行回调最小间隔时间（毫秒）
+ * @returns {void}
+ * @example
+ * mutationEffective(dom, {attributes: true, childList: true}, (obs) => console.log('changed'))
  */
 export declare const mutationEffective: (dom: HTMLElement, option: MutationObserverInit, payload: (obs: MutationObserver) => void, minInterval?: number) => void;
 
 /**
- * 获取当前节点在父结点中的索引号
- * @param node
- * @return {number}
+ * 获取当前节点在父节点中的索引号
+ * @param {HTMLElement} node - DOM 节点
+ * @returns {number} 返回索引号，如果没有父节点返回 -1
+ * @example
+ * nodeIndex(element) // 2
  */
 export declare const nodeIndex: (node: HTMLElement) => number;
 
@@ -868,10 +1154,12 @@ export declare const nodeIndex: (node: HTMLElement) => number;
 export declare function objectGet<T = any>(obj: any, path: string, defaultValue?: T): T;
 
 /**
- * 对象属性名转换
- * @param {Object} obj
- * @param {Object} mapping
- * @return {{}}
+ * 对象属性名转换（根据映射表重命名属性）
+ * @param {Record<string, any>} obj - 源对象
+ * @param {Record<string, string>} mapping - 属性名映射表
+ * @returns {Record<string, any>} 返回转换后的对象
+ * @example
+ * objectKeyMapping({a: 1, b: 2}, {a: 'x'}) // {x: 1, b: 2}
  */
 export declare const objectKeyMapping: (obj: Record<string, any>, mapping: Record<string, string>) => Record<string, any>;
 
@@ -895,11 +1183,23 @@ export declare function objectMerge<T extends object>(target: T, ...sources: Par
  */
 export declare function objectSet(obj: any, path: string, value: any): void;
 
+/**
+ * 将对象转换为 URL 查询字符串
+ * @param {Record<string, any>} data - 数据对象
+ * @returns {string} 返回查询字符串
+ * @example
+ * objToQuery({name: 'John', age: 30}) // 'name=John&age=30'
+ */
+export declare const objToQuery: (data: Record<string, any>) => string;
+
 /**
  * 监听节点树变更
- * @param {Node} dom
- * @param {Function} callback
- * @param {Boolean} includeElementChanged 是否包含表单元素的值变更
+ * @param {HTMLElement} dom - 要监听的 DOM 节点
+ * @param {Function} callback - 回调函数
+ * @param {boolean} [includeElementChanged=true] - 是否包含表单元素的值变更
+ * @returns {void}
+ * @example
+ * onDomTreeChange(container, () => console.log('changed'))
  */
 export declare const onDomTreeChange: (dom: HTMLElement, callback: () => void, includeElementChanged?: boolean) => void;
 
@@ -919,6 +1219,8 @@ export declare const ONE_YEAR365: number;
 
 export declare const ONE_YEAR366: number;
 
+export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void, onHoverOut: () => void) => void;
+
 /**
  * 非自关闭标签
  * https://www.w3schools.com/html/html_blocks.asp
@@ -926,18 +1228,84 @@ export declare const ONE_YEAR366: number;
  */
 export declare const PAIR_TAGS: string[];
 
+/**
+ * 上传文件
+ * @param {string} url - 请求 URL
+ * @param {Record<string, File>} fileMap - 文件对象映射
+ * @param {any} [data=null] - 额外的表单数据
+ * @param {RequestOption} [option={}] - 请求选项
+ * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @example
+ * postFiles('/api/upload', {avatar: fileObject})
+ */
+export declare const postFiles: (url: string, fileMap: Record<string, File>, data?: any, option?: RequestOption) => Promise<any>;
+
+/**
+ * 发送 POST 请求并获取 JSON 响应
+ * @param {string} url - 请求 URL
+ * @param {any} [data=null] - 请求数据
+ * @param {RequestOption} [option={}] - 请求选项
+ * @returns {Promise<any>} 返回解析后的 JSON 数据
+ * @example
+ * postJson('/api/users', {name: 'John'}).then(data => console.log(data))
+ */
+export declare const postJson: (url: string, data?: any, option?: RequestOption) => Promise<any>;
+
 /**
  * 精度位数转小数表示法
- * @param {Number} precision 精度位数
- * @returns {Float} 精度小数表示法，如 0.01
+ * @param {number} precision - 精度位数
+ * @returns {number} 精度小数表示法，如 0.01
+ * @example
+ * precisionToStep(2) // 0.01
  */
 export declare const precisionToStep: (precision: number) => number;
 
 /**
  * 打印调用堆栈
+ * @returns {void}
+ * @example
+ * printStack() // 在控制台输出堆栈信息
  */
 export declare const printStack: () => void;
 
+/**
+ * 将磅（Point）转换为 mm
+ * @param {number} pt - 磅值
+ * @returns {number} 返回毫米值
+ * @example
+ * ptToMm(2.83) // 1
+ */
+export declare const ptToMm: (pt: number) => number;
+
+/**
+ * 像素转毫米
+ * @param {number} px - 像素值
+ * @param {number} [dpi=STAND_DPI] - DPI 值，默认为标准 DPI (96)
+ * @returns {number} 返回毫米值
+ * @example
+ * pxToMm(96) // 25.4
+ */
+export declare const pxToMm: (px: number, dpi?: number) => number;
+
+/**
+ * 替换 URL 中的查询参数
+ * @param {string} url - 原始 URL
+ * @param {Record<string, any>} newQuery - 新的查询参数对象
+ * @returns {string} 返回更新后的 URL
+ * @example
+ * queryReplace('http://example.com?a=1', {b: 2}) // 'http://example.com?a=1&b=2'
+ */
+export declare const queryReplace: (url: string, newQuery: Record<string, any>) => string;
+
+/**
+ * 将 URL 查询字符串转换为对象
+ * @param {string} query - 查询字符串
+ * @returns {Record<string, string>} 返回键值对对象
+ * @example
+ * queryToObj('name=John&age=30') // {name: 'John', age: '30'}
+ */
+export declare const queryToObj: (query: string) => Record<string, string>;
+
 /**
  * 随机整数
  * @param {Number} min
@@ -964,17 +1332,21 @@ export declare const randomWords: (count?: number, letterMax?: number) => string
 
 /**
  * 矩形相交（包括边重叠情况）
- * @param {Object} rect1
- * @param {Object} rect2
- * @returns {boolean}
+ * @param {Dimension} rect1 - 第一个矩形对象
+ * @param {Dimension} rect2 - 第二个矩形对象
+ * @returns {boolean} 如果两个矩形相交返回 true，否则返回 false
+ * @example
+ * rectAssoc({left: 0, top: 0, width: 100, height: 100}, {left: 50, top: 50, width: 100, height: 100}) // true
  */
 export declare const rectAssoc: (rect1: Dimension, rect2: Dimension) => boolean;
 
 /**
  * 检测矩形是否在指定布局内部
- * @param rect
- * @param layout
- * @returns {*}
+ * @param {Dimension} rect - 要检测的矩形
+ * @param {Dimension} layout - 布局矩形
+ * @returns {boolean} 如果矩形在布局内部返回 true，否则返回 false
+ * @example
+ * rectInLayout(rect, layout) // true
  */
 export declare const rectInLayout: (rect: Dimension, layout: Dimension) => boolean;
 
@@ -988,9 +1360,11 @@ declare interface RectObject {
 }
 
 /**
- * 正则表达式转义
- * @param str
- * @returns {string}
+ * 正则表达式转义（将特殊字符转义）
+ * @param {string} str - 要转义的字符串
+ * @returns {string} 返回转义后的字符串
+ * @example
+ * regQuote('a.b') // 'a\\.b'
  */
 export declare const regQuote: (str: string) => string;
 
@@ -1000,8 +1374,34 @@ export declare const regQuote: (str: string) => string;
  */
 export declare const REMOVABLE_TAGS: string[];
 
+/**
+ * 移除 DOM 节点
+ * @param {HTMLElement|string} dom - DOM 元素或选择器
+ * @returns {Node|null} 返回被移除的节点，如果未找到返回 null
+ * @example
+ * remove('#myElement')
+ */
 export declare const remove: (dom: HTMLElement | string) => Node | null;
 
+/**
+ * 发送 HTTP 请求
+ * @param {string} url - 请求 URL
+ * @param {BodyInit|null} [data=null] - 请求数据,可以是字符串、FormData、URLSearchParams、Blob、ArrayBuffer 等，如果是对象会根据 ContentType 自动转换（例如 application/json 会自动 JSON.stringify）
+ * @param {RequestOption} option - 请求选项
+ * @returns {AbortablePromise<Response>} 返回可中止的 Promise
+ * @example
+ * request('/api/data', null, {method: 'GET'})
+ */
+export declare const request: (url: string, data: (BodyInit | null) | undefined, option: RequestOption) => AbortablePromise<Response>;
+
+declare interface RequestOption {
+    method?: string;
+    headers?: Record<string, string>;
+    ContentType?: string;
+    Accept?: string;
+    timeout?: number;
+}
+
 /**
  * 取整
  * @param {Number} num
@@ -1026,30 +1426,56 @@ export declare const sanitizeFileName: (name: string) => string;
 export declare const SELF_CLOSING_TAGS: string[];
 
 /**
- * 设置cookie
- * @param {String} name
- * @param {String} value
- * @param {Number} days
- * @param {String} path
+ * 设置 Cookie
+ * @param {string} name - Cookie 名称
+ * @param {string} value - Cookie 值
+ * @param {number} days - 有效天数，0 表示会话 Cookie
+ * @param {string} [path='/'] - Cookie 路径，默认为根路径
+ * @returns {void}
+ * @example
+ * setCookie('username', 'john', 7)
  */
 export declare const setCookie: (name: string, value: string, days: number, path?: string) => void;
 
 /**
- * 显示节点（通过设置display为空方式）
- * @param {HTMLElement} dom
- * @param dom
+ * 显示节点（通过设置 display 为空方式）
+ * @param {HTMLElement|string} dom - DOM 元素或选择器
+ * @returns {void}
+ * @example
+ * show('#myElement')
  */
 export declare const show: (dom: HTMLElement | string) => void;
 
 /**
- * 通过ImageSrc获取base64（网络请求模式）
- * @param src
- * @returns {Promise<unknown>}
+ * 通过图片 URL 获取 Base64（网络请求模式）
+ * @param {string} src - 图片 URL
+ * @param {boolean} [cache=false] - 是否缓存结果
+ * @returns {Promise<unknown>} 返回 Base64 Data URL 的 Promise
+ * @example
+ * srcToBase64('https://example.com/image.png').then(base64 => console.log(base64))
  */
 export declare const srcToBase64: (src: string, cache?: boolean) => Promise<unknown>;
 
 export declare const STAND_DPI = 96;
 
+/**
+ * 将字符串分割成指定长度的数组
+ * @param {string} str - 要分割的字符串
+ * @param {number} size - 每段的长度
+ * @returns {string[]} 返回分割后的数组
+ * @example
+ * strChunk('abcdef', 2) // ['ab', 'cd', 'ef']
+ */
+export declare const strChunk: (str: string, size: number) => string[];
+
+/**
+ * 字符串转换为 HTML 实体
+ * @param {string} str - 要转换的字符串
+ * @param {number} [radix] - 进制，为 16 时使用十六进制
+ * @returns {string} 返回 HTML 实体字符串
+ * @example
+ * stringToEntity('AB', 16) // '&#x41;&#x42;'
+ */
 export declare const stringToEntity: (str: string, radix?: number) => string;
 
 /**
@@ -1076,28 +1502,35 @@ export declare const stringToEntity: (str: string, radix?: number) => string;
 export declare const stripSlashes: (str: string) => string;
 
 /**
- * 字符串转成首字母大写
- * @param {String} str
- * @param {Boolean} capitalize_first 是否将第一个单词首字母大写
- * @return {string}
+ * 字符串转成首字母大写（Pascal Case）
+ * @param {string} str - 要转换的字符串
+ * @param {boolean} [capitalize_first=false] - 是否将第一个单词首字母大写
+ * @returns {string} 返回转换后的字符串
+ * @example
+ * strToPascalCase('hello-world', true) // 'HelloWorld'
  */
 export declare const strToPascalCase: (str: string, capitalize_first?: boolean) => string;
 
 /**
- * 节流
+ * 节流函数
  * 规定在一个单位时间内，只能触发一次函数。如果这个函数单位时间内触发多次函数，只有一次生效。
- * @param {Function} fn
- * @param {Number} intervalMiSec
- * @return {(function(): void)|*}
+ * @param {Function} fn - 要节流的函数
+ * @param {number} intervalMiSec - 间隔时间（毫秒）
+ * @returns {Function} 返回节流后的函数
+ * @example
+ * const throttled = throttle(() => console.log('called'), 1000)
  */
 export declare const throttle: (fn: Function, intervalMiSec: number) => Function;
 
 /**
  * 更有效果的节流函数
  * 区别：如果函数执行间隔还没到期，放入下一个时间周期执行，如果已经有下一周期未执行，当前触发作废。
- * 这种效果在 **Change 类型函数场景中更有效果，可以确保最后一次变更能够有效执行
- * @param {Function} fn
- * @param {Number} intervalMiSec
+ * 这种效果在 Change 类型函数场景中更有效果，可以确保最后一次变更能够有效执行
+ * @param {Function} fn - 要节流的函数
+ * @param {number} intervalMiSec - 间隔时间（毫秒）
+ * @returns {Function} 返回节流后的函数
+ * @example
+ * const throttled = throttleEffect(() => console.log('called'), 1000)
  */
 export declare const throttleEffect: (fn: Function, intervalMiSec: number) => Function;
 
@@ -1110,18 +1543,22 @@ export declare const throttleEffect: (fn: Function, intervalMiSec: number) => Fu
 export declare const toggleDisabled: (el: HTMLElement | string, disabledClass?: string, forceEnabled?: boolean | null) => void;
 
 /**
- * 切换全屏
- * @param element
- * @returns {Promise<unknown>}
+ * 切换全屏模式（全屏时退出，非全屏时进入）
+ * @param {HTMLElement} element - 要全屏显示的元素
+ * @returns {Promise<unknown>} 返回 Promise
+ * @example
+ * toggleFullScreen(document.body)
  */
 export declare const toggleFullScreen: (element: any) => Promise<unknown>;
 
 /**
  * 去除字符串首尾指定字符或空白
- * @param {String} str 源字符串
- * @param {String} chars 指定字符，默认为空白
- * @param {Number} dir 方向
- * @returns {*|boolean}
+ * @param {string} str - 源字符串
+ * @param {string} [chars=''] - 指定字符，默认为空白
+ * @param {number} [dir=TRIM_BOTH] - 方向（TRIM_BOTH/TRIM_LEFT/TRIM_RIGHT）
+ * @returns {string} 返回去除后的字符串
+ * @example
+ * trim('__hello__', '_') // 'hello'
  */
 export declare const trim: (str: string, chars?: string, dir?: number) => string;
 
@@ -1143,29 +1580,40 @@ export declare const TRIM_RIGHT = 2;
 export declare function truncate(str: string, length: number, suffix?: string): string;
 
 /**
- * 反转义HTML
- * @param {String} html
- * @returns {string}
+ * 反转义 HTML（将 HTML 实体转换为字符）
+ * @param {string} html - 包含 HTML 实体的字符串
+ * @returns {string} 返回反转义后的字符串
+ * @example
+ * unescapeHtml('&lt;div&gt;') // '<div>'
  */
 export declare const unescapeHtml: (html: string) => string;
 
 /**
- * url 转 Base64Data 数据缓存
- * @param {String} url
- * @param {String|Null} b64Data base64 数据，传入 null 则为读取缓存，这里不是不是base64，而是 base64 data URL
- * @returns {String|Null} 读取缓存时返回 base64 data URL 字符串，未命中返回 null
+ * URL 转 Base64 Data URL 数据缓存
+ * @param {string} url - 文件 URL
+ * @param {string|null} [b64Data=null] - Base64 Data URL 数据，传入 null 则为读取缓存
+ * @returns {string|null} 读取缓存时返回 Base64 Data URL 字符串，未命中返回 null
+ * @example
+ * urlB64DataCache('http://example.com/img.png', dataUrl) // 设置缓存
+ * urlB64DataCache('http://example.com/img.png') // 读取缓存
  */
 export declare const urlB64DataCache: (url: string, b64Data?: string | null) => string | null;
 
 /**
- * @param {String} srcStr
- * @return {string}
+ * UTF-8 解码
+ * @param {string} srcStr - 要解码的字符串
+ * @returns {string} 返回解码后的字符串
+ * @example
+ * utf8Decode(encodedStr) // 'decoded string'
  */
 export declare const utf8Decode: (srcStr: string) => string;
 
 /**
- * @param {String} srcStr
- * @returns {string}
+ * UTF-8 编码
+ * @param {string} srcStr - 要编码的字符串
+ * @returns {string} 返回编码后的字符串
+ * @example
+ * utf8Encode('string') // 'encoded string'
  */
 export declare const utf8Encode: (srcStr: string) => string;