vben admin 5的useVbenVxeGrid钩子详解

1.用于创建和管理基于 vxe-table 的表格组件。它返回一个数组，包含两个元素：表格组件和表格 API

2.基本用法

const [BasicTable, tableApi] = useVbenVxeGrid({
  formOptions,
  gridOptions,
  gridEvents,
});
 
3.参数详解
1.formOptions ------表单配置选项
formOptions 是用于表格上方的搜索表单，他的类型是VbenFormProps
 
const formOptions: VbenFormProps = {
  commonConfig: {
    labelWidth: 80,
    componentProps: {
      allowClear: true,
    },
  },
  schema: querySchema(), // 表单字段定义
  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4',
};
关键属性
commonConfig: 表单通用配置，如标签宽度、组件通用属性等
schema: 表单字段定义数组，描述每个表单控件
wrapperClass: 表单布局类，使用 Tailwind CSS 类控制响应式布局
 
2.gridOptions - 表格配置选项
gridOptions 是 vxe-table 的核心配置，用于定义表格的各种行为和外观
 
const gridOptions: VxeGridProps = {
  checkboxConfig: {
    highlight: true,     // 高亮选中行
    reserve: true,       // 翻页时保留选中状态
  },
  columns,               // 列配置
  height: 'auto',        // 表格高度
  keepSource: true,      // 保持数据源
  pagerConfig: {},       // 分页配置
  proxyConfig: {         // 代理配置（用于数据加载）
    ajax: {
      query: async ({ page }, formValues = {}) => {
        // 数据查询逻辑
        return await dataList({
          pageNum: page.currentPage,
          pageSize: page.pageSize,
          ...formValues,
        });
      },
    },
  },
  rowConfig: {
    isHover: true,       // 鼠标悬停效果
    keyField: 'id',      // 主键字段
  },
  id: 'unique-table-id', // 表格唯一标识，用于保存列配置
};
 
关键属性：
  • checkboxConfig/radioConfig: 复选框/单选框配置
  • columns: 表格列定义
  • height: 表格高度
  • pagerConfig: 分页配置
  • proxyConfig: 数据代理配置，用于处理数据加载、保存等操作
  • rowConfig: 行配置
  • id: 表格唯一标识，用于保存用户自定义的列配置

3. gridEvents - 表格事件处理

gridEvents 用于处理表格的各种事件，如点击、选中等。

 

const [BasicTable, tableApi] = useVbenVxeGrid({
  formOptions,
  gridOptions,
  gridEvents: {
    checkboxChange: tableCheckboxEvent(checked),
    checkboxAll: tableCheckboxEvent(checked),
    cellClick: (e) => {
      // 处理单元格点击事件
    }
  },
});

常见事件：

1.checkboxChange: 复选框状态改变事件

2.checkboxAll: 全选状态改变事件

3.cellClick: 单元格点击事件

4.cellDblclick: 单元格双击事件

5.sortChange: 排序改变事件

 

返回值详解

1. BasicTable - 表格组件

 返回的表格组件可以直接在模板中使用：
 
<template>
  <BasicTable>
    <!-- 工具栏操作按钮 -->
    <template #toolbar-actions>
      <span class="pl-[7px] text-[16px]">标题</span>
    </template>
   
    <!-- 工具栏工具按钮 -->
    <template #toolbar-tools>
      <Space>
        <w-button>导出</w-button>
        <w-button>删除</w-button>
        <w-button>新增</w-button>
      </Space>
    </template>
   
    <!-- 自定义列 -->
    <template #action="{ row }">
      <Space>
        <ghost-button @click.stop="handleEdit(row)">编辑</ghost-button>
        <ghost-button @click.stop="handleDelete(row)">删除</ghost-button>
      </Space>
    </template>
  </BasicTable>
</template>
 

2. tableApi - 表格操作 API

tableApi 提供了操作表格的方法：

// 查询数据（会触发 proxyConfig.ajax.query）
await tableApi.query();

// 重新加载数据
await tableApi.reload();

// 设置表格选项
tableApi.setGridOptions(options);

// 设置加载状态
tableApi.setLoading(true);

// 获取选中的记录
const records = tableApi.grid.getCheckboxRecords();

// 获取表单值
const formValues = tableApi.formApi.getValues();
 

实际应用示例

// 定义表单配置
const formOptions: VbenFormProps = {
  commonConfig: {
    labelWidth: 80,
    componentProps: {
      allowClear: true,
    },
  },
  schema: [
    {
      field: 'name',
      label: '姓名',
      component: 'Input',
    },
    {
      field: 'status',
      label: '状态',
      component: 'Select',
      componentProps: {
        options: [
          { label: '启用', value: '1' },
          { label: '禁用', value: '0' },
        ],
      },
    },
  ],
  wrapperClass: 'grid-cols-1 md:grid-cols-2',
};

// 定义表格配置
const gridOptions: VxeGridProps = {
  checkboxConfig: {
    highlight: true,
    reserve: true,
  },
  columns: [
    { field: 'id', title: 'ID' },
    { field: 'name', title: '姓名' },
    { field: 'status', title: '状态' },
    { field: 'createTime', title: '创建时间' },
    {
      field: 'action',
      title: '操作',
      slots: { default: 'action' },
      fixed: 'right',
      width: 160,
    },
  ],
  height: 'auto',
  keepSource: true,
  pagerConfig: {},
  proxyConfig: {
    ajax: {
      query: async ({ page }, formValues = {}) => {
        return await getUserList({
          pageNum: page.currentPage,
          pageSize: page.pageSize,
          ...formValues,
        });
      },
    },
  },
  rowConfig: {
    isHover: true,
    keyField: 'id',
  },
  id: 'user-table',
};

// 使用 useVbenVxeGrid
const [BasicTable, tableApi] = useVbenVxeGrid({
  formOptions,
  gridOptions,
  gridEvents: {
    checkboxChange: tableCheckboxEvent(checked),
    checkboxAll: tableCheckboxEvent(checked),
  },
});
 
 
 
 
 
 
 
 
 
 
 
 
 
 
posted @ 2025-08-26 15:42  小猴子会上树  阅读(842)  评论(0)    收藏  举报