@minto-ai/tools 1.0.662 → 1.0.663

package/README.md

@@ -327,6 +327,50 @@ console.log(chunkString('abcdefghijklmnopqrstuvwxyz', 3)) //  ['abc', 'def', 'gh
 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`
@@ -615,6 +659,29 @@ 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`
@@ -656,6 +723,7 @@ copyText('Hello, World!').then(
 
 ```typescript
 import { isIos } from '@minto-ai/tools'
+
 console.log(isIos()) // 输出 true 或 false
 ```
 
@@ -673,6 +741,7 @@ console.log(isIos()) // 输出 true 或 false
 
 ```typescript
 import { isAndroid } from '@minto-ai/tools'
+
 console.log(isAndroid()) // 输出 true 或 false
 ```
 
@@ -690,6 +759,7 @@ console.log(isAndroid()) // 输出 true 或 false
 
 ```typescript
 import { isMobile } from '@minto-ai/tools'
+
 console.log(isMobile()) // 输出 true 或 false
 ```
 
@@ -707,10 +777,35 @@ console.log(isMobile()) // 输出 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()
+```
+
+## 工具
 
 ### `getUuid`
 
@@ -731,6 +826,29 @@ 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)
+// 继续后续逻辑
+```
+
 ## 文件
 
 ### 枚举
@@ -806,6 +924,24 @@ console.log(uuid) // 输出类似于 "1gann4cq9b6r"
 | `XLS`    | `xls`  | Excel 工作簿                   |
 | `XLSX`   | `xlsx` | Excel 工作簿 (XML 格式)        |
 
+#### `MusicFileSuffixEnum`
+
+常见音乐文件后缀的枚举类型。
+
+| 枚举键名 | 后缀值 | 说明         |
+| -------- | ------ | ------------ |
+| `MP3`    | `mp3`  | MP3 音频文件 |
+| `WAV`    | `wav`  | WAV 音频文件 |
+
+#### `CompressFileSuffixEnum`
+
+常见压缩文件后缀的枚举类型。
+
+| 枚举键名 | 后缀值 | 说明         |
+| -------- | ------ | ------------ |
+| `ZIP`    | `zip`  | ZIP 压缩文件 |
+| `RAR`    | `rar`  | RAR 压缩文件 |
+
 ### 类型
 
 #### `FileSuffix`
@@ -1019,6 +1155,52 @@ 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`
@@ -1066,6 +1248,78 @@ 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>`
@@ -1122,6 +1376,88 @@ const fileList = [
 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`

package/dist/file/index.d.ts

@@ -16,6 +16,7 @@ import { default as isMusicFilePath } from './is-music-file-path';
 import { default as isPptFilePath } from './is-ppt-file-path';
 import { default as isVideoFilePath } from './is-video-file-path';
 import { default as singleDownloadFile } from './single-download-file';
+import { default as singleDownloadFileBase64 } from './single-download-file-base64';
 import { default as updateFilePathQuery } from './update-file-path-query';
 export type { CompressFileSuffix, DocumentFileSuffix, FileSuffix, ImageFileSuffix, MusicFileSuffix, PptFileSuffix, VideoFileSuffix, };
-export { batchDownloadFile, CompressFileSuffixEnum, DocumentFileSuffixEnum, FileSuffixEnum, getFileIcon, getFileName, getFilePathNotQuery, getFileQuery, getFileSuffix, getFileSuffixIcon, getFileTitle, ImageFileSuffixEnum, isCompressFilePath, isDocumentFilePath, isFilePath, isImageFilePath, isMusicFilePath, isPptFilePath, isVideoFilePath, MusicFileSuffixEnum, PptFileSuffixEnum, singleDownloadFile, updateFilePathQuery, VideoFileSuffixEnum, };
+export { batchDownloadFile, CompressFileSuffixEnum, DocumentFileSuffixEnum, FileSuffixEnum, getFileIcon, getFileName, getFilePathNotQuery, getFileQuery, getFileSuffix, getFileSuffixIcon, getFileTitle, ImageFileSuffixEnum, isCompressFilePath, isDocumentFilePath, isFilePath, isImageFilePath, isMusicFilePath, isPptFilePath, isVideoFilePath, MusicFileSuffixEnum, PptFileSuffixEnum, singleDownloadFile, singleDownloadFileBase64, updateFilePathQuery, VideoFileSuffixEnum, };

package/dist/file/single-download-file-base64.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 下载 base64 图片或文件
+ * @param base64Data - base64 data URL (如: data:image/png;base64,...)
+ * @param fileName - 保存的文件名和扩展名
+ * @returns Promise<void>
+ */
+declare function downloadBase64File(base64Data: string, fileName: string): Promise<void>;
+export default downloadBase64File;

package/dist/index.js

@@ -12094,7 +12094,7 @@ if (!USE_NATIVE_URL$1 && isCallable(Headers)) {
       dontCallGetSet: true,
       forced: true
     }, {
-      fetch: function fetch(input) {
+      fetch: function fetch2(input) {
         return nativeFetch(input, arguments.length > 1 ? wrapRequestOptions(arguments[1]) : {});
       }
     });
@@ -14154,6 +14154,31 @@ function _singleDownloadFile() {
   }));
   return _singleDownloadFile.apply(this, arguments);
 }
+function downloadBase64File(_x, _x2) {
+  return _downloadBase64File.apply(this, arguments);
+}
+function _downloadBase64File() {
+  _downloadBase64File = _asyncToGenerator(/* @__PURE__ */ _regenerator().m(function _callee(base64Data, fileName) {
+    var response, blob;
+    return _regenerator().w(function(_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          _context.n = 1;
+          return fetch(base64Data);
+        case 1:
+          response = _context.v;
+          _context.n = 2;
+          return response.blob();
+        case 2:
+          blob = _context.v;
+          FileSaver.saveAs(blob, fileName);
+        case 3:
+          return _context.a(2);
+      }
+    }, _callee);
+  }));
+  return _downloadBase64File.apply(this, arguments);
+}
 function debounce(callback, delay) {
   var timerId = null;
   function debouncedFunction() {
@@ -16728,6 +16753,7 @@ export {
   pickObject,
   queryStringToObject,
   singleDownloadFile,
+  downloadBase64File as singleDownloadFileBase64,
   subtract,
   throttle,
   timeDelay,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@minto-ai/tools",
   "type": "module",
-  "version": "1.0.662",
+  "version": "1.0.663",
   "description": "明途公共工具库",
   "author": "hcc",
   "license": "ISC",