@mingto/tools 1.0.675

package/README.md

@@ -0,0 +1,1615 @@
+# @minto-ai/tools工具库
+
+欢迎使用@minto-ai/tools工具库，旨在提供一系列实用的函数，以简化日常开发任务。
+
+# 安装
+
+使用 pnpm 安装最新版本的 @minto-ai/tools：
+
+```bash
+pnpm install @minto-ai/tools
+```
+
+# 功能概览
+
+## 主要
+
+### `isNumber`
+
+> `function isNumber(value: unknown): value is number`
+
+判断给定的值是否是一个数字。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(value is number)`: 如果 `value` 是一个数字，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isNumber } from '@minto-ai/tools'
+
+isNumber(123) //  true
+isNumber('123') //  false
+```
+
+### `isString`
+
+> `function isString(value: unknown): value is string`
+
+判断给定的值是否是一个字符串。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`( value is string)`: 如果 `value` 是一个字符串，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isString } from '@minto-ai/tools'
+
+isString('hello') //  true
+isString(123) //  false
+```
+
+### `isUndefined`
+
+> `function isUndefined(value: unknown): value is undefined`
+
+检查一个值是否为 undefined。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(value is undefined)`: 如果 `value` 是 undefined，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isUndefined } from '@minto-ai/tools'
+
+console.log(isUndefined(undefined)) //  true
+console.log(isUndefined(123)) //  false
+```
+
+### `isNullOrUndefined`
+
+> `function isNullOrUndefined(value: unknown): value is null | undefined`
+
+如果值为 null 或 undefined，则返回 true；否则返回 false。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(value is null | undefined)`: 如果 `value` 是 null 或 undefined，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isNullOrUndefined } from '@minto-ai/tools'
+
+console.log(isNullOrUndefined(null)) //  true
+console.log(isNullOrUndefined(123)) //  false
+```
+
+### `isObject`
+
+> `function isObject(value: unknown): value is Record<PropertyKey, unknown>`
+
+判断给定的值是否是一个对象。但对象的值包含 null 的情况，返回 false。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(value is Record<PropertyKey, unknown>)`: 如果 `value` 是一个普通对象，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isObject } from '@minto-ai/tools'
+
+isObject({ a: 1 }) //  true
+isObject(null) //  false
+```
+
+### `isArray`
+
+> `function isArray(value: unknown): value is unknown[]`
+
+判断给定的值是否是一个数组。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(value is unknown[])`: 如果 `value` 是一个数组，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isArray } from '@minto-ai/tools'
+
+isArray([1, 2, 3]) //  true
+isArray('123') //  false
+```
+
+### `checkEmpty`
+
+> `function checkEmpty(value: unknown): boolean`
+
+检查给定的值是否为空。空值包括：空字符串、空数组、空对象、null 或 undefined。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(boolean)`: 如果 `value` 是空的，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { checkEmpty } from '@minto-ai/tools'
+
+checkEmpty('') //  true
+checkEmpty(null) //  true
+checkEmpty({}) //  true
+checkEmpty([]) //  true
+checkEmpty('text') //  false
+```
+
+### `checkObjectEmpty`
+
+> `function checkObjectEmpty(value: unknown): boolean`
+
+检查对象是否为空。一个空对象是指没有任何自身属性的对象。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(boolean)`: 如果 `value` 是一个空对象，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { checkObjectEmpty } from '@minto-ai/tools'
+
+checkObjectEmpty({}) //  true
+checkObjectEmpty({ a: 1 }) //  false
+```
+
+### `checkArrayEmpty`
+
+> `function checkArrayEmpty(value: unknown): boolean`
+
+检查数组是否为空。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(boolean)`: 如果 `value` 是一个数组并且长度为0，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { checkArrayEmpty } from '@minto-ai/tools'
+
+checkArrayEmpty([]) //  true
+checkArrayEmpty([1, 2, 3]) //  false
+```
+
+### `checkEmptyNotZero`
+
+> `function checkEmptyNotZero(value: unknown): boolean`
+
+检查给定的值是否为空，但不包括数字 0。空值包括：空字符串、空数组、空对象、null 或 undefined。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(boolean)`: 如果 `value` 是空的，且不是数字 0，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { checkEmptyNotZero } from '@minto-ai/tools'
+
+checkEmptyNotZero('') //  true
+checkEmptyNotZero(0) //  false
+checkEmptyNotZero(null) //  true
+checkEmptyNotZero({}) //  true
+checkEmptyNotZero([]) //  true
+checkEmptyNotZero('text') //  false
+```
+
+### `canBeParsedAsNumber`
+
+> `function canBeParsedAsNumber(value: unknown): boolean`
+
+检查一个值是否可以被解析为有效的数字。
+
+#### 参数
+
+- `value (unknown)`: 要检查的值。
+
+#### 返回
+
+`(boolean)`: 如果 `value` 可以被解析为数字，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { canBeParsedAsNumber } from '@minto-ai/tools'
+
+console.log(canBeParsedAsNumber('123')) //  true
+console.log(canBeParsedAsNumber('abc')) //  false
+console.log(canBeParsedAsNumber(null)) //  false
+console.log(canBeParsedAsNumber(undefined)) //  false
+console.log(canBeParsedAsNumber(123)) //  true
+```
+
+### `beParsedAsNumber`
+
+> `function beParsedAsNumber(value: never): number`
+
+将输入值转换为数字类型。
+
+#### 参数
+
+- `value (never)`: 要转换的值。
+
+#### 返回
+
+`(number)`: 如果 `value` 可以被解析为数字，则返回解析后的数字，否则返回 NaN。
+
+#### 例子
+
+```typescript
+import { beParsedAsNumber } from '@minto-ai/tools'
+
+console.log(beParsedAsNumber('123')) //  123
+console.log(beParsedAsNumber('abc')) //  NaN
+console.log(beParsedAsNumber(null)) //  NaN
+```
+
+## 字符串
+
+### `chunkString`
+
+> `function chunkString(str: string, chunkSize: number): string[]`
+
+将输入字符串按照指定的块大小分割成多个子字符串。
+
+#### 参数
+
+- `str (string)`: 要分割的字符串。
+- `chunkSize (number)`: 每个子字符串的长度。
+
+#### 返回
+
+`(string[])`: 返回一个包含分割后的子字符串的数组。
+
+#### 例子
+
+```typescript
+import { chunkString } from '@minto-ai/tools'
+
+console.log(chunkString('abcdefghijklmnopqrstuvwxyz', 3)) //  ['abc', 'def', 'ghi', 'jkl', 'mno', 'pqr', 'stu', 'vwx', 'yz']
+console.log(chunkString('abcdefghijklmnopqrstuvwxyz', 5)) //  ['abcde', 'fghij', 'klmno', 'pqrst', 'uvwxy', 'z']
+```
+
+### `objectToQueryString`
+
+> `function objectToQueryString(obj: Record<string, any>): string`
+
+将对象转换为 URL 查询字符串，自动进行键值的 URL 编码并以 `key=value` 使用 `&` 连接。
+
+#### 参数
+
+- `obj (Record<string, any>)`: 需要转换的对象。
+
+#### 返回
+
+`(string)`: 转换后的查询字符串。
+
+#### 例子
+
+```typescript
+import { objectToQueryString } from '@minto-ai/tools'
+
+objectToQueryString({ a: 1, b: 'x y' }) //  'a=1&b=x%20y'
+```
+
+### `queryStringToObject`
+
+> `function queryStringToObject(queryString: string): Record<string, any>`
+
+将 URL 查询字符串转换为对象，自动对键值进行 URL 解码。
+
+#### 参数
+
+- `queryString (string)`: 需要解析的查询字符串，例如 `a=1&b=x%20y`。
+
+#### 返回
+
+`(Record<string, any>)`: 解析后的对象。
+
+#### 例子
+
+```typescript
+import { queryStringToObject } from '@minto-ai/tools'
+
+queryStringToObject('a=1&b=x%20y') //  { a: '1', b: 'x y' }
+```
+
+## 函数
+
+### `throttle`
+
+> `function throttle<T extends (...args: any[]) => any>(callback: T, delay: number): ThrottledFunction<T>`
+
+节流函数用于限制一个函数的执行频率。它确保一个函数在指定的时间间隔内最多只执行一次。
+
+#### 参数
+
+- `callback (Function)`: 要节流的函数。
+- `delay (number)`: 执行频率的延迟时间（以毫秒为单位）。
+
+#### 返回
+
+`(Function)`: 返回一个节流后的函数，包含原函数的参数类型和一个 cancel 方法，用于取消未执行的部分。
+
+#### 例子
+
+```typescript
+import { throttle } from '@minto-ai/tools'
+
+// 定义一个需要节流的函数
+function handleScroll() {
+  console.log('Scroll event triggered')
+}
+
+// 创建节流后的函数，每 500 毫秒最多执行一次
+const throttledScroll = throttle(handleScroll, 500)
+
+// 绑定到事件监听器
+window.addEventListener('scroll', throttledScroll)
+
+// 取消节流函数的未执行部分
+throttledScroll.cancel()
+```
+
+### `debounce`
+
+> `function debounce<T extends (...args: any[]) => any>(callback: T, delay: number): DebouncedFunction<T>`
+
+防抖函数用于延迟函数的执行，直到指定时间内不再触发事件。如果在延迟时间内再次触发事件，则会重新计时。
+
+#### 参数
+
+- `callback(Function)`: 要防抖的函数。
+- `delay(number)`: 执行频率的延迟时间（以毫秒为单位）。
+
+#### 返回
+
+`(Function)`: 返回一个防抖后的函数，包含原函数的参数类型和一个 cancel 方法，用于取消未执行的部分。
+
+#### 例子
+
+```typescript
+import { debounce } from '@minto-ai/tools'
+
+// 定义一个需要防抖的函数
+function handleResize() {
+  console.log('Window resized')
+}
+
+// 创建防抖后的函数，延迟 300 毫秒执行
+const debouncedResize = debounce(handleResize, 300)
+
+// 绑定到事件监听器
+window.addEventListener('resize', debouncedResize)
+
+// 取消防抖函数的未执行部分
+debouncedResize.cancel()
+```
+
+## 对象
+
+### `deepFreeze`
+
+> `function deepFreeze<T extends Record<string, any>>(obj: T): Readonly<T>`
+
+深度冻结一个对象，防止其属性及嵌套属性被修改。递归地冻结对象的所有属性，包括嵌套对象，确保对象的状态不可变。
+
+#### 参数
+
+- `value (T)`: 需要被冻结的对象。
+
+#### 返回
+
+`(Readonly<T>)`: 返回深度冻结后的对象。
+
+#### 例子
+
+```typescript
+import { deepFreeze } from '@minto-ai/tools'
+
+const obj = { name: 'Kimi', details: { age: 30 } }
+const frozenObj = deepFreeze(obj)
+console.log(Object.isFrozen(frozenObj)) // 输出：true
+console.log(Object.isFrozen(frozenObj.details)) // 输出：true
+```
+
+### `pickObject`
+
+> `function pickObject<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>`
+
+从给定对象中挑选指定的属性，并返回一个包含这些属性的新对象。
+
+#### 参数
+
+- `obj (T)`: 源对象，从中挑选属性。
+- `keys (K[])`: 需要挑选的属性键名数组。
+
+#### 返回
+
+`(Readonly<T>)`: 返回深度冻结后的对象。
+
+#### 例子
+
+```typescript
+import { pickObject } from '@minto-ai/tools'
+
+const user = {
+  name: 'Kimi',
+  age: 30,
+  email: 'kimi@example.com'
+}
+
+const pickedUser = pickObject(user, ['name', 'email'])
+console.log(pickedUser) // 输出：{ name: 'Kimi', email: 'kimi@example.com' }
+```
+
+## 数组
+
+### `chunkArray`
+
+> `function chunkArray<T>(array: T[], chunkSize?: number): T[][]`
+
+这个函数接受一个数组和一个指定的块大小，然后返回一个二维数组。每个子数组包含原数组中的一部分元素，大小由 `chunkSize` 参数决定。如果数组的长度不是 `chunkSize` 的整数倍，最后一个块可能包含的元素少于 `chunkSize`。
+
+#### 参数
+
+- `array (Array)`: 要分割的源数组。
+- `[chunkSize=1] (number)`: 每个块的大小，默认值为 1。
+
+#### 返回
+
+`(Array)`: 返回一个二维数组，每个子数组是原数组的一部分元素。
+
+#### 例子
+
+```typescript
+import { chunkArray } from '@minto-ai/tools'
+
+chunkArray(['a', 'b', 'c', 'd'], 2)
+//  [['a', 'b'], ['c', 'd']]
+
+chunkArray(['a', 'b', 'c', 'd', 'e'], 3)
+//  [['a', 'b', 'c'], ['d', 'e']]
+
+chunkArray([1, 2, 3, 4, 5], 4)
+//  [[1, 2, 3, 4], [5]]
+```
+
+## 数学
+
+### `getDecimalPlaces`
+
+> `function getDecimalPlaces(num: number): number`
+
+获取一个数字的小数位数
+
+#### 参数
+
+- `num (number)`: 需要获取小数位数的数字。
+
+#### 返回
+
+`(number)`: 返回一个数字的小数位数。
+
+#### 例子
+
+```typescript
+import { getDecimalPlaces } from '@minto-ai/tools'
+
+console.log(getDecimalPlaces(123.456)) //  3
+console.log(getDecimalPlaces(123)) //  0
+console.log(getDecimalPlaces(0.001)) //  3
+console.log(getDecimalPlaces(-123.45)) //  2
+```
+
+### `add`
+
+> `function add(augend: number, addend: number): number`
+
+精确地将两个数字相加，避免 JavaScript 中浮点数运算的精度问题。
+
+#### 参数
+
+- `augend (number)`: 第一个数字（被加数）。
+- `addend (number)`: 第二个数字（加数）。
+
+#### 返回
+
+`(number)`: 返回两个数字的精确和。
+
+#### 例子
+
+```typescript
+import { add } from '@minto-ai/tools'
+
+console.log(add(0.1, 0.2)) //  0.3
+console.log(add(1.234, 5.678)) //  6.912
+console.log(add(100, 0.001)) //  100.001
+```
+
+### `subtract`
+
+> `function subtract(minuend: number, subtrahend: number): number`
+
+精确地减去两个数字，避免 JavaScript 中浮点数运算的精度问题。
+
+#### 参数
+
+- `minuend (number)`: 第一个数字（被减数）。
+- `subtrahend (number)`: 第二个数字（减数）。
+
+#### 返回
+
+`(number)`: 返回两个数字的精确差。
+
+#### 例子
+
+```typescript
+import { subtract } from '@minto-ai/tools'
+
+console.log(subtract(0.3, 0.1)) // 0.2
+console.log(subtract(1.234, 0.567)) // 0.667
+console.log(subtract(100.001, 0.001)) // 100
+```
+
+### `multiply`
+
+> `function multiply(multiplier: number, multiplicand: number): number`
+
+精确地乘以两个数字，避免 JavaScript 中浮点数运算的精度问题。
+
+#### 参数
+
+- `multiplier (number)`: 第一个数字（乘数）。
+- `multiplicand (number)`: 第二个数字（被乘数）。
+
+#### 返回
+
+`(number)`: 返回两个数字的精确积。
+
+#### 例子
+
+```typescript
+import { multiply } from '@minto-ai/tools'
+
+console.log(multiply(0.1, 0.2)) // 0.02
+console.log(multiply(1.234, 5.678)) // 7.006652
+console.log(multiply(100.001, 0.001)) // 0.100001
+```
+
+### `divide`
+
+> `function divide(dividend: number, divisor: number): number`
+
+精确地除以两个数字，避免 JavaScript 中浮点数运算的精度问题。
+
+#### 参数
+
+- `dividend (number)`: 第一个数字（被除数）。
+- `divisor (number)`: 第二个数字（除数）。
+
+#### 返回
+
+`(number)`: 返回两个数字的精确商。
+
+#### 例子
+
+```typescript
+import { divide } from '@minto-ai/tools'
+
+console.log(divide(10, 2)) // 5
+console.log(divide(1.234, 0.567)) // 2.1763668430335097
+console.log(divide(100.001, 0.001)) // 100001
+```
+
+### `calcAspectRatio`
+
+> `function calcAspectRatio(size: [number, number]): [number, number]`
+
+计算宽高的最简整数比例，常用于等比缩放或显示比例展示。
+
+#### 参数
+
+- `size ([number, number])`: 数组形式的宽高值。
+
+#### 返回
+
+`([number, number])`: 最简整数比例，例如 `[16, 9]`。
+
+#### 例子
+
+```typescript
+import { calcAspectRatio } from '@minto-ai/tools'
+
+calcAspectRatio([1920, 1080]) //  [16, 9]
+calcAspectRatio([1280, 800]) //  [16, 10]
+```
+
+## 浏览器
+
+### `copyText`
+
+> `function copyText(text: string): Promise<string>`
+
+将指定的文本复制到剪贴板。
+
+#### 参数
+
+- `text (string)`: 需要复制到剪贴板的文本。
+
+#### 返回
+
+`Promise<string>`: 一个 Promise 对象，当文本成功复制到剪贴板时解析为被复制的文本，如果复制失败则拒绝 Promise。
+
+#### 例子
+
+```typescript
+import { copyText } from '@minto-ai/tools'
+
+copyText('Hello, World!').then(
+  text => console.log('Text copied to clipboard:', text),
+  error => console.error('Failed to copy text:', error)
+)
+```
+
+### `isIos`
+
+> `function isIos(): boolean`
+
+判断当前环境是否为 iOS 设备。主要检测的设备类型包括 iPhone、iPad 和 iPod。
+
+#### 返回
+
+`(boolean)`: 如果是iOS设备，返回true；否则返回false。
+
+#### 例子
+
+```typescript
+import { isIos } from '@minto-ai/tools'
+
+console.log(isIos()) // 输出 true 或 false
+```
+
+### `isAndroid`
+
+> `function isAndroid(): boolean`
+
+判断当前环境是否为 Android 设备。主要检测设备类型为 Android。
+
+#### 返回
+
+`(boolean)`: 如果是Android设备，返回true；否则返回false。
+
+#### 例子
+
+```typescript
+import { isAndroid } from '@minto-ai/tools'
+
+console.log(isAndroid()) // 输出 true 或 false
+```
+
+### `isMobile`
+
+> `function isMobile(): boolean`
+
+判断当前环境是否为移动设备。主要检测设备类型为移动设备。
+
+#### 返回
+
+`(boolean)`: 如果是移动设备，返回true；否则返回false。
+
+#### 例子
+
+```typescript
+import { isMobile } from '@minto-ai/tools'
+
+console.log(isMobile()) // 输出 true 或 false
+```
+
+### `isPc`
+
+> `function isPc(): boolean`
+
+判断当前环境是否为PC设备。主要检测设备类型为PC设备。
+
+#### 返回
+
+`(boolean)`: 如果是PC设备，返回true；否则返回false。
+
+#### 例子
+
+```typescript
+import { isPc } from '@minto-ai/tools'
+
+console.log(isPc()) // 输出 true 或 false
+```
+
+### `createAudioPermission`
+
+> `function createAudioPermission(): AudioPermission`
+
+跨平台音频权限管理器，统一请求音频播放权限与麦克风权限，处理 PC/iOS/Android 在自动播放与权限授权上的差异。
+
+#### 返回
+
+`(AudioPermission)`: 返回单例的权限管理器，包含 `requestPlaybackPermission()` 与 `requestMicrophonePermission()` 两个方法。
+
+#### 例子
+
+```typescript
+import { createAudioPermission } from '@minto-ai/tools'
+
+const audioPermission = createAudioPermission()
+
+// 请求音频播放权限（需在用户交互后调用）
+await audioPermission.requestPlaybackPermission()
+
+// 请求麦克风权限
+await audioPermission.requestMicrophonePermission()
+```
+
+### `getBrowserFingerprint`
+
+> `function getBrowserFingerprint(): string`
+
+生成匿名浏览器指纹，用于区分浏览器匿名用户的唯一 ID。通过收集浏览器环境特征（如 UserAgent、语言、屏幕分辨率、色深、时区、硬件并发、平台，以及 Canvas 渲染指纹等），并使用 MurmurHash3（32 位）生成稳定的十六进制字符串。
+
+#### 参数
+
+- 无
+
+#### 返回
+
+`(string)`: 浏览器指纹 ID（十六进制字符串）。在非浏览器环境（如 Node/SSR）返回空字符串 `''`。
+
+#### 例子
+
+```typescript
+import { getBrowserFingerprint } from '@minto-ai/tools'
+
+// 生成匿名用户唯一ID
+const fingerprint = getBrowserFingerprint()
+console.log(fingerprint) //  例如：'a1b2c3d4'
+
+// 建议：结合本地存储缓存以保持一致性
+localStorage.setItem('anonymous_id', fingerprint)
+```
+
+#### 注意事项
+
+- 指纹可能随浏览器升级、系统变更或渲染差异而变化，适合作为匿名用户的临时唯一标识，不建议用于强身份识别。
+- 隐私增强模式或跨平台差异可能禁用部分特征（如 deviceMemory、Canvas），函数会自动兼容并尽可能生成可辨识的 ID。
+
+### `getAbsoluteUrl`
+
+> `function getAbsoluteUrl(rawUrl: string): string`
+
+将任意格式的 URL 路径规范化为完整的绝对 URL 地址。
+
+#### 参数
+
+- `rawUrl (string)`: 待规范化的原始 URL 路径，支持空值、相对路径、绝对路径等格式。
+
+#### 返回
+
+`(string)`: 规范化后的绝对 URL 字符串，空输入返回空字符串。
+
+#### 例子
+
+```typescript
+import { getAbsoluteUrl } from '@minto-ai/tools'
+
+// 假设当前页面 URL 为 https://example.com/page
+
+getAbsoluteUrl('/api/data') // 'https://example.com/api/data'
+getAbsoluteUrl('https://other.com/api') // 'https://other.com/api'
+getAbsoluteUrl('') // ''
+```
+
+## 工具
+
+### `getUuid`
+
+> `function getUuid(): string`
+
+利用 Web Crypto API，生成一个随机的 32 位无符号整数，并将其转换为一个基于 36 进制的字符串。这种格式的字符串通常用于标识，并且可以保证在很大范围内的唯一性。
+
+#### 返回
+
+`(string)`: 返回一个随机生成的 UUID 字符串。
+
+#### 例子
+
+```typescript
+import { getUuid } from '@minto-ai/tools'
+
+const uuid = getUuid()
+console.log(uuid) // 输出类似于 "1gann4cq9b6r"
+```
+
+### `timeDelay`
+
+> `function timeDelay(delay: number): Promise<void>`
+
+创建一个延迟执行的 Promise，常用于等待动画或节流场景中的异步等待。
+
+#### 参数
+
+- `delay (number)`: 延迟时间，单位毫秒，必须为非负数。
+
+#### 返回
+
+`(Promise<void>)`: 在指定时间后解析的 Promise。
+
+#### 例子
+
+```typescript
+import { timeDelay } from '@minto-ai/tools'
+
+await timeDelay(300)
+// 继续后续逻辑
+```
+
+## 文件
+
+### 枚举
+
+#### `FileSuffixEnum`
+
+一个包含常见文件后缀的枚举类型，用于统一管理文件后缀的字符串值。
+
+| 枚举键名 | 后缀值 | 说明                           |
+| -------- | ------ | ------------------------------ |
+| `DOC`    | `doc`  | Microsoft Word 文档            |
+| `DOCX`   | `docx` | Microsoft Word 文档 (XML 格式) |
+| `PDF`    | `pdf`  | Portable Document Format (PDF) |
+| `PPT`    | `ppt`  | PowerPoint 演示文稿            |
+| `PPTX`   | `pptx` | PowerPoint 演示文稿 (XML 格式) |
+| `XLS`    | `xls`  | Excel 工作簿                   |
+| `XLSX`   | `xlsx` | Excel 工作簿 (XML 格式)        |
+| `JSON`   | `json` | JSON 数据文件                  |
+| `JPG`    | `jpg`  | JPEG 图像                      |
+| `PNG`    | `png`  | PNG 图像                       |
+| `JPEG`   | `jpeg` | JPEG 图像 (另一种扩展名)       |
+| `WEBP`   | `webp` | WebP 图像                      |
+| `MP4`    | `mp4`  | MP4 视频文件                   |
+| `AVI`    | `avi`  | AVI 视频文件                   |
+| `FLV`    | `flv`  | Flash 视频文件                 |
+| `MKV`    | `mkv`  | Matroska 视频文件              |
+| `MP3`    | `mp3`  | MP3 音频文件                   |
+| `WAV`    | `wav`  | WAV 音频文件                   |
+| `TXT`    | `txt`  | 文本文件                       |
+| `HTML`   | `html` | HTML 文件                      |
+| `NULL`   | `''`   | 空字符串，用于表示无后缀       |
+
+#### `ImageFileSuffixEnum`
+
+一个包含常见图片文件后缀的枚举类型，继承自 `FileSuffixEnum`。
+
+| 枚举键名 | 后缀值 | 说明      |
+| -------- | ------ | --------- |
+| `JPG`    | `jpg`  | JPEG 图像 |
+| `PNG`    | `png`  | PNG 图像  |
+| `JPEG`   | `jpeg` | JPEG 图像 |
+| `WEBP`   | `webp` | WebP 图像 |
+
+#### `VideoFileSuffixEnum`
+
+一个包含常见视频文件后缀的枚举类型，继承自 `FileSuffixEnum`。
+
+| 枚举键名 | 后缀值 | 说明              |
+| -------- | ------ | ----------------- |
+| `MP4`    | `mp4`  | MP4 视频文件      |
+| `AVI`    | `avi`  | AVI 视频文件      |
+| `FLV`    | `flv`  | Flash 视频文件    |
+| `MKV`    | `mkv`  | Matroska 视频文件 |
+
+#### `PptFileSuffixEnum`
+
+一个包含常见 PPT 文件后缀的枚举类型，继承自 `FileSuffixEnum`。
+
+| 枚举键名 | 后缀值 | 说明                           |
+| -------- | ------ | ------------------------------ |
+| `PPT`    | `ppt`  | PowerPoint 演示文稿            |
+| `PPTX`   | `pptx` | PowerPoint 演示文稿 (XML 格式) |
+
+#### `DocumentFileSuffixEnum`
+
+一个包含常见文档文件后缀的枚举类型，继承自 `FileSuffixEnum`。
+
+| 枚举键名 | 后缀值 | 说明                           |
+| -------- | ------ | ------------------------------ |
+| `DOC`    | `doc`  | Microsoft Word 文档            |
+| `DOCX`   | `docx` | Microsoft Word 文档 (XML 格式) |
+| `PDF`    | `pdf`  | Portable Document Format (PDF) |
+| `TXT`    | `txt`  | 文本文件                       |
+| `XLS`    | `xls`  | Excel 工作簿                   |
+| `XLSX`   | `xlsx` | Excel 工作簿 (XML 格式)        |
+| `JSON`   | `json` | JSON 数据文件                  |
+
+#### `MusicFileSuffixEnum`
+
+常见音乐文件后缀的枚举类型。
+
+| 枚举键名 | 后缀值 | 说明         |
+| -------- | ------ | ------------ |
+| `MP3`    | `mp3`  | MP3 音频文件 |
+| `WAV`    | `wav`  | WAV 音频文件 |
+
+#### `CompressFileSuffixEnum`
+
+常见压缩文件后缀的枚举类型。
+
+| 枚举键名 | 后缀值 | 说明         |
+| -------- | ------ | ------------ |
+| `ZIP`    | `zip`  | ZIP 压缩文件 |
+| `RAR`    | `rar`  | RAR 压缩文件 |
+
+### 类型
+
+#### `FileSuffix`
+
+`FileSuffix` 是一个基于 `FileSuffixEnum` 枚举的类型别名，用于表示文件后缀。
+
+#### `ImageFileSuffix`
+
+`ImageFileSuffix` 是一个基于 `ImageFileSuffixEnum` 枚举的类型别名，用于表示图片文件后缀。
+
+#### `VideoFileSuffix`
+
+`VideoFileSuffix` 是一个基于 `VideoFileSuffixEnum` 枚举的类型别名，用于表示视频文件后缀。
+
+#### `PptFileSuffix`
+
+`PptFileSuffix` 是一个基于 `PptFileSuffixEnum` 枚举的类型别名，用于表示 PowerPoint 文件后缀。
+
+#### `DocumentFileSuffix`
+
+`DocumentFileSuffix` 是一个基于 `DocumentFileSuffixEnum` 枚举的类型别名，用于表示文档文件后缀。
+
+### `getFileSuffix`
+
+> `function getFileSuffix(filePath: string): FileSuffix`
+
+从文件路径或文件名中提取文件后缀。
+
+#### 参数
+
+- `filePath (string)`: 文件路径或文件名。
+
+#### 返回
+
+`(FileSuffix)`: 文件后缀，以小写形式返回。如果文件没有后缀或路径无效，返回空字符串。
+
+#### 例子
+
+```typescript
+import { getFileSuffix } from '@minto-ai/tools'
+
+console.log(getFileSuffix('example/document.pdf')) //  "pdf"
+console.log(getFileSuffix('image.jpg')) //  "jpg"
+console.log(getFileSuffix('no_extension')) //  ""
+```
+
+### `getFileTitle`
+
+> `function getFileTitle(filePath: string): string`
+
+从文件路径中提取文件名（不包含后缀）。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/file.txt`。
+
+#### 返回
+
+`(string)`: 文件名（不包含后缀）
+
+#### 示例
+
+```typescript
+import { getFileTitle } from '@minto-ai/tools'
+
+console.log(getFileTitle('/path/to/example/document.pdf')) //  "document"
+console.log(getFileTitle('/path/to/image.jpg')) //  "image"
+console.log(getFileTitle('/path/to/no_extension')) //  "no_extension"
+```
+
+### `getFileName`
+
+> `function getFileName(filePath: string): string`
+
+从文件路径中提取完整的文件名（包含后缀）。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/file.txt`。
+
+#### 返回
+
+`(string)`: 文件名（包含后缀）。
+
+#### 示例
+
+```typescript
+import { getFileName } from '@minto-ai/tools'
+
+console.log(getFileName('/path/to/example/document.pdf')) //  "document.pdf"
+console.log(getFileName('/path/to/image.jpg')) //  "image.jpg"
+console.log(getFileName('/path/to/no_extension')) //  "no_extension"
+```
+
+### `isFilePath`
+
+> `function isFilePath(filePath: string): boolean`
+
+判断是否是有效的文件路径。有效文件路径指的是文件后缀匹配到 `FileSuffixEnum` 中的任何值。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/file.txt`。
+
+#### 返回
+
+`(boolean)`: 如果文件路径的后缀匹配到 `FileSuffixEnum` 中的任何值，则返回 `true`，否则返回 `false`。
+
+#### 示例
+
+```typescript
+import { isFilePath } from '@minto-ai/tools'
+
+console.log(isFilePath('/path/to/example/document.pdf')) //  true
+console.log(isFilePath('/path/to/image.jpg')) //  true
+console.log(isFilePath('/path/to/no_extension')) //  false
+```
+
+### `isImageFilePath`
+
+> `function isImageFilePath(filePath: string): boolean`
+
+判断是否是有效的图片文件路径。有效图片文件路径指的是文件后缀匹配到 `ImageFileSuffixEnum` 中的任何值。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/image.jpg`。
+
+#### 返回值
+
+`(boolean)`: 如果文件路径的后缀匹配到 `ImageFileSuffixEnum` 中的任何值，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isImageFilePath } from '@minto-ai/tools'
+
+console.log(isImageFilePath('/path/to/image.jpg')) //  true
+console.log(isImageFilePath('/path/to/image.png')) //  true
+console.log(isImageFilePath('/path/to/image.gif')) //  false
+console.log(isImageFilePath('/path/to/image.bmp')) //  false
+```
+
+### `isVideoFilePath`
+
+> `function isVideoFilePath(filePath: string): boolean`
+
+判断是否是有效的视频文件路径。有效视频文件路径指的是文件后缀匹配到 `VideoFileSuffixEnum` 中的任何值。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/video.mp4`。
+
+#### 返回值
+
+`(boolean)`: 如果文件路径的后缀匹配到 `VideoFileSuffixEnum` 中的任何值，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isVideoFilePath } from '@minto-ai/tools'
+
+console.log(isVideoFilePath('/path/to/video.mp4')) //  true
+console.log(isVideoFilePath('/path/to/video.avi')) //  true
+```
+
+### `isPptFilePath`
+
+> `function isPptFilePath(filePath: string): boolean`
+
+判断是否是有效的文件路径。有效文件路径指的是文件后缀匹配到 `PptFileSuffixEnum` 中的任何值。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/presentation.ppt`。
+
+#### 返回值
+
+`(boolean)`: 如果文件路径的后缀匹配到 `PptFileSuffixEnum` 中的任何值，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isPptFilePath } from '@minto-ai/tools'
+
+console.log(isPptFilePath('/path/to/presentation.ppt')) //  true
+console.log(isPptFilePath('/path/to/presentation.pptx')) //  true
+```
+
+### `isDocumentFilePath`
+
+> `function isDocumentFilePath(filePath: string): boolean`
+
+判断是否是有效的文件路径。有效文件路径指的是文件后缀匹配到 `DocumentFileSuffixEnum` 中的任何值。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/document.pdf`。
+
+#### 返回值
+
+`(boolean)`: 如果文件路径的后缀匹配到 `DocumentFileSuffixEnum` 中的任何值，则返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isDocumentFilePath } from '@minto-ai/tools'
+
+console.log(isDocumentFilePath('/path/to/document.pdf')) //  true
+console.log(isDocumentFilePath('/path/to/document.docx')) //  true
+console.log(isDocumentFilePath('/path/to/document.doc')) //  true
+```
+
+### `isMusicFilePath`
+
+> `function isMusicFilePath(filePath: string): boolean`
+
+判断是否是有效的音乐文件路径。匹配 `MusicFileSuffixEnum` 中的后缀。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/audio.mp3`。
+
+#### 返回
+
+`(boolean)`: 如果匹配音乐后缀返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isMusicFilePath } from '@minto-ai/tools'
+
+isMusicFilePath('/path/to/audio.mp3') //  true
+isMusicFilePath('/path/to/audio.wav') //  true
+```
+
+### `isCompressFilePath`
+
+> `function isCompressFilePath(filePath: string): boolean`
+
+判断是否是有效的压缩文件路径。匹配 `CompressFileSuffixEnum` 中的后缀。
+
+#### 参数
+
+- `filePath (string)`: 文件路径，例如 `/path/to/archive.zip`。
+
+#### 返回
+
+`(boolean)`: 如果匹配压缩后缀返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isCompressFilePath } from '@minto-ai/tools'
+
+isCompressFilePath('/path/to/archive.zip') //  true
+isCompressFilePath('/path/to/archive.rar') //  true
+```
+
+### `getFileSuffixIcon`
+
+> `function getFileSuffixIcon(fileSuffix: FileSuffix): string`
+
+根据文件后缀获取对应的图标。
+
+#### 参数
+
+- `fileSuffix (FileSuffix)`: 文件后缀，需为 `FileSuffixEnum` 中的有效值。
+
+#### 返回
+
+`(string)`: 对应的图标路径。
+
+#### 示例
+
+```typescript
+import { FileSuffixEnum, getFileSuffixIcon } from '@minto-ai/tools'
+
+console.log(getFileSuffixIcon(FileSuffixEnum.PDF)) //  返回 pdfIcon 的路径
+console.log(getFileSuffixIcon(FileSuffixEnum.JPG)) //  返回 imageIcon 的路径
+console.log(getFileSuffixIcon(FileSuffixEnum.TXT)) //  返回 txtIcon 的路径
+```
+
+### `getFileIcon`
+
+> `function getFileIcon(filePath: string): string`
+
+根据文件路径获取对应的图标
+
+#### 参数
+
+- `filePath`: 文件路径
+
+#### 返回
+
+- `string`: 图标路径
+
+#### 示例
+
+```typescript
+import { getFileIcon } from '@minto-ai/tools'
+
+console.log(getFileIcon('/path/to/file.pdf')) // 返回 pdfIcon 的路径
+console.log(getFileIcon('/path/to/file.txt')) // 返回 txtIcon 的路径
+```
+
+### `getFilePathNotQuery`
+
+> `function getFilePathNotQuery(filePath: string): string`
+
+获取不包含查询参数的纯文件路径。
+
+#### 参数
+
+- `filePath (string)`: 包含查询参数的文件路径。
+
+#### 返回
+
+`(string)`: 纯文件路径。
+
+#### 例子
+
+```typescript
+import { getFilePathNotQuery } from '@minto-ai/tools'
+
+getFilePathNotQuery('https://a.com/file.pdf?x=1') //  'https://a.com/file.pdf'
+```
+
+### `getFileQuery`
+
+> `function getFileQuery(filePath: string): Record<string, any>`
+
+从文件路径中解析查询参数并转换为对象。
+
+#### 参数
+
+- `filePath (string)`: 包含查询参数的文件路径。
+
+#### 返回
+
+`(Record<string, any>)`: 查询参数对象。
+
+#### 例子
+
+```typescript
+import { getFileQuery } from '@minto-ai/tools'
+
+getFileQuery('https://a.com/file.pdf?x=1&y=2') //  { x: '1', y: '2' }
+```
+
+### `updateFilePathQuery`
+
+> `function updateFilePathQuery(filePath: string, objectQuery: Record<string, string>, isAppend?: boolean): string`
+
+更新文件路径中的查询参数；支持在原有参数上追加或覆盖。
+
+#### 参数
+
+- `filePath (string)`: 原始文件路径。
+- `objectQuery (Record<string, string>)`: 需写入的查询参数对象。
+- `[isAppend=true] (boolean)`: 是否在原有参数基础上追加，`false` 则覆盖。
+
+#### 返回
+
+`(string)`: 更新后的完整文件路径。
+
+#### 例子
+
+```typescript
+import { updateFilePathQuery } from '@minto-ai/tools'
+
+updateFilePathQuery('https://a.com/file.pdf?x=1', { y: '2' })
+// 'https://a.com/file.pdf?x=1&y=2'
+
+updateFilePathQuery('https://a.com/file.pdf?x=1', { y: '2' }, false)
+// 'https://a.com/file.pdf?y=2'
+```
+
+### `singleDownloadFile`
+
+> `function singleDownloadFile(filePath: string, fileName?: string): Promise<void>`
+
+下载单个文件。该函数通过指定的文件路径下载文件，并允许自定义下载文件的名称。
+
+#### 参数
+
+- `fileUrl (string)`: 文件的完整路径，例如 `https://example.com/file.pdf`。
+- `fileName (string)`: 下载时保存的文件名（可选）。如果未提供，将自动从 `filePath` 提取文件名。
+
+#### 返回
+
+`(Promise<void>)`: 返回一个 Promise，在文件下载完成后。
+
+#### 例子
+
+```typescript
+import { singleDownloadFile } from '@minto-ai/tools'
+
+// 示例 1: 使用默认文件名下载
+singleDownloadFile('https://example.com/document.pdf')
+
+// 示例 2: 自定义文件名下载
+singleDownloadFile('https://example.com/document.pdf', 'custom_name.pdf')
+```
+
+### `batchDownloadFile`
+
+> `function batchDownloadFile(fileList: Array<{filePath: string;fileName?: string;}>, zipName: string):Promise<void>`
+
+批量下载文件并打包为 ZIP。该函数接受一个文件列表，每个文件包含文件路径和可选的文件名，最终将所有文件打包为一个 ZIP 文件并触发下载。
+
+#### 参数
+
+- `fileList (Array<{filePath: string;fileName?: string;}>)`: 文件列表，每个文件包含文件路径和可选的文件名。如果未提供文件名，将自动从文件路径中提取。
+- `zipName (string)`: 打包后的 ZIP 文件名。如果文件名不以 `.zip` 结尾，将自动添加 `.zip` 后缀。
+
+#### 返回
+
+`(Promise<void>)`: 返回一个 Promise，在文件打包和下载完成后。
+
+#### 例子
+
+```typescript
+import { batchDownloadFile } from '@minto-ai/tools'
+
+const fileList = [
+  { filePath: 'https://example.com/file1.pdf', fileName: 'document1.pdf' },
+  { filePath: 'https://example.com/file2.jpg' },
+  { filePath: 'https://example.com/file3.txt', fileName: 'notes.txt' }
+]
+
+batchDownloadFile(fileList, 'my-files.zip')
+```
+
+## 校验
+
+### `isValidUrl`
+
+> `function isValidUrl(url: string): boolean`
+
+校验是否为合法的 HTTP/HTTPS 网页地址，支持域名、IP、端口、路径、查询、哈希等组合。
+
+#### 参数
+
+- `url (string)`: 需要校验的地址字符串。
+
+#### 返回
+
+`(boolean)`: 合法返回 `true`，否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isValidUrl } from '@minto-ai/tools'
+
+isValidUrl('https://example.com?a=1#hash') //  true
+isValidUrl('ftp://example.com') //  false
+```
+
+## 主题
+
+### `useTheme`
+
+> `function useTheme(): { theme: Ref<Theme>; isDark: ComputedRef<boolean>; isLight: ComputedRef<boolean>; setTheme: (theme?: Theme) => void; getTheme: () => Theme; setLight: () => void; setDark: () => void; toggleTheme: () => void }`
+
+Vue 主题切换 Hook，支持亮色/暗黑模式切换与状态读取，并自动将主题类名应用到 `html` 根元素。
+
+#### 返回
+
+`({ theme, isDark, isLight, setTheme, getTheme, setLight, setDark, toggleTheme })`: 主题状态与操作方法。
+
+#### 例子
+
+```typescript
+import { useTheme } from '@minto-ai/tools'
+
+const { theme, isDark, setDark, toggleTheme } = useTheme()
+
+setDark()
+toggleTheme()
+```
+
+## 国际化
+
+### `locale`
+
+> `function locale(locale: 'zh-cn' | 'zh-tw' | 'en' | 'ms' | 'ar' | 'th' | 'vi'): void`
+
+设置当前语言，内置中文简体/繁体、英文、马来语、阿拉伯语、泰语、越南语，并自动在包初始化时注册多语言文案。
+
+#### 参数
+
+- `locale`: 语言代码。
+
+#### 例子
+
+```typescript
+import tools from '@minto-ai/tools'
+
+tools.locale('zh-cn')
+```
+
+### `getLocale`
+
+> `function getLocale(): 'zh-cn' | 'zh-tw' | 'en' | 'ms' | 'ar' | 'th' | 'vi'`
+
+获取当前语言代码。
+
+#### 例子
+
+```typescript
+import tools from '@minto-ai/tools'
+
+tools.getLocale() //  'zh-cn'
+```
+
+## webSocket
+
+### `isWebSocketSupported`
+
+> `function isWebSocketSupported(): boolean`
+
+检查当前浏览器是否支持 WebSocket。
+
+#### 返回
+
+`(boolean)`: 如果浏览器支持 WebSocket，则返回 `true`；否则返回 `false`。
+
+#### 例子
+
+```typescript
+import { isWebSocketSupported } from '@minto-ai/tools'
+
+if (isWebSocketSupported()) {
+  console.log('WebSocket is supported!')
+}
+else {
+  console.log('WebSocket is not supported!')
+}
+```
+
+### `createWebSocket`
+
+> `function createWebSocket(url: string): WebSocket`
+
+创建一个新的 WebSocket 实例。此函数接受一个 WebSocket 服务器的 URL 并创建一个新的 WebSocket 实例。
+
+#### 参数
+
+- `url (string)`: WebSocket 服务器的 URL。
+
+#### 返回
+
+`(WebSocket)`: 返回一个新的 WebSocket 实例。
+
+#### 例子
+
+```typescript
+import { createWebSocket } from '@minto-ai/tools'
+
+const socket = createWebSocket('ws://example.com')
+// 使用 socket 进行通信...
+```
+
+## worker
+
+### `createWorker`
+
+> `function createWorker(fun: (...args: any) => any): Worker`
+
+创建并返回一个新的 Worker 实例，`fun`指的的任意函数，也就是要在 Worker 中执行的 JavaScript 函数。
+
+#### 参数
+
+- `fun (Function)`: 要在 Worker 中执行的 JavaScript 函数。
+
+#### 返回
+
+`(Worker)`: 返回新创建的 Worker 实例。
+
+#### 例子
+
+```typescript
+import { createWorker } from '@minto-ai/tools'
+
+const myWorker = createWorker(() => {
+  console.log('Hello from the Web Worker!')
+})
+```
+
+### `closeWorker`
+
+> `function closeWorker(worker: Worker | undefined | null): void`
+
+关闭并终止传入 Web Worker 实例的执行，通常配合`createWorker`一起使用
+
+#### 参数
+
+- `worker (Worker | undefined | null)`: 要关闭的 Worker 实例。
+
+#### 例子
+
+```typescript
+import { closeWorker, createWorker } from '@minto-ai/tools'
+
+const myWorker = createWorker(() => {
+  console.log('Hello from the Web Worker!')
+})
+// 当不再需要 Worker 时
+closeWorker(myWorker)
+```