Template
118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
---
|
|
name: v3-use-utils
|
|
description: 项目内置工具函数使用教程，涵盖验证、日期格式化、CSS 变量、权限判断、本地存储等工具。当用户提到以下任何场景时都应触发：使用工具函数、调用 utils、格式化日期、判断权限、操作 localStorage、获取/设置 CSS 变量、验证数据类型、判断外链、获取/存储 Token。即使用户没有明确说 Utils，只要意图是使用项目内置的通用工具函数就应该使用此 Skill。
|
|
metadata:
|
|
author: pany
|
|
version: "2026.06.03"
|
|
---
|
|
|
|
# 内置工具函数使用教程
|
|
|
|
项目在 `src/common/utils` 目录下提供了一组通用工具函数，通过路径别名 `@@/utils/` 导入。
|
|
|
|
本 Skill 定义的是项目内置的工具函数，当这些函数不存在时，以用户需求为准，新增对应函数。
|
|
|
|
## 验证工具 `@@/utils/validate`
|
|
|
|
```ts
|
|
import { isArray, isString, isExternal } from "@@/utils/validate"
|
|
|
|
// 判断是否为数组
|
|
isArray([1, 2, 3]) // true
|
|
|
|
// 判断是否为字符串
|
|
isString("hello") // true
|
|
|
|
// 判断是否为外链（以 http(s)://、mailto:、tel: 开头）
|
|
isExternal("https://example.com") // true
|
|
isExternal("/dashboard") // false
|
|
```
|
|
|
|
## 日期格式化 `@@/utils/datetime`
|
|
|
|
基于 dayjs 封装，无效日期返回 `"N/A"`。
|
|
|
|
```ts
|
|
import { formatDateTime } from "@@/utils/datetime"
|
|
|
|
// 默认格式 YYYY-MM-DD HH:mm:ss
|
|
formatDateTime("2026-01-15T10:30:00") // "2026-01-15 10:30:00"
|
|
|
|
// 自定义格式
|
|
formatDateTime("2026-01-15", "YYYY/MM/DD") // "2026/01/15"
|
|
|
|
// 支持时间戳
|
|
formatDateTime(1737000000000) // 格式化后的日期时间
|
|
|
|
// 无效输入
|
|
formatDateTime("invalid") // "N/A"
|
|
```
|
|
|
|
## CSS 变量 `@@/utils/css`
|
|
|
|
读取和设置 CSS 变量（变量名必须以 `--` 开头）。`getCssVar` 未找到变量时返回空串 `""`，不是 `undefined`。
|
|
|
|
```ts
|
|
import { getCssVar, setCssVar } from "@@/utils/css"
|
|
|
|
// 获取全局 CSS 变量
|
|
const color = getCssVar("--el-color-primary")
|
|
|
|
// 设置全局 CSS 变量
|
|
setCssVar("--el-color-primary", "#409eff")
|
|
|
|
// 操作指定元素上的 CSS 变量
|
|
const el = document.querySelector(".container") as HTMLElement
|
|
setCssVar("--bg-color", "#fff", el)
|
|
```
|
|
|
|
## 权限判断 `@@/utils/permission`
|
|
|
|
基于当前用户角色或权限判断是否拥有指定权限，内部读取 `useUserStore().roles` 和 `useUserStore().permissions`。
|
|
|
|
```ts
|
|
import { checkPermission } from "@@/utils/permission"
|
|
|
|
// 判断当前用户是否拥有 admin 或 editor 角色
|
|
if (checkPermission(["admin", "editor"])) {
|
|
// 有权限
|
|
}
|
|
|
|
// 判断当前用户是否拥有指定权限
|
|
if (checkPermission(["permission:button-level"])) {
|
|
// 有权限
|
|
}
|
|
```
|
|
|
|
适用于模板中 `v-permission` 指令无法覆盖的场景（如在 TS 逻辑中做条件判断）。
|
|
|
|
## 本地存储 `@@/utils/local-storage`
|
|
|
|
对 localStorage 的类型安全封装，所有 key 统一由 `@@/constants/cache-key` 中的 `CacheKey` 管理。
|
|
|
|
```ts
|
|
import { getToken, setToken, removeToken } from "@@/utils/local-storage"
|
|
|
|
// Token 操作
|
|
setToken("eyJhbGciOiJIUzI1NiJ9...")
|
|
const token = getToken()
|
|
removeToken()
|
|
```
|
|
|
|
可用函数一览：
|
|
|
|
| 分组 | 函数 | 说明 |
|
|
|------|------|------|
|
|
| Token | `getToken` / `setToken` / `removeToken` | 用户认证令牌 |
|
|
| 布局配置 | `getLayoutsConfig` / `setLayoutsConfig` / `removeLayoutsConfig` | 系统布局设置 |
|
|
| 侧边栏 | `getSidebarStatus` / `setSidebarStatus` | 侧边栏展开/收起状态 |
|
|
| 主题 | `getActiveThemeName` / `setActiveThemeName` | 当前主题名称 |
|
|
| 标签栏 | `getVisitedViews` / `setVisitedViews` / `getCachedViews` / `setCachedViews` | 标签页缓存 |
|
|
|
|
## 使用原则
|
|
|
|
1. 优先使用这些内置工具，不要重复造轮子
|
|
2. 需要新增 localStorage 存储项时，先在 `CacheKey` 中定义 key，再在 `local-storage.ts` 中添加对应的 get / set 函数
|
|
3. 需要新增通用工具时，根据功能归类到对应文件，或创建新的工具文件
|
|
4. 工具文件之间可以互相引用（如 `permission.ts` 引用了 `@@/utils/validate`），新建工具时也可复用已有工具
|