# @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)
```