z-crud-table

介绍

CrudTable 是一个高度抽象的业务组件，旨在统一项目中表格增删改查的操作体验和开发规范。

它通过“配置驱动”的方式，将一个完整表格页面的功能点抽象为以下几个核心 Prop：

API 配置： 通过 apiUrlQuery, apiUrlDetail, apiUrlCreate, apiUrlUpdate, apiUrlDelete 五个属性自动管理所有后端交互。

表格列配置： columns 数组用于动态渲染 el-table 的列，并支持插槽和表头提示。

弹窗表单配置： dialogFormConfig 数组与内置的 DynamicForm 组件联动，自动渲染新增和编辑时的弹窗表单。

此外，它还提供了丰富的插槽 (Slots) 和生命周期钩子 (Hooks)，允许开发者在不修改组件源码的情况下，轻松注入自定义的搜索条件、行内操作和提交前/后逻辑，在实现高度复用的同时保持了灵活性。 :::tip 提示 表格的请求、查询、编辑、删除接口类型分别为"GET"、"POST"、"PUT"、"DELETE"类型，否则会报错！ :::

安装

npm install z-crud-table

引用

案例

配置驱动

<template>
  <crud-table
      :api-url-query="apiUrls.query"
      :api-url-detail="apiUrls.detail"
      :api-url-create="apiUrls.create"
      :api-url-update="apiUrls.update"
      :api-url-delete="apiUrls.delete"
      :columns="tableColumns"
      :dialog-form-config="formConfig"
      :dialog-form-rules="formRules"
  />
</template>

<script setup lang="ts">
  import { ref } from 'vue';

  // 1. API 地址
  const apiUrls = {
    query: '/api/user/list',
    detail: '/api/user/detail',
    create: '/api/user/create',
    update: '/api/user/update',
    delete: '/api/user/delete',
  };

  // 2. 表格列配置
  const tableColumns = ref([
    { prop: 'username', label: '用户名', width: 150 },
    { prop: 'nickname', label: '昵称', width: 150 },
    { prop: 'email', label: '邮箱' },
    { prop: 'role', label: '角色', width: 150 },
    { prop: 'createTime', label: '创建时间', width: 150 },
  ]);

  // 3. 弹窗表单配置 (使用 DynamicForm)
  const formConfig = ref([
    { type: 'input', prop: 'username', label: '用户名' },
    { type: 'input', prop: 'nickname', label: '昵称' },
    { type: 'input', prop: 'email', label: '邮箱' },
    {
      type: 'select',
      prop: 'role',
      label: '角色',
      options: [
        { label: '管理员', value: 'admin' },
        { label: '普通用户', value: 'user' },
      ],
      // 自定义字段
      // componentProps: {
      //   placeholder: '请选择角色',
      //   // ✨ 在这里指定自定义的字段映射
      //   props: {
      //     label: 'dictName', // 将 label 映射到 dictLabel
      //     value: 'dictCode'  // 将 value 映射到 dictValue
      //   }
      // },
    },
    { type: 'textarea', prop: 'description', label: '备注' },
    {
      label: '创建时间',
      prop: 'createTime',
      type: 'date-picker', // 对应 DynamicForm 中的 v-if
      componentProps: {
        type: 'date',      // Element Plus 原生属性，指定为日期选择
        valueFormat: 'YYYY-MM-DD', // 指定绑定值的格式
        placeholder: '请选择日期',
        clearable: true
      }
    },
  ]);

  // 4. 弹窗表单校验规则
  const formRules = ref({
    username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
    role: [{ required: true, message: '请选择角色', trigger: 'change' }],
  });
</script>

自定义搜索区 & 表格列内容

<template>
  <crud-table
    :api-url-query="apiUrls.query"
    :api-url-detail="apiUrls.detail"
    :api-url-create="apiUrls.create"
    :api-url-update="apiUrls.update" 
    :api-url-delete="apiUrls.delete"
    :columns="tableColumns"
    :dialog-form-config="formConfig"
    :dialog-form-rules="formRules"
  >
    <template #query-conditions="{ searchForm }">
      <el-form-item label="用户名">
        <el-input v-model="searchForm.username" placeholder="请输入用户名" clearable />
      </el-form-item>
      <el-form-item label="状态">
        <el-select v-model="searchForm.status" placeholder="请选择状态" clearable>
          <el-option label="启用" :value="1" />
          <el-option label="禁用" :value="0" />
        </el-select>
      </el-form-item>
    </template>
    
    <template #status="{ row }">
      <el-tag v-if="row.status === 1" type="success">启用</el-tag>
      <el-tag v-else type="danger">禁用</el-tag>
    </template>

    <template #role="{ row }">
      <el-tag type="primary">{{ row.roleName }}</el-tag>
    </template>
  </crud-table>
</template>

<script setup lang="ts">
import { ref } from 'vue';

// 1. API 地址
const apiUrls = {
  query: '/api/user/list',
  detail: '/api/user/detail',
  create: '/api/user/create',
  update: '/api/user/update',
  delete: '/api/user/delete',
};

// 2. 表格列配置
const tableColumns = ref([
  { prop: 'username', label: '用户名' },
  { prop: 'role', label: '角色', slot: 'role' }, // ✨ 指定使用名为 'role' 的插槽
  { prop: 'status', label: '状态', slot: 'status' }, // ✨ 指定使用名为 'status' 的插槽
  { prop: 'createTime', label: '创建时间' },
]);

// 3. 弹窗表单配置 (使用 DynamicForm)
const formConfig = ref([
  { type: 'input', prop: 'username', label: '用户名' },
  { type: 'input', prop: 'nickname', label: '昵称' },
  { type: 'input', prop: 'email', label: '邮箱' },
  {
    type: 'select',
    prop: 'role',
    label: '角色',
    options: [
      { label: '管理员', value: 'admin' },
      { label: '普通用户', value: 'user' },
    ],
  },
  { type: 'textarea', prop: 'description', label: '备注' },
]);

// 4. 弹窗表单校验规则
const formRules = ref({
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
  role: [{ required: true, message: '请选择角色', trigger: 'change' }],
});
</script>

生命周期函数使用

<template>
  <crud-table
    ...省略了基础配置（api-url与表头、表单内容等）
    :initial-search-form="{ dateRange: [] }"
    :on-before-query="handleBeforeQuery"
    :on-after-query="handleAfterQuery"
    :on-before-submit="handleBeforeSubmit"
    :on-before-delete="handleBeforeDelete"
  >
    <template #query-conditions="{ searchForm }">
      <el-form-item label="创建日期">
        <el-date-picker
          v-model="searchForm.dateRange"
          type="daterange"
          range-separator="至"
          start-placeholder="开始日期"
          end-placeholder="结束日期"
          value-format="YYYY-MM-DD"
        />
      </el-form-item>
    </template>
  </crud-table>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const roleMap = { 1: '管理员', 2: '普通用户', 3: '访客' };
const currentUser = { name: 'admin_user' }; // 假设这是当前登录用户

// 1. 查询前：转换日期参数
const handleBeforeQuery = (params) => {
  const newParams = { ...params };
  if (newParams.dateRange && newParams.dateRange.length === 2) {
    newParams.beginTime = newParams.dateRange[0] + ' 00:00:00';
    newParams.endTime = newParams.dateRange[1] + ' 23:59:59';
  }
  delete newParams.dateRange; // 删除原始数组
  return newParams;
};

// 2. 查询后：处理表格数据
const handleAfterQuery = (tableData, queryParams) => {
  console.log('本次查询的参数是：', queryParams);
  // 映射角色 ID 为角色名称
  return tableData.map(item => ({
    ...item,
    roleName: roleMap[item.roleId] || '未知角色',
  }));
};

// 3. 提交前：附加额外数据
const handleBeforeSubmit = (formData, mode) => {
  if (mode === 'add') {
    formData.createBy = currentUser.name;
  } else {
    formData.updateBy = currentUser.name;
  }
  // 必须返回处理后的 formData
  return formData;
};

// 4. 删除前：进行业务校验
const handleBeforeDelete = async (ids, rows) => {
  // rows 是即将被删除的完整行数据对象
  const hasAdmin = rows.some(row => row.roleName === '管理员');
  if (hasAdmin) {
    ElMessage.error('不能删除“管理员”角色的用户！');
    return false; // 返回 false 中止删除
  }
  
  // 可以返回一个 Promise
  // return ElMessageBox.confirm('确定要删除吗？');
  
  return true; // 返回 true 继续执行
};
</script>

自定义“操作列”

<template>
  <crud-table
      ...省略了基础配置（api-url与表头、表单内容等）
  >
    <template #action-before-edit="{ row }">
      <el-button size="small" type="primary" link @click="viewDetails(row)">
        详情
      </el-button>
    </template>
    
    <template #action-after-delete="{ row }">
      <el-button size="small" type="warning" link @click="resetPassword(row)">
        重置密码
      </el-button>
    </template>
    
    </crud-table>
</template>

<script setup lang="ts">
// ...
const viewDetails = (row) => { console.log('查看详情', row.id); };
const resetPassword = (row) => { console.log('重置密码', row.id); };
// const handleApprove = (row) => { ... };
// const handleReject = (row) => { ... };
</script>

复杂表单

<template>
  <crud-table
    ...省略了基础配置（api-url与表头、表单内容等）
    :dialog-form-rules="formRules"
  >
    <template #dialog-form="{ formData, formRef }">
      <el-form :ref="formRef" :model="formData" :rules="formRules" label-width="100px">
        <el-form-item label="用户名" prop="username">
          <el-input v-model="formData.username" />
        </el-form-item>
        <el-form-item label="昵称" prop="nickname">
          <el-input v-model="formData.nickname" />
        </el-form-item>
        <el-form-item label="用户类型" prop="userType">
          <el-select v-model="formData.userType" @change="onUserTypeChange(formData)">
            <el-option label="普通用户" value="normal" />
            <el-option label="VIP 用户" value="vip" />
          </el-select>
        </el-form-item>
        
        <el-form-item v-if="formData.userType === 'vip'" label="VIP 等级" prop="vipLevel">
          <el-input-number v-model="formData.vipLevel" :min="1" />
        </el-form-item>
      </el-form>
    </template>
  </crud-table>
</template>

<script setup lang="ts">
import { ref } from 'vue';

// 校验规则
const formRules = ref({
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
  userType: [{ required: true, message: '请选择用户类型', trigger: 'change' }],
});

// 表单内部联动逻辑
const onUserTypeChange = (formData) => {
  if (formData.userType !== 'vip') {
    formData.vipLevel = undefined; // 清空联动字段
  }
};
</script>

文件上传表单

<template>
  <crud-table
      ...省略了基础配置（api-url与表头内容等）
    :dialog-form-rules="formRules"
    :submit-as-form-data="true"
  >
    <template #dialog-form="{ formData, formRef }">
      <el-form :ref="formRef" :model="formData" :rules="formRules" label-width="100px">
        <el-form-item label="用户名" prop="username">
          <el-input v-model="formData.username" />
        </el-form-item>
        
        <el-form-item label="用户头像" prop="avatarFile">
          <el-upload
            action="#"
            :auto-upload="false"
            :limit="1"
            :on-change="handleAvatarChange"
          >
            <el-button type="primary">选择文件</el-button>
          </el-upload>
        </el-form-item>
      </el-form>
    </template>
  </crud-table>
</template>

<script setup lang="ts">
import { ref } from 'vue';

// ...
const formRules = ref({
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
  avatarFile: [{ required: true, message: '请上传头像', trigger: 'change' }],
});

// 在 handleBeforeSubmit 钩子中处理文件
const handleBeforeSubmit = (formData, mode) => {
  // `submit` 函数会自动将 `formData` 转换为 FormData 对象
  // 我们只需要确保 `avatarFile` 字段是原始的 File 对象
  console.log('提交前的表单数据：', formData);
  return formData;
};

// el-upload 的 change 事件
const handleAvatarChange = (file, fileList) => {
  // 上传逻辑
};
</script>

属性

API 与数据配置

UI 功能开关

弹窗与表单配置

分页配置

样式与加载

生命周期钩子 (Hooks)

Events (自定义事件)

Exposed Methods (暴露方法)

搜索区插槽

操作区插槽

表格区插槽

Column (用于 columns Prop)

FormItem (用于 dialogFormConfig Prop)