useGrid

useGrid 聚合 ElForm、ElTable 和 ElPagination，通过一个 Controller 管理查询条件、表格数据和分页状态。调用方负责请求数据，并通过 setData 或 loadData 更新表格。异步加载数据时，会自动处理 Loading。

基础用法

columns 用于设置表格列，data 用于设置初始数据。传入 pagination 后会显示分页器。分页变化只会更新内部状态并触发事件，调用方需在事件中使用 loadData 加载数据。

传入 form 配置即可显示查询表单。调用加载函数时，loadData 会传入表单模型和分页参数。loadData 执行异步加载函数时会显示 Loading，函数结束后会关闭 Loading。

表单插槽会接收 loading 参数，调用方可以使用该参数控制自定义按钮。加载状态不会遮挡表单区域。

vue

<script setup lang="ts">
  import { useGrid } from 'element-hooks';
  import { ElInput, ElSelect } from 'element-plus';

  type Row = {
    address: string;
    date: string;
    name: string;
    region: string;
  };

  type SearchModel = {
    region: string;
    user: string;
  };

  const sourceData: Row[] = [
    {
      date: '2016-05-03',
      name: 'Tom',
      region: 'shanghai',
      address: 'No. 189, Grove St, Los Angeles',
    },
    {
      date: '2016-05-02',
      name: 'Jack',
      region: 'beijing',
      address: 'No. 189, Grove St, Los Angeles',
    },
    {
      date: '2016-05-04',
      name: 'Tom',
      region: 'beijing',
      address: 'No. 189, Grove St, Los Angeles',
    },
    {
      date: '2016-05-01',
      name: 'Alice',
      region: 'shanghai',
      address: 'No. 189, Grove St, Los Angeles',
    },
  ];

  async function handleSearch() {
    await loadData(async params => {
      await new Promise(resolve => setTimeout(resolve, 500));

      const { currentPage, pageSize, region, user } = params;
      const filtered = sourceData.filter(row => {
        return (
          (!user || row.name.includes(user)) &&
          (!region || row.region === region)
        );
      });
      const start = (currentPage - 1) * pageSize;

      return {
        result: filtered.slice(start, start + pageSize),
        total: filtered.length,
      };
    });
  }

  function handleReset() {
    instance.value?.form?.resetFields();
    return handleSearch();
  }

  const [Grid, { instance, loadData }] = useGrid<Row, SearchModel>({
    form: {
      model: { user: '', region: '' },
      inline: true,
      items: [
        {
          label: 'Approved by',
          prop: 'user',
          render: {
            component: ElInput,
            props: {
              placeholder: 'Approved by',
              style: '--el-input-width: 190px',
            },
          },
        },
        {
          label: 'Activity zone',
          prop: 'region',
          render: {
            component: ElSelect,
            props: {
              placeholder: 'Activity zone',
              options: [
                { label: 'Zone one', value: 'shanghai' },
                { label: 'Zone two', value: 'beijing' },
              ],
              style: '--el-select-width: 190px',
            },
          },
        },
        {
          slot: 'operations',
        },
      ],
    },
    data: {
      result: sourceData.slice(0, 2),
      total: sourceData.length,
    },
    columns: [
      { prop: 'date', label: 'Date', width: '180' },
      { prop: 'name', label: 'Name', width: '180' },
      { prop: 'address', label: 'Address' },
    ],
    pagination: {
      currentPage: 1,
      pageSize: 2,
      layout: 'prev, pager, next',
      onCurrentChange: handleSearch,
      onSizeChange: handleSearch,
    },
  });
</script>

<template>
  <Grid>
    <template #operations="{ loading }">
      <el-button
        type="primary"
        :loading="loading"
        :disabled="loading"
        @click="handleSearch"
      >
        Query
      </el-button>
      <el-button :disabled="loading" @click="handleReset">Reset</el-button>
    </template>
  </Grid>
</template>

自定义数据映射

Grid 会根据数据自动设置总条数。数据为数组时使用数组长度，数据为对象时默认读取 result 和 total 字段。pagination.props 可以将其他响应字段映射为这两个字段。

暂无数据

数据更新

setData 直接写入数据，也支持函数式更新。loadData 调用同步或异步加载函数，并将返回值写入数据。

setData(rows);

setData(data => (Array.isArray(data) ? [...data, row] : [row]));

loadData(params => getRows(params));

await loadData(async params => {
  const response = await getRows(params);
  return response;
});

每次调用 loadData 时，传入的加载函数只会执行一次。分页变化不会自动重新执行之前的加载函数。传入 form 时，加载函数的参数包含表单模型和分页参数，未传入 form 时，参数只包含 currentPage 和 pageSize。有表单且需要显式声明行类型时，应同时声明 D 和 M。不写泛型时，D 和 M 会分别从 data 和 form.model 推导。分页字段会覆盖表单中的同名字段。currentPage 和 pageSize 未配置时采用 ElPagination 的默认值。

GridData<D> 也可以接收对象形式的响应。响应对象可以使用 interface 或 type 定义，无需声明字符串索引签名。

需要串行加载时，调用方应逐次 await loadData(...)。

[加载范围]

加载函数返回 PromiseLike（包括 Promise）时，页面才会显示加载状态。加载状态仅覆盖表格区域，并在加载期间禁用分页，函数结束后会自动关闭。错误会继续向调用方抛出。useGrid 不负责消息提示或重试。

API

Options

useGrid 支持 ElTable 的属性，并增加以下配置。

GridOptions<D> 不包含表单配置。使用表单时应声明为 GridOptions<D, M>，此时 form 为必填项。未提供具体行类型时，D 默认使用 object，传入空数组不会将行类型固定为 never。

参数	说明	类型	默认值
`data`	表格数据，可以是数组或包含结果及总数的对象	`GridData<D>`	-
`columns`	表格列配置	`TableColumn<D>[]`	`[]`
`form`	表单配置，参考 `useForm`	`FormOptions<M>`	-
`pagination`	分页配置，参考 `ElPagination`	`PaginationOptions`	-

PaginationOptions 不包含 total、pageCount、defaultCurrentPage 和 defaultPageSize。Grid 根据数据管理总条数，ElPagination 会结合 pageSize 计算总页数。初始页码和每页条数可以通过 currentPage、pageSize 设置。

可以通过 app.use(ElementHooks, { pagination }) 设置全局分页默认项。

TIP

传入 pagination 时，局部分页配置会与全局 pagination 配置合并。

Controller

成员	说明	类型
`setState`	更新 `Grid` 的整体状态	`(state: GridOptions<D, M> \| ((prev: GridOptions<D, M>) => GridOptions<D, M>)) => void`
`setData`	更新表格数据	`(data: GridData<D> \| ((prev: GridData<D>) => GridData<D>)) => void`
`loadData`	执行一次同步或异步数据加载	`(loader: GridDataLoader<D, M>) => void \| Promise<void>`
`setModel`	更新或初始化表单模型数据	`(model: M \| ((prev: M) => M)) => void`
`getModel`	获取当前表单数据	`() => M \| null`
`setItems`	更新表单项配置	`(items: FormItem<M>[] \| ((prev: FormItem<M>[]) => FormItem<M>[])) => void`
`setColumns`	更新表格列配置	`(columns: TableColumn<D>[] \| ((prev: TableColumn<D>[]) => TableColumn<D>[])) => void`
`getData`	获取当前表格渲染的数据	`() => D[]`
`getPagination`	获取当前页码和每页条数	`() => GridPaginationParams`
`instance`	表单、表格和分页实例	`Ref<GridInstance \| null>`

模型尚未初始化时，setModel 只能直接传入模型对象。

useGrid ​

基础用法 ​

查询表单 ​

自定义数据映射 ​

数据更新 ​

API ​

Options ​

Controller ​