开发预览更新于 2026-05-10

DataGrid 数据网格

重型表格 — 列拖拽调宽、单元格双击编辑、固定表头滚动；适合后台管理与数据维护。

基础用法

CfDataGrid 在 Table 的列定义之上额外支持列拖宽 / 单元格编辑 / sticky 表头。最简形态 — 配置 columns + rows + rowKey，与 Table 一致。

ID	姓名	角色	等级
1	Alice Chen	前端	3
2	Bob Wang	后端	2
3	Carol Liu	设计	5
4	Dave Zhang	运维	1

<script setup lang="ts">
import { ref } from 'vue';
import { CfDataGrid, type DataGridColumn } from '@chufix-design/vue';

interface Row { id: string; name: string; role: string; level: number; }

const rows = ref<Row[]>([
{ id: '1', name: 'Alice Chen', role: '前端', level: 3 },
// ...
]);
const columns: DataGridColumn<Row>[] = [
{ key: 'id', title: 'ID', width: 60, sortable: true },
{ key: 'name', title: '姓名', width: 140, sortable: true },
{ key: 'role', title: '角色', width: 100 },
{ key: 'level', title: '等级', width: 80, align: 'right', sortable: true },
];
</script>

<template>
<CfDataGrid :columns="columns" :rows="rows" row-key="id" />
</template>

import { CfDataGrid, type DataGridColumn } from '@chufix-design/react';

interface Row { id: string; name: string; role: string; level: number; }
const columns: DataGridColumn<Row>[] = [
{ key: 'id', title: 'ID', width: 60, sortable: true },
{ key: 'name', title: '姓名', width: 140, sortable: true },
{ key: 'role', title: '角色', width: 100 },
{ key: 'level', title: '等级', width: 80, align: 'right', sortable: true },
];

<CfDataGrid columns={columns} rows={rows} rowKey="id" />

列宽拖拽

给列加 resizable: true 让用户拖拽该列右边缘改变宽度。minWidth 限制拖拽下限避免列被拖到看不见。每次松手会触发 columnResize(col, width) 事件，可用来持久化用户的列宽偏好。

ID	姓名	邮箱	角色
1	Alice Chen	[email protected]	前端
2	Bob Wang	[email protected]	后端
3	Carol Liu	[email protected]	设计

把鼠标放到列头右边缘，光标变成 ↔ 即可拖拽。

const columns: DataGridColumn<Row>[] = [
{ key: 'id', title: 'ID', width: 60 },
{ key: 'name', title: '姓名', width: 140, resizable: true, minWidth: 80 },
{ key: 'email', title: '邮箱', width: 220, resizable: true, minWidth: 120 },
{ key: 'role', title: '角色', width: 100, resizable: true },
];

<CfDataGrid :columns="columns" :rows="rows" row-key="id" />

const columns: DataGridColumn<Row>[] = [
{ key: 'id', title: 'ID', width: 60 },
{ key: 'name', title: '姓名', width: 140, resizable: true, minWidth: 80 },
{ key: 'email', title: '邮箱', width: 220, resizable: true, minWidth: 120 },
{ key: 'role', title: '角色', width: 100, resizable: true },
];

<CfDataGrid columns={columns} rows={rows} rowKey="id" />

单元格编辑

给列加 editable: true 启用双击进入内联编辑模式。Enter 提交并触发 cellEdit(edit)；Esc 取消。回调里拿到 { row, column, value }，把变化写回数据源。

ID	姓名	角色	等级
1	Alice Chen	前端	3
2	Bob Wang	后端	2
3	Carol Liu	设计	5

双击任意单元格进入编辑，Enter 提交，Esc 取消。

function onEdit(edit: DataGridCellEdit<Row>) {
const target = rows.value.find((r) => r.id === edit.row.id);
if (!target) return;
const key = edit.column.dataIndex ?? edit.column.key;
(target as any)[key] = key === 'level' ? Number(edit.value) : edit.value;
}

<CfDataGrid :columns="columns" :rows="rows" row-key="id" @cell-edit="onEdit" />

function onEdit(edit: DataGridCellEdit<Row>) {
setRows((arr) =>
  arr.map((r) =>
    r.id === edit.row.id
      ? { ...r, [edit.column.dataIndex ?? edit.column.key]: edit.value }
      : r,
  ),
);
}

<CfDataGrid columns={columns} rows={rows} rowKey="id" onCellEdit={onEdit} />

高度限制 + sticky 表头

传 maxHeight 启用纵向滚动 — 表头通过 sticky 固定在容器顶部。配合 selectable="multiple" 做大数据量浏览页很合适。

ID	项目	状态
1	项目 001	进行中
2	项目 002	已完成
3	项目 003	待审核
4	项目 004	进行中
5	项目 005	已完成
6	项目 006	待审核
7	项目 007	进行中
8	项目 008	已完成
9	项目 009	待审核
10	项目 010	进行中
11	项目 011	已完成
12	项目 012	待审核
13	项目 013	进行中
14	项目 014	已完成
15	项目 015	待审核
16	项目 016	进行中
17	项目 017	已完成
18	项目 018	待审核
19	项目 019	进行中
20	项目 020	已完成
21	项目 021	待审核
22	项目 022	进行中
23	项目 023	已完成
24	项目 024	待审核
25	项目 025	进行中
26	项目 026	已完成
27	项目 027	待审核
28	项目 028	进行中
29	项目 029	已完成
30	项目 030	待审核

<CfDataGrid
:columns="columns"
:rows="rows"
row-key="id"
:max-height="280"
selectable="multiple"
/>

<CfDataGrid
columns={columns}
rows={rows}
rowKey="id"
maxHeight={280}
selectable="multiple"
/>

API · DataGrid

继承 Table 的所有列基础属性（title / width / align / sortable / dataIndex 等），额外加：

属性	类型	默认值	说明
`maxHeight`	`number \| string`	`—`	容器最大高度，启用 sticky thead + 纵向滚动
`onCellEdit` (React) / `cell-edit` (Vue)	`(edit) => void`	`—`	单元格编辑提交回调
`onColumnResize` / `column-resize`	`(col, width) => void`	`—`	列宽变化回调

DataGridColumn 在 TableColumn 上加：

属性	类型	说明
`resizable`	`boolean`	是否允许拖拽改宽
`minWidth`	`number`	拖拽最小宽度
`editable`	`boolean`	是否允许双击进入内联编辑

当前版本不内置虚拟滚动 / 列拖动（顺序）。如果数据量超过 1000 行，建议自行实现分页或上层数据切片，再把切片传入 rows。