Leftsky Vue3 帮助工程

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

📦 安装

npm install
# 或
yarn install
# 或
pnpm install

🚀 快速开始

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

📖 API 文档

usePagination - 分页管理 Hook

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

基本用法

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 | 在头部添加最新数据 |

高级用法

// 自定义数据处理
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，支持相对时间、绝对时间等多种格式。

基本用法

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，提供触摸状态管理和滑动计算。

基本用法

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。

基本用法

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。

基本用法

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