---
name: utils-toolkit
description: >
  Duooomi 应用工具函数集使用指南。当需要页面导航、本地存储、CDN URL 处理、文件上传/转换、WebView 打开、权限请求、样式合并、邮箱/手机号验证时触发。导入路径 `@/utils`。包含：push/replace/goBack 导航、storage 存储、videoUrlCache、uploadFile、mp4ToWebpUrl、cn() 样式合并、CDN 工具、相机权限、aniStorage 动画缓存。
---

# Utils 工具函数集

```tsx
import { push, replace, goBack, storage, videoUrlCache, uploadFile, openUrl, screenWidth, screenHeight, isValidEmail, isValidPhone } from '@/utils'
import { cn } from '@/utils/cn'
import { extractCdnKey, isFromCdn, buildCdnUrl } from '@/utils/getCDNKey'
import { ensureCameraPermission } from '@/utils/permissions'
import { aniStorage } from '@/utils/aniStorage'
```

## 导航

```tsx
push('/profile', { id: '123' })   // router.push
replace('/auth')                   // router.replace
goBack()                           // router.back
```

## 存储 (storage)

基于 AsyncStorage，按 APP_VERSION 隔离的带缓存单例。

```tsx
await storage.set('key', value)
const val = await storage.get<T>('key')
await storage.clear()
```

## 视频缓存 (videoUrlCache)

```tsx
const cached = await videoUrlCache.get(originalUrl, width)
await videoUrlCache.set(originalUrl, finalUrl, width)
```

## 文件上传/转换

```tsx
const url = await uploadFile({ uri, mimeType: 'image/jpeg', fileName: 'photo.jpg' })
const webpUrl = await mp4ToWebpUrl({ videoUrl, width: 256, height: 256, quality: 70 })
const aniUrl = await uploadAndConvertToAniUrl({ url, width: 360, height: 360, fps: '24' })
```

## WebView

```tsx
await openUrl('https://example.com', '标题')          // 系统浏览器
await openUrl('https://example.com', '标题', true)     // 内嵌WebView
```

## CDN 工具

CDN: `https://cdn.roasmax.cn/`

```tsx
extractCdnKey('https://cdn.roasmax.cn/material/xxx.mp4')  // 'material/xxx.mp4'
isFromCdn(url)                                              // boolean
buildCdnUrl('material/xxx.mp4')                            // 完整URL
```

## 样式合并 (cn)

```tsx
<Block className={cn('flex-1 bg-black', isActive && 'bg-primary', className)} />
```

## 权限

```tsx
const granted = await ensureCameraPermission()  // 检查->请求->引导设置
```

## ANI 缓存 (aniStorage)

```tsx
await aniStorage.set(url, arrayBuffer)
const data = await aniStorage.get(url)
await aniStorage.has(url) / .delete(url) / .clear()
```

## 验证

```tsx
isValidEmail('test@example.com')   // true
isValidPhone('13800138000')        // true
```

## 屏幕尺寸

```tsx
screenWidth / screenHeight
```