# 9.16 工具函数

:::tip 概述
本节介绍前端项目中常用的工具函数，包括本地存储、类型判断、URL 处理和权限检查等。
:::

## Storage 本地存储

```typescript
import { storage } from '@/utils/Storage';

// 存储（带过期时间）
storage.set('key', value, 7 * 24 * 60 * 60 * 1000);  // 7天

// 读取
const value = storage.get('key', defaultValue);

// 删除
storage.remove('key');

// 清空
storage.clear();
```

:::tip Token 存储约定
访问令牌通过 Storage 管理（键名常量 `ACCESS_TOKEN`，实际键 `'ACCESS-TOKEN'`；本项目前端仅存访问令牌）。登出时清除本地存储**并调用** `/api/logout`（服务端吊销 refresh_token，见 [9.8 登录流程](/zh/frontend/login.html)）。
:::

## 类型判断

```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-10-02'
formatToDateTime(new Date());      // '2026-10-02 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);
```

## 字典工具

```typescript
import { getDictItemByCode } from '@/api/common/index';

// 按编码取字典项（下拉框数据源）
const options = await getDictItemByCode('example_status');
```

（接口详情见 [5.11 字典配置与使用](/zh/core/dict-guide.html)。）