签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,104 +1,47 @@
-# 9.16 工具函数
+# 9.17 工具函数

 :::tip 概述
-本节介绍前端项目中常用的工具函数，包括本地存储、类型判断、URL 处理和权限检查等。
+`ui/src/utils` 收敛通用能力：http 封装、存储、鉴权、校验、日期、下载、格式化、DOM、颜色等。业务页面优先查这里，避免重复造轮子。
 :::

-## Storage 本地存储
+## 主要工具

-```typescript
-import { storage } from '@/utils/Storage';
+| 文件/目录 | 职责 |
+|---|---|
+| http/ | axios 封装（[9.4](/zh/frontend/http.html)） |
+| Storage.ts | 持久化封装（localStorage 统一入口） |
+| auth.ts | token/权限辅助（菜单树查找 findTreeByPath 等） |
+| validate.ts | 校验（手机号、邮箱、URL、长度等） |
+| dateUtil.ts / formatTime.ts | 日期解析与格式化（dayjs 封装） |
+| downloadFile.ts | URL 文件下载 |
+| urlUtils.ts | URL 参数处理 |
+| domUtils.ts | DOM 操作辅助 |
+| color.ts | 颜色计算（主题） |
+| index.ts | 聚合出口 |
+| is/ | 类型判断 |
+| lib/ helper/ file/ | 子域工具（库封装、文件处理等） |
+| propTypes.ts | 组件 props 类型 |
+| useLockFn.ts | 防重入函数包装 |
+| lodashChunk.ts | 数组分块 |
+| wartermark.ts | 水印 |
+| log.ts / env.ts / browser-type.ts | 日志、环境、浏览器探测 |

-// 存储（带过期时间）
-storage.set('key', value, 7 * 24 * 60 * 60 * 1000);  // 7天
+## 使用规约

-// 读取
-const value = storage.get('key', defaultValue);
+- **统一入口**：`import { xxx } from '@/utils'`（聚合出口），保持引用一致
+- **纯函数优先**：工具函数不做 IO 副作用（下载类除外）
+- **不引业务**：utils 不得 import api/views/store（防环依赖）
+- **新增前检索**：先确认 index.ts 是否已有同能力

-// 删除
-storage.remove('key');
+## 高频组合

-// 清空
-storage.clear();
-```
+| 场景 | 组合 |
+|---|---|
+| 导出下载 | downloadFile（配合 Export 接口返回的 URL） |
+| 时间展示 | formatTime（列表列、日志时间） |
+| 表单校验 | validate（与后端 binding 标签双侧校验） |
+| 记住页签/主题 | Storage（store 持久化底层） |

-## 类型判断
+## 相关

-```typescript
-import { isString, isNumber, isArray, isObject } from '@/utils/is';
-
-isString('hello');    // true
-isNumber(123);        // true
-isArray([1, 2]);      // true
-isObject({ a: 1 });   // true
-```
-
-## URL 工具
-
-```typescript
-import { setObjToUrlParams } from '@/utils/urlUtils';
-
-// 将对象拼接到 URL 参数
-const url = setObjToUrlParams('/api/example/page', { pageNo: 1, pageSize: 10 });
-// '/api/example/page?pageNo=1&pageSize=10'
-```
-
-## 权限工具
-
-```typescript
-import { usePermission } from '@/hooks/web/usePermission';
-
-const { hasSomePermission, hasEveryPermission } = usePermission();
-
-// 检查单个权限
-hasSomePermission('sys:user:add');
-
-// 检查多个权限（满足任一）
-hasSomePermission(['sys:user:add', 'sys:user:update']);
-```
-
-## 日期工具
-
-```typescript
-import { formatToDate, formatToDateTime } from '@/utils/dateUtil';
-
-formatToDate(new Date());          // '2026-09-21'
-formatToDateTime(new Date());      // '2026-09-21 14:30:00'
-```
-
-## 深拷贝
-
-项目使用 `lodash-es` 提供的 `cloneDeep` 函数进行深拷贝：
-
-```typescript
-import { cloneDeep } from 'lodash-es';
-
-const obj = { a: 1, b: { c: 2 } };
-const copy = cloneDeep(obj);
-copy.b.c = 3;
-console.log(obj.b.c);  // 2（原对象不受影响）
-```
-
-:::warning 功能未实现
-以下工具函数尚未在项目中实现，仅供参考。
-:::
-
-:::warning 注意
-项目中没有封装自定义的 `deepClone` 或 `numberUtil`、`fileUtil` 工具。数字格式化和文件大小格式化等功能建议使用 `lodash-es`、`Intl.NumberFormat` 等成熟方案自行处理。
-:::
-
-## 防抖与节流
-
-```typescript
-import { useDebounceFn, useThrottleFn } from '@vueuse/core';
-
-// 防抖：停止输入 300ms 后执行
-const debouncedSearch = useDebounceFn((keyword: string) => {
-  fetchData(keyword);
-}, 300);
-
-// 节流：每 200ms 最多执行一次
-const throttledScroll = useThrottleFn(() => {
-  handleScroll();
-}, 200);
-```
+- [9.18 Hooks 与枚举](/zh/frontend/hooks-enums.html)