# vue-crud

**Repository Path**: chadounet/vue-crud

## Basic Information

- **Project Name**: vue-crud
- **Description**: 一个基于 Vue 3 Composition API 的强大 CRUD 操作组合式函数，提供完整的增删改查功能，支持分页、表单验证、状态管理和生命周期钩子。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/chadounet/vue-crud
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-30
- **Last Updated**: 2025-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# useCrud 组合式函数

一个基于 Vue 3 Composition API 的强大 CRUD 操作组合式函数，提供完整的增删改查功能，支持分页、表单验证、状态管理和生命周期钩子。

## 特性

- 🚀 **开箱即用** - 提供完整的 CRUD 操作方法
- 📊 **分页支持** - 内置分页逻辑和状态管理
- 🔄 **状态管理** - 智能的操作状态跟踪
- 🎣 **生命周期钩子** - 丰富的钩子函数支持自定义逻辑
- 📝 **表单处理** - 集成表单验证和重置功能
- 🌳 **树形表格** - 支持树形数据的选择操作
- 💡 **TypeScript 友好** - 完整的类型定义
- 🎯 **Element Plus 集成** - 与 Element Plus 组件库深度集成

## 基本用法

### 1. 导入组合式函数

```javascript
// 注意：dist/index.js 建议拷贝到项目的 components/vue-crud 目录下面
import useCrud from './components/vue-crud/index.js'
import CRUD from './components/vue-crud/index.js'
```

### 2. 定义 API 方法

```javascript
const userApi = {
  list: (params) => api.get('/users', { params }),
  add: (data) => api.post('/users', data),
  edit: (data) => api.put(`/users/${data.id}`, data),
  delete: (ids) => api.delete('/users', { data: { ids } }),
  get: (id) => api.get(`/user/${data.id}`),
  export: (params) => api.get('/users/export', { params })
}
```

### 3. 初始化 CRUD 实例

```javascript
const crud = useCrud({
  title: '用户',
  apiService: userApi,
  idField: 'id',
  rowsField: 'list',
  pageField: 'page',
  sizeField: 'size',
  totalField: 'total',
  promptField: 'name',
  queryParams: reactive({
    name: '',
    phone: ''
  }),
  form: reactive({
    id: '',
    name: '',
    phone: '',
    email: ''
  }),
  formRef,
  tableRef
})
```

## 配置选项

### 基础配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | `string` | `''` | 模块标题，用于动态标题生成 |
| `data` | `array` | `[]` | 表格数据 |
| `selections` | `array` | `[]` | 选中的数据项 |
| `hooks` | `object` | `{}` | 生命周期钩子函数 |
| `apiService` | `object` | - | CRUD API 方法对象 |
| `props` | `object` | `{ searchVisible: true, searchFormVisible: true }` | 自定义扩展属性 |

### 字段配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `idField` | `string` | `'id'` | 数据项 ID 字段名 |
| `rowsField` | `string` | `'rows'` | 列表数据字段名 |
| `pageField` | `string` | `'page'` | 当前页码字段名 |
| `sizeField` | `string` | `'size'` | 每页大小字段名 |
| `totalField` | `string` | `'total'` | 总数字段名 |
| `promptField` | `string` | `'id'` | 操作提示字段名 |

### 查询配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `queryParams` | `object` | `{}` | 查询参数对象 |
| `time` | `number` | `50` | 查询等待时间（毫秒） |
| `autoQuery` | `boolean` | `true` | 页面加载后自动查询 |

### 分页配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `page` | `number` | `1` | 当前页码 |
| `size` | `number` | `10` | 分页大小 |
| `total` | `number` | `0` | 数据总数 |

### 引用配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `form` | `object` | `{}` | 表单数据对象 |
| `formRef` | `ref` | `null` | 表单组件引用 |
| `tableRef` | `ref` | `null` | 表格组件引用 |

## API 方法

### 操作方法

| 方法名 | 参数 | 说明 |
|--------|------|------|
| `handleRefresh()` | - | 刷新数据（重置到第一页） |
| `handleClear(toQuery, useDefaultQueryParams)` | `boolean, boolean` | 清空查询条件 |
| `handleQuery()` | - | 执行查询 |
| `handleAdd()` | - | 新增操作 |
| `handleEdit(data)` | `object` | 编辑操作 |
| `handleDelete(data)` | `object\|array` | 删除操作 |
| `handleExport()` | - | 导出操作 |
| `handleCancel()` | - | 取消新增/编辑 |
| `handleSubmit()` | - | 提交表单 |

### 分页方法

| 方法名 | 参数 | 说明 |
|--------|------|------|
| `handlePageChange(current)` | `number` | 当前页改变 |
| `handleSizeChange(size)` | `number` | 分页大小改变 |
| `handleSelectionChange(selections)` | `array` | 选中项改变 |

### 树形表格方法

| 方法名 | 参数 | 说明 |
|--------|------|------|
| `handleTreeSelectionAllChange(selections)` | `array` | 树形表格全选 |
| `handleTreeSelectionChange(selections, row)` | `array, object` | 树形表格单选 |

### 工具方法

| 方法名 | 参数 | 说明 |
|--------|------|------|
| `notifySuccess(message)` | `string` | 成功提示 |
| `notifyError(message)` | `string` | 错误提示 |
| `notify(title, type)` | `string, string` | 通用提示 |

## 响应式属性

### 计算属性

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `formTitle` | `string` | 动态标题（新增/编辑/查看） |
| `formStatus` | `number` | 表单操作状态（新增/编辑） |
| `formVisible` | `boolean` | 表单对话框是否可见 |
| `loading` | `boolean` | 是否查询中 |
| `commitLoading` | `boolean` | 是否提交中 |
| `deleteLoading` | `boolean` | 是否删除中 |
| `exportLoading` | `boolean` | 是否导出中 |

## 生命周期钩子

### 查询相关

- `beforeQuery` - 查询前
- `afterQuery` - 查询后
- `afterQueryError` - 查询错误

### 新增/编辑相关

- `beforeToCU` - 进入新增/编辑前
- `afterToCU` - 进入新增/编辑后
- `beforeToAdd` - 进入新增前
- `afterToAdd` - 进入新增后
- `beforeToEdit` - 进入编辑前
- `afterToEdit` - 进入编辑后
- `beforeValidate` - 表单验证前
- `afterValidate` - 表单验证后
- `beforeSubmit` - 提交前
- `afterSubmit` - 提交后
- `afterSubmitError` - 提交错误
- `beforeCancel` - 取消前
- `afterCancel` - 取消后

### 删除相关

- `beforeDelete` - 删除前
- `afterDelete` - 删除后
- `afterDeleteError` - 删除错误

### 导出相关

- `beforeExport` - 导出前
- `afterExport` - 导出后
- `afterExportError` - 导出错误

## 完整使用示例

以下是一个完整的用户管理页面示例：

```vue
<template>
  <div class="crud-container">
    <el-card class="box-card">
      <template #header>
        <div class="card-header">
          <span>用户数据管理</span>
          <div>
            <el-button type="primary" @click="handleAdd" :icon="Plus">新增用户</el-button>
            <el-button type="primary" @click="handleEdit" :icon="Edit" :disabled="!hasSelection">编辑用户</el-button>
            <el-button type="success" @click="handleRefresh" :icon="Refresh" :loading="loading">刷新数据</el-button>
            <el-button type="danger" @click="handleDelete" :icon="Delete" :disabled="!hasSelection">删除用户</el-button>
          </div>
        </div>
      </template>
      
      <el-table
        v-loading="loading" 
        :data="data" 
        ref="tableRef" 
        @selection-change="handleSelectionChange"
        style="width: 100%"
        border
        stripe
      >
        <el-table-column type="selection" width="50" align="center" fixed="left" />
        <el-table-column prop="id" label="ID" width="80" sortable />
        <el-table-column prop="name" label="姓名" width="120" show-overflow-tooltip />
        <el-table-column prop="phone" label="手机号" width="150" show-overflow-tooltip />
        <el-table-column prop="email" label="邮箱" min-width="200" show-overflow-tooltip />
        <el-table-column label="操作" width="180" fixed="right">
          <template #default="{ row }">
            <el-button type="primary" size="small" @click="handleEdit(row)" :icon="Edit">编辑</el-button>
            <el-button type="danger" size="small" @click="handleDelete(row)" :icon="Delete">删除</el-button>
          </template>
        </el-table-column>
      </el-table>
      
      <el-pagination
        v-model:page-size="size"
        v-model:current-page="page"
        :total="total"
        :page-sizes="[10, 20, 50, 100]"
        layout="total, sizes, prev, pager, next, jumper"
        @current-change="handlePageChange"
        @size-change="handleSizeChange"
      />
    </el-card>

    <!-- 用户表单对话框 -->
    <el-dialog
      :model-value="formVisible"
      :title="formTitle"
      width="500px"
      @close="handleCancel"
    >
      <el-form
        ref="formRef"
        :model="form"
        :rules="formRules"
        label-width="80px"
        :disabled="commitLoading"
      >
        <el-form-item label="姓名" prop="name">
          <el-input v-model="form.name" placeholder="请输入姓名" clearable />
        </el-form-item>
        <el-form-item label="手机号" prop="phone">
          <el-input v-model="form.phone" placeholder="请输入手机号" clearable />
        </el-form-item>
        <el-form-item label="邮箱" prop="email">
          <el-input v-model="form.email" placeholder="请输入邮箱" type="email" clearable />
        </el-form-item>
      </el-form>
      <template #footer>
        <div class="dialog-footer">
          <el-button @click="handleCancel" :disabled="commitLoading">取消</el-button>
          <el-button type="primary" :loading="commitLoading" @click="handleSubmit">
            {{ commitLoading ? '提交中...' : '确定' }}
          </el-button>
        </div>
      </template>
    </el-dialog>
  </div>
</template>

<script setup>
import { ref, reactive, computed, toRefs } from 'vue'
import { Edit, Delete, Plus, Refresh } from '@element-plus/icons-vue'
import { userApi } from '../api/userApi'
import useCrud from '../components/vue-crud/index.js'

// 表格和表单引用
const tableRef = ref()
const formRef = ref()

// 表单数据
const form = reactive({
  id: '',
  name: '',
  phone: '',
  email: ''
})

// 查询参数
const queryParams = reactive({
  name: '',
  phone: ''
})

// 表单验证规则
const formRules = {
  name: [
    { required: true, message: '请输入姓名', trigger: 'blur' },
    { min: 2, max: 10, message: '姓名长度在 2 到 10 个字符', trigger: 'blur' }
  ],
  phone: [
    { required: true, message: '请输入手机号', trigger: 'blur' },
    { pattern: /^1[3-9]\d{9}$/, message: '请输入正确的手机号码', trigger: 'blur' }
  ],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱地址', trigger: ['blur', 'change'] }
  ]
}

// 初始化 CRUD
const crud = useCrud({
  title: '用户',
  apiService: userApi,
  idField: 'id',
  rowsField: 'list',
  pageField: 'page',
  sizeField: 'size',
  totalField: 'total',
  promptField: 'name',
  queryParams,
  form,
  formRef,
  tableRef,
  hooks: {
    beforeToCU: () => {
      // 新增编辑前的自定义逻辑
      return true
    },
    afterSubmit: () => {
      // 提交成功后的自定义逻辑
      console.log('用户操作成功')
    }
  }
})

// 解构方法
const {
  handleRefresh,
  handleAdd,
  handleEdit,
  handleDelete,
  handleSubmit,
  handleCancel,
  handlePageChange,
  handleSizeChange,
  handleSelectionChange
} = crud

// 解构响应式数据
const {
  data,
  formVisible,
  formTitle,
  hasSelection,
  loading,
  commitLoading,
  page,
  size,
  total
} = toRefs(crud)
</script>
```

## 常见问题

### Q: 如何自定义字段映射？

A: 通过配置字段选项来映射后端返回的字段名：

```javascript
const crud = useCrud({
  idField: 'userId',        // 后端返回的 ID 字段名
  totalField: 'totalCount', // 后端返回的 总数 字段名
  rowsField: 'dataList',    // 后端返回的 列表 字段名
  // ...
})
```

### Q: 如何在操作前后执行自定义逻辑？

A: 使用生命周期钩子：

```javascript
const crud = useCrud({
  hooks: {
    beforeSubmit: async () => {
      // 提交前的验证逻辑
      const isValid = await customValidation()
      return isValid // 返回 false 会阻止提交
    },
    afterQuery: () => {
      // 查询后的数据处理
      console.log('数据加载完成')
    }
  }
})
```

### Q: 如何处理树形数据？

A: 使用提供的树形表格方法：

```javascript
// 在模板中
<el-table
  @select-all="handleTreeSelectionAllChange"
  @select="handleTreeSelectionChange"
>
  <!-- 表格列 -->
</el-table>
```

## 许可证

MIT License