uni-vue-utils

一套为 uni-app 和 Vue 3 设计的高度封装的工具集，提供网络请求、用户认证、表单处理、列表分页等功能。

✨ 特性

• 🎯 组合式优先: 基于 Vue 3 Composition API，提供可复用、可组合的逻辑单元
• 🔒 类型安全: 全面拥抱 TypeScript，利用 Zod 实现端到端类型安全
• 🚀 自动化封装: 封装 Token 管理、加载状态、错误处理等繁琐逻辑
• 📦 开箱即用: 提供标准化的解决方案，减少决策成本

📦 安装

npm install uni-vue-utils

🚀 快速开始

1. 安装依赖

确保你的项目中已安装以下 peer dependencies：

npm install vue@^3.5.0 pinia@^3.0.4
npm install vee-validate@^4.12.6 @vee-validate/zod@^4.15.1 zod@^3.24.0
npm install @vueuse/core@^14.0.0

# @dcloudio/uni-app 会根据你的 uni-app 项目自动安装，无需手动安装
# 如果遇到 peer dependency 警告，可以使用 --legacy-peer-deps

2. 初始化

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { setupNavigationGuards } from 'uni-vue-utils'

const app = createApp(App)
app.use(createPinia())

// 设置导航守卫（可选）
setupNavigationGuards()

app.mount('#app')

3. 使用示例

认证

import { useAuth } from 'uni-vue-utils'

const { loginPassword, loading, error } = useAuth()

const handleLogin = async () => {
  try {
    await loginPassword({
      username: 'admin',
      password: '123456'
    })
    console.log('登录成功')
  } catch (e) {
    console.error('登录失败', e)
  }
}

API 请求

import { useApi } from 'uni-vue-utils'
import { getUserProfile } from '@/api/user'

const { data, loading, error, execute } = useApi(getUserProfile)

// 执行请求
onMounted(() => {
  execute()
})

表单处理

import { useForm } from 'uni-vue-utils'
import { z } from 'zod'

const schema = z.object({
  username: z.string().min(1, '请输入用户名'),
  password: z.string().min(6, '密码至少6位'),
})

const { values, errors, isSubmitting, onSubmit } = useForm(schema)

const handleSubmit = onSubmit(async (formValues) => {
  // 提交表单
  await submitForm(formValues)
})

分页

import { usePagination } from 'uni-vue-utils'
import { getProductList } from '@/api/product'

const {
  list,
  loading,
  hasMore,
  refresh,
  loadMore,
  pagination
} = usePagination(getProductList, { pageSize: 10 })

// 刷新列表
onMounted(() => {
  refresh()
})

📚 API 文档

Composables

• useApi - 通用 API 请求状态封装
• useAuth - 全局认证中心
• useForm - 表单处理和验证
• usePagination - 列表分页（支持 offset 和 cursor 模式）
• useFilter - 筛选条件管理
• usePermission - 权限控制
• useScrollBehavior - 滚动行为（回到顶部、吸顶等）
• useWeChat - 微信登录

Stores

• useUserStore - 用户状态管理
• useAppStore - 应用状态管理

Utils

• request - 统一网络请求封装（自动 Token 注入、自动刷新）

Config

• API_PATHS - API 路径常量
• setupNavigationGuards - 导航守卫设置

🔧 配置

环境变量

在你的项目中创建 .env 文件：

VITE_API_BASE_URL=https://api.example.com
VITE_WECHAT_APP_ID=your_wechat_app_id
VITE_WECHAT_REDIRECT_URI=http://your-domain.com/pages/login/login
VITE_USE_MOCK=false
VITE_MOCK_URL=

API 路径配置

import { API_PATHS } from 'uni-vue-utils'

// API_PATHS.AUTH.LOGIN
// API_PATHS.USER.PROFILE
// API_PATHS.PRODUCT.LIST

📖 更多文档

详细使用说明请参考 完整文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT