vue3-help/README.md

Vue3 帮助工程

# Leftsky Vue3 帮助工程

一个基于 Vue 3 + TypeScript 的实用工具库，提供了多个常用的 Composition API hooks，帮助开发者快速构建高质量的 Vue 应用。

## 📦 安装

```bash
npm install
# 或
yarn install
# 或
pnpm install
```

## 🚀 快速开始

```typescript
import { usePagination, useOnlineTime, useTouch, useDictionary, useSkin } from './src/hooks'
```

## 📖 API 文档

### usePagination - 分页管理 Hook

一个功能强大的分页数据管理 Hook，支持自动缓存、数据处理、增量加载等特性。

#### 基本用法

```typescript
import { usePagination } from './src/hooks'

const { fullList, nextPage, loadStatus, totalNum, updateItem } = usePagination({
  api: fetchUserList, // 必须：数据获取 API
  pageSize: 20,       // 每页数量，默认 10
  initParams: {       // 初始化参数
    category: 'active'
  }
})

// 加载下一页
await nextPage()

// 刷新数据（重新从第一页开始）
await nextPage(true)

// 更新单个数据项
updateItem({ id: 1, name: '新名称' })
```

#### 配置选项

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `api` | `Function` | 必须 | 数据获取 API 函数 |
| `initParams` | `Object` | `{}` | 初始化请求参数 |
| `pageSize` | `number` | `10` | 每页数据量 |
| `pageSizeParam` | `string` | `'size'` | 分页大小参数名 |
| `pageNumParam` | `string` | `'page'` | 页码参数名 |
| `dataListName` | `string` | `'data'` | 响应数据中列表字段名 |
| `dataItemDeal` | `Function` | `(item) => item` | 数据项处理函数 |
| `dataFilter` | `Function` | `(item) => item` | 数据过滤函数 |
| `primaryKey` | `string` | `'id'` | 数据主键字段 |
| `autoCacheNextPage` | `boolean` | `true` | 是否自动缓存下一页 |
| `cacheNextPageAtFirst` | `boolean` | `true` | 是否在首次请求时缓存下一页 |
| `autoCacheImg` | `boolean` | `true` | 是否自动缓存图片 |

#### 返回值

| 属性 | 类型 | 说明 |
|------|------|------|
| `fullList` | `Ref<any[]>` | 完整数据列表 |
| `totalNum` | `Ref<number>` | 数据总数 |
| `isComplete` | `Ref<boolean>` | 是否加载完成 |
| `loadStatus` | `ComputedRef<string>` | 加载状态：'loading' \| 'no-more' \| 'more' |
| `nextPage` | `Function` | 加载下一页函数 |
| `updateItem` | `Function` | 更新数据项函数 |
| `joinHead` | `Function` | 在头部添加最新数据 |

#### 高级用法

```typescript
// 自定义数据处理
const { fullList, nextPage } = usePagination({
  api: fetchData,
  dataItemDeal: (item) => ({
    ...item,
    displayName: `${item.firstName} ${item.lastName}`,
    avatar: item.avatar || '/default-avatar.png'
  }),
  dataFilter: (item) => item.status === 'active', // 只显示活跃用户
  primaryKey: 'userId' // 自定义主键
})

// 更新特定数据项
updateItem({
  userId: 123,
  fetchFun: (item) => item.userId === 123, // 自定义查找逻辑
  updateFun: (oldItem) => ({ ...oldItem, status: 'updated' }) // 自定义更新逻辑
})

// 删除数据项
updateItem({ userId: 123 }, true)
```

### useOnlineTime - 时间格式化 Hook

处理各种时间显示格式的 Hook，支持相对时间、绝对时间等多种格式。

#### 基本用法

```typescript
import { useOnlineTime } from './src/hooks'

const timestamp = 1640995200 // Unix 时间戳
const {
  visitorOnlineTime,
  trendOnlineTime,
  notifyTrendOnlineTime,
  trendPublishTime
} = useOnlineTime(timestamp)

console.log(visitorOnlineTime()) // "2天前" 或 "刚刚"
console.log(trendOnlineTime())   // "2022-01-01" 或 "2小时前"
console.log(trendPublishTime())  // "2022/01/01 08:00"
```

#### 方法说明

| 方法 | 返回值示例 | 说明 |
|------|------------|------|
| `visitorOnlineTime()` | "2天前", "刚刚" | 访客时间格式 |
| `trendOnlineTime(defaultDay)` | "2022-01-01", "2小时前" | 动态时间格式 |
| `notifyTrendOnlineTime()` | "01月01日 08:00" | 通知时间格式 |
| `trendPublishTime()` | "2022/01/01 08:00" | 发布时间格式 |
| `noticeOnlineTime()` | "01月01日 08:00" | 通知完整时间 |
| `userCardOnlineTime()` | "2天内来过" | 用户卡片时间 |

### useTouch - 触摸事件处理 Hook

处理移动端触摸事件的 Hook，提供触摸状态管理和滑动计算。

#### 基本用法

```typescript
import { useTouch } from './src/hooks'

const { touchState, slideState, touchstart, touchmove, touchend } = useTouch()

// 在模板中使用
// <div @touchstart="touchstart" @touchmove="touchmove" @touchend="touchend">
//   滑动距离: {{ slideState.x }}, {{ slideState.y }}
// </div>
```

#### 返回值

| 属性 | 类型 | 说明 |
|------|------|------|
| `touchState` | `Reactive` | 触摸状态对象，包含 start/move/end 坐标 |
| `slideState` | `ComputedRef` | 计算的滑动距离 {x, y} |
| `touchstart` | `Function` | 触摸开始事件处理器 |
| `touchmove` | `Function` | 触摸移动事件处理器 |
| `touchend` | `Function` | 触摸结束事件处理器 |

### useDictionary - 枚举字典 Hook

处理枚举值与显示文本转换的 Hook。

#### 基本用法

```typescript
import { useDictionary } from './src/hooks'

const enumData = {
  enums: [
    {
      name: 'userStatus',
      values: [
        { no: 1, value: '活跃' },
        { no: 2, value: '禁用' },
        { no: 0, value: '未知' }
      ]
    }
  ]
}

const { enumChange, enumChangeReverse } = useDictionary(enumData)

console.log(enumChange('userStatus', 1))        // "活跃"
console.log(enumChangeReverse('userStatus', '活跃')) // 1
```

### useSkin - 皮肤主题 Hook

管理应用皮肤主题的 Hook。

#### 基本用法

```typescript
import { useSkin } from './src/hooks'

const skinData = {
  skins: [
    {
      name: 'default',
      version: '1.0.0',
      description: '默认主题',
      author: 'leftsky',
      part: {
        images: {
          logo: '/images/logo.png',
          background: '/images/bg.jpg'
        }
      }
    }
  ]
}

const { get } = useSkin(skinData)

console.log(get('logo'))       // "/images/logo.png"
console.log(get('background')) // "/images/bg.jpg"
```

## 🛠️ 工具函数

项目还包含了一些实用的工具函数，位于 `src/utils/` 目录：

- `formatter.ts` - 数据格式化工具
- `validate.ts` - 数据验证工具  
- `toolMethods.ts` - 通用工具方法

## 🎯 使用场景

- **usePagination**: 列表页面、表格分页、无限滚动
- **useOnlineTime**: 社交应用、评论系统、动态时间显示
- **useTouch**: 移动端滑动操作、手势识别
- **useDictionary**: 状态显示、枚举值转换
- **useSkin**: 主题切换、多皮肤应用

## 📝 注意事项

1. 确保在 Vue 3 环境中使用
2. TypeScript 支持完整的类型提示
3. 所有 Hook 都遵循 Composition API 规范
4. 建议配合 Vue 3.2+ 的 `<script setup>` 语法使用

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 📄 许可证

MIT License