Utils 工具函数文档

本文档详细介绍了 src/utils 目录下的工具函数，这些函数为 unibest 项目提供了各种实用的功能支持。

目录结构

src/utils/
├── index.ts          # 路由相关工具函数
├── lodash.ts         # 通用工具函数（类似 lodash）
├── queue.ts          # 任务队列工具
├── token.ts          # Token 管理工具
└── README.md         # 工具函数文档（本文档）

模块说明

1. index.ts - 路由相关工具函数

提供了与页面路由相关的工具函数，支持多端（H5、小程序、APP）路由操作。

主要功能

• 获取当前页面实例：getLastPage() - 获取当前页面的实例对象
• 解析当前路由：currRoute() - 获取当前页面的路径和查询参数
• URL 解析：parseUrlToObj() - 将 URL 解析为路径和查询参数对象
• URL 生成：parseObjToUrl() - 将路径和查询参数对象转换为 URL
• 页面列表管理：getAllPages() - 获取所有页面信息，支持按条件过滤
• 国际化支持：getCurrentPageI18nKey() - 获取当前页面的国际化键值
• 首页路径：HOME_PAGE - 获取应用首页的路径
• URL 参数解析：getUrlParams() - 解析 URL 中的查询参数

类型定义

• PageInstance - 页面实例类型，扩展了原始的 Page.PageInstance 类型

使用示例

import { currRoute, getLastPage, HOME_PAGE } from '@/utils'

// 获取当前路由信息
const routeInfo = currRoute()
console.log('当前路径:', routeInfo.path)
console.log('查询参数:', routeInfo.query)

// 获取当前页面实例
const pageInstance = getLastPage()

// 跳转到首页
uni.navigateTo({ url: HOME_PAGE })

2. lodash.ts - 通用工具函数

提供了类似 lodash 的通用工具函数，包括类型判断、时间格式化、对象操作等。

主要功能

类型判断

• isArray() - 判断是否为数组类型
• isObject() - 判断是否为对象类型
• isString() - 判断是否为字符串类型
• isNumber() - 判断是否为数字类型
• isBoolean() - 判断是否为布尔类型
• isFunction() - 判断是否为函数类型
• isNull() - 判断是否为 null
• isUndefined() - 判断是否为 undefined
• isEmpty() - 判断是否为空

字符串操作

• trim() - 去除字符串空格，支持多种模式

时间格式化

• dateFormat() - 格式化日期时间，支持自定义格式

对象操作

• objectSort() - 对对象按键名排序
• deepClone() - 深度克隆对象
• deepMerge() - 深度合并对象
• groupBy() - 按条件对数组分组
• set() - 修改对象指定路径的值
• get() - 获取对象指定路径的值
• isEqual() - 深度比较两个值是否相等

函数工具

• debounce() - 防抖函数
• throttle() - 节流函数

其他工具

• sleep() - 等待指定时间
• getTag() - 获取值的类型标签

使用示例

import { isObject, deepClone, debounce, dateFormat } from '@/utils/lodash'

// 类型判断
const data = { name: 'test' }
if (isObject(data)) {
  console.log('是对象类型')
}

// 深度克隆
const clonedData = deepClone(data)

// 防抖处理
const debouncedFn = debounce(() => {
  console.log('防抖执行')
}, 500)

// 时间格式化
const formattedDate = dateFormat('YYYY-MM-DD HH:mm:ss', new Date())
console.log('当前时间:', formattedDate)

3. queue.ts - 任务队列工具

实现了一个支持并发执行的任务队列类，确保任务按顺序添加并按设定的并发数执行。

主要功能

• 任务管理：支持添加、执行、暂停、恢复任务
• 并发控制：可设置最大并发数
• 状态管理：获取队列状态、等待任务完成
• 全局单例：提供全局队列实例

核心类

• Queue - 任务队列类
• GlobalQueue - 全局队列单例管理

使用示例

import Queue, { GlobalQueue } from '@/utils/queue'

// 创建单线程队列（默认）
const queue = new Queue()

// 创建并发队列
const concurrentQueue = new Queue({ maxConcurrency: 3 })

// 添加任务
queue.push(async () => {
  await new Promise(resolve => setTimeout(resolve, 1000))
  return 'task completed'
}).then(result => {
  console.log(result) // 'task completed'
})

// 使用全局队列
const globalQueue = GlobalQueue.getInstance()
globalQueue.push(async () => {
  // 执行异步操作
})

4. token.ts - Token 管理工具

提供了与 Token 相关的存储和获取功能，基于项目的存储管理机制。

主要功能

• getToken() - 获取本地存储的 Token
• setToken() - 设置或删除 Token

使用示例

import { getToken, setToken } from '@/utils/token'

// 获取 Token
const token = getToken()
console.log('当前 Token:', token)

// 设置 Token
setToken('your-token-here')

// 删除 Token
setToken() // 不传参数即为删除

技术特点

1. 多端兼容：所有工具函数都考虑了多端兼容性，支持 H5、小程序、APP 等平台
2. 类型安全：使用 TypeScript 编写，提供了完整的类型定义
3. 性能优化：针对低版本平台（如安卓）进行了性能优化
4. 易用性：提供了清晰的 API 和详细的注释
5. 可扩展性：模块化设计，易于扩展和维护

使用建议

1. 按需导入：根据需要导入具体的工具函数，避免全量导入
2. 遵循命名规范：使用时遵循函数的命名规范和参数要求
3. 注意平台差异：虽然已做了多端兼容，但在使用某些函数时仍需注意平台差异
4. 结合文档使用：参考本文档和函数注释，正确使用工具函数

维护说明

• 新增工具函数时，请按照模块分类添加到相应文件中
• 为新函数添加详细的 JSDoc 注释
• 确保函数的多端兼容性
• 更新本文档，保持文档与代码同步

---

通过使用这些工具函数，可以大大提高开发效率，减少重复代码，使项目更加规范和易于维护。