Vxe 数据表格组件
Vxe 数据表格组件是一个基于 vxe-table 的 Vue 数据表格组件，支持灵活的列配置、多种数据来源、分页、排序、筛选、可编辑单元格等专业级表格能力。组件提供丰富的配置选项和事件支持，可以轻松集成到表单设计器中，实现复杂的数据管理和展示场景。
安装与挂载
Vxe 数据表格依赖 vxe-table 组件，设计器打包时不会将其打包进去，需要您在自己的项目中安装并在 Vue 中全局挂载。
安装依赖
Vue 3 项目：
bash
npm install vxe-table@4.17.48 vxe-pc-ui@4.12.31Vue 2 项目：
bash
npm install vxe-table@3.19.49 vxe-pc-ui@3.12.31全局挂载
Vue 3：
js
import VxeUIBase from 'vxe-pc-ui';
import 'vxe-pc-ui/es/style.css';
import { VxeGrid, VxeUI } from 'vxe-table';
import 'vxe-table/es/style.css';
// 行内编辑的下拉、日期等浮层若被弹窗遮挡，可提高全局 zIndex
VxeUI.setConfig({
zIndex: 4000,
});
app.use(VxeUIBase);
app.use(VxeGrid);Vue 2：
js
import VxeUIBase from 'vxe-pc-ui';
import 'vxe-pc-ui/es/style.css';
import { VxeGrid, VxeUI } from 'vxe-table';
import 'vxe-table/es/style.css';
VxeUI.setConfig({
zIndex: 4000,
});
Vue.use(VxeUIBase);
Vue.use(VxeGrid);更多安装方式、按需引入等说明请参阅 vxe-table 官方安装文档。
基础使用
获取表格数据
通过注入的 api.el 方法可以获取数据表格组件实例，访问表格数据：
js
function onChange($inject) {
const dataTableInstance = $inject.api.el('ref_F2vulxvqc841dac');
const list = dataTableInstance.list;
const total = dataTableInstance.total;
const currentPage = dataTableInstance.currentPage;
console.log('当前表格数据:', list);
}获取表格实例与选中行
通过 getEl 方法可以获取底层 VxeGrid 实例，进行更高级的操作。选中行的获取需根据 selection 类型调用对应方法：
js
function getSelectedRows($inject) {
const dataTableInstance = $inject.api.el('ref_F2vulxvqc841dac');
const tableEl = dataTableInstance.getEl();
if (!tableEl || !dataTableInstance.selection) return;
if (dataTableInstance.selection === 'checkbox') {
const selectedRows = tableEl.getCheckboxRecords();
console.log('多选中的行:', selectedRows);
} else if (dataTableInstance.selection === 'radio') {
const selectedRow = tableEl.getRadioRecord();
console.log('单选中的行:', selectedRow);
}
}刷新表格数据
使用 initPage 方法可以重新初始化表格并刷新数据：
js
function refreshTable($inject) {
const dataTableInstance = $inject.api.el('ref_F2vulxvqc841dac');
dataTableInstance.initPage();
}修改列配置
通过 api.getRule 方法可以动态修改表格列配置：
js
function onChange($inject) {
const rule = $inject.api.getRule('ref_F2vulxvqc841dac');
rule.props.column = [
{ prop: 'name', label: '姓名', width: 120, format: 'default' },
{ prop: 'age', label: '年龄', width: 80, format: 'default' },
];
}配置项
Vxe 数据表格提供了丰富的配置选项，您可以通过在设计器中配置属性来自定义表格的行为和外观。
表格属性
| 属性名 | 类型 | 默认值 | 必需 | 说明 |
|---|---|---|---|---|
| column | Array | [] | 是 | 表格列配置，包括字段、标题、宽度、对齐方式、排序、可编辑、合计等 |
| data | Array | [] | 否 | 静态数据，当不使用 fetch 或 globalDataKey 时使用 |
| globalDataKey | String, Object | - | 否 | 全局数据键名，使用预定义的全局数据源 |
| fetch | Object | - | 否 | 远程数据获取配置，支持 POST/GET 请求 |
| page | Object | - | 否 | 分页配置，包含 open、position、pageSizes、totalField、dataField 等 |
| button | Object | - | 否 | 操作列配置，包含 open、column、label、fixed、width |
| index | Boolean | - | 否 | 是否显示序号列 |
| selection | Boolean, String | - | 否 | 是否显示选择列，可选 checkbox、radio |
| showHeader | Boolean | true | 否 | 是否显示表头 |
| headerAlign | String | - | 否 | 表头对齐方式，可选 left、center、right |
| align | String | - | 否 | 单元格对齐方式，可选 left、center、right |
| showFooter | Boolean | false | 否 | 是否显示表尾；任一一列开启合计时会自动显示表尾 |
| footerData | Array | - | 否 | 自定义表尾数据；开启列合计后由组件自动生成合计行，该配置不再生效 |
| mergeCells | Array | - | 否 | 合并单元格配置 |
| showOverflow | Boolean, String | - | 否 | 单元格内容溢出时显示方式，可选 title、ellipsis、tooltip |
| showHeaderOverflow | Boolean, String | - | 否 | 表头内容溢出时显示方式 |
| showFooterOverflow | Boolean, String | - | 否 | 表尾内容溢出时显示方式 |
| allowCurrent | Boolean, String | - | 否 | 是否高亮当前行/列，可选 col、row |
| treeNode | Boolean | false | 否 | 是否启用树形结构 |
| rowDrag | Boolean | false | 否 | 是否开启行拖拽排序 |
| columnDrag | Boolean | false | 否 | 是否开启列拖拽排序 |
| autoInit | Boolean | true | 否 | 是否自动初始化加载数据 |
分页配置 (page)
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| open | Boolean | - | 是否开启分页 |
| position | String | 'right' | 分页组件位置，可选 left、center、right |
| pageField | String | 'page' | 请求参数字段名（页码） |
| pageSizeField | String | 'limit' | 请求参数字段名（每页条数） |
| orderField | String | 'order' | 排序字段参数字段名 |
| orderByField | String | 'orderBy' | 排序方式参数字段名 |
| totalField | String | 'count' | 响应数据中总数的字段路径 |
| dataField | String | 'list' | 响应数据中列表的字段路径 |
| pageSizes | String, Array | '10, 20, 50, 100' | 每页条数选项 |
| props | Object | - | 传递给 el-pagination 的额外属性 |
列配置 (column)
每列支持以下配置：
| 属性名 | 类型 | 说明 |
|---|---|---|
| prop | String | 列绑定的字段名 |
| label | String | 列标题（必填） |
| width | Number, String | 列宽度 |
| minWidth | Number, String | 列最小宽度 |
| align | String | 列对齐方式 |
| headerAlign | String | 表头对齐方式 |
| fixed | String | 固定列，可选 left、right |
| sortable | Boolean, String | 是否可排序，custom 表示服务端排序 |
| resizable | Boolean | 是否可调整列宽 |
| hidden | Boolean | 是否隐藏列 |
| className | String | 列单元格的 class 名 |
| titlePrefix | String, Object | 列标题前缀 |
| format | String | 单元格渲染格式，可选 default、tag、image、custom |
| render | Function | 当 format 为 custom 时的自定义渲染函数 |
| editRender | String | 可编辑渲染器，可选 input、textarea、number、select、date、datetime、time |
| editRenderOptions | Array | 当 editRender 为 select 时的选项，格式 [{label, value}] |
| summary | Boolean | 是否对该列求和并显示在表尾行；仅叶子列生效，需同时配置 prop |
| filter | Array | 列筛选值数组，用于前端过滤 |
| children | Array | 子列配置，用于多级表头 |
操作按钮配置 (button)
| 属性名 | 类型 | 说明 |
|---|---|---|
| open | Boolean | 是否显示操作列 |
| label | String | 操作列标题 |
| fixed | String | 固定位置，left、right |
| width | Number, String | 操作列宽度 |
| column | Array | 按钮配置列表 |
按钮项配置：
| 属性名 | 类型 | 说明 |
|---|---|---|
| name | String | 按钮文本 |
| key | String | 按钮唯一标识 |
| type | String | 按钮类型，如 primary、danger |
| size | String | 按钮尺寸 |
| prop | Array | 按钮属性，如 ['round']、['plain']、['disabled'] |
| click | String | 点击时执行的函数，参数 (scope, api) |
| handle | String | 返回按钮 props 的函数，可动态控制 disabled |
| hide | String | 返回布尔值的函数，控制按钮显隐 |
| hidden | Boolean | 是否隐藏 |
事件
Vxe 数据表格提供了事件，方便您监听表格状态变化并执行相应的处理。
| 事件名 | 说明 |
|---|---|
| ready | 表格就绪事件，渲染完成后触发 |
| handleClick | 操作按钮点击事件，参数 {name, key, scope, column} |
| radioChange | 单选变化事件，单选列选中/取消时触发 |
| checkboxChange | 多选变化事件，多选列选中/取消时触发 |
| checkboxAll | 全选/取消全选事件 |
| cellClick | 单元格点击事件 |
| headerCellClick | 表头单元格点击事件 |
| footerCellClick | 表尾单元格点击事件 |
| sortChange | 排序变化事件，点击列标题排序时触发 |
| clearSort | 清除排序事件 |
| editActivated | 单元格编辑激活事件 |
| editClosed | 单元格编辑关闭事件 |
| currentRowChange | 当前行变化事件 |
| currentChange | 页码变化事件 |
| currentColumnChange | 当前列变化事件 |
| pageSizeChange | 每页条数变化事件 |
| rowDragstart | 行拖拽开始事件 |
| rowDragend | 行拖拽结束事件 |
| columnDragstart | 列拖拽开始事件 |
| columnDragend | 列拖拽结束事件 |
事件使用示例
监听操作按钮点击：
js
function handleClick({ name, key, scope, column }) {
console.log('按钮名称:', name);
console.log('当前行数据:', scope.row);
if (name === '编辑') {
// 编辑逻辑
} else if (name === '删除') {
// 删除逻辑
}
}监听页码变化：
js
function handleCurrentChange(pageNum) {
console.log('切换到的页码:', pageNum);
}方法
Vxe 数据表格提供了方法，方便您进行程序化控制。
| 方法名 | 参数 | 说明 | 返回值 |
|---|---|---|---|
| getEl | - | 获取底层 VxeGrid 实例 | VxeGrid |
| initPage | - | 重新初始化并刷新数据 | - |
| changePage | n | 切换到指定页码 | - |
| changePageSize | size | 切换每页条数 | - |
| getLimit | - | 获取当前每页条数 | Number |
方法使用示例
切换页码：
js
function goToPage($inject, pageNum) {
const dataTableInstance = $inject.api.el('ref_F2vulxvqc841dac');
dataTableInstance.changePage(pageNum);
}切换每页条数：
js
function changePageSize($inject, size) {
const dataTableInstance = $inject.api.el('ref_F2vulxvqc841dac');
dataTableInstance.changePageSize(size);
}VxeGrid 实例方法
getEl() 返回 vxe-table 的 VxeGrid 实例，可直接调用 vxe-table 提供的 API：
| 方法名 | 说明 | 适用场景 |
|---|---|---|
| getCheckboxRecords() | 获取多选选中的行数据数组 | selection 为 checkbox |
| getRadioRecord() | 获取单选选中的行数据 | selection 为 radio |
| getCurrentRecord() | 获取当前聚焦的行数据 | 通用 |
| clearCheckboxRow() | 清空多选选中状态 | - |
| clearRadioRow() | 清空单选选中状态 | - |
更多 API 请参考 vxe-table 官方文档。
单元格格式
列支持多种单元格渲染格式：
| 格式值 | 说明 |
|---|---|
| default | 默认文本显示 |
| tag | 使用 el-tag 组件渲染 |
| image | 图片列表，支持单图或多图预览 |
| custom | 自定义渲染，需配置 render 函数 |
自定义渲染示例
当 format 为 custom 时，需配置 render 函数：
js
{
prop: 'status',
label: '状态',
format: 'custom',
render: (scope, h, resolveComponent, api) => {
const status = scope.row.status;
return h(resolveComponent('el-tag'), {
type: status === 1 ? 'success' : 'info'
}, () => [status === 1 ? '启用' : '禁用']);
}
}可编辑列
配置 editRender 可启用单元格双击编辑。行内编辑基于 vxe 官方编辑组件渲染，支持以下类型：
| 类型 | 说明 |
|---|---|
| input | 单行文本输入 |
| textarea | 多行文本输入 |
| number | 数字输入 |
| select | 下拉选择，需配置 editRenderOptions，格式 [{label, value}] |
| date | 日期选择 |
| datetime | 日期时间选择 |
| time | 时间选择 |
编辑时触发方式为双击单元格。若下拉或日期面板被弹窗遮挡，可在全局挂载时通过 VxeUI.setConfig({ zIndex: 4000 }) 提高浮层层级。
列合计
在列配置中将 summary 设为 true，即可对该列数值自动求和，并在表尾展示合计行。
规则说明：
- 任一叶子列开启合计后，表格会自动显示表尾行，无需再手动打开
showFooter - 开启列合计后，合计行由组件自动计算，
footerData不再生效 - 合计仅对叶子列生效（含多级表头场景下的末级列），且该列需配置
prop - 求和时跳过空值、
null与非数字内容，并对小数做精度累加 - 表尾行展示方式：开启序号列时，序号列显示「合计」；已开启合计的列显示求和结果；其余列显示
-
配置示例：
js
rule.props.column = [
{ prop: 'name', label: '商品名称', width: 160 },
{ prop: 'price', label: '单价', width: 100, summary: true },
{ prop: 'qty', label: '数量', width: 100, summary: true },
{ prop: 'remark', label: '备注', width: 160 },
];内部数据
| 数据名 | 初始值 | 说明 |
|---|---|---|
| total | 0 | 总数据量 |
| loading | false | 加载状态 |
| list | [] | 当前页数据 |
| currentPage | 1 | 当前页码 |
| order | '' | 排序字段 |
| orderBy | '' | 排序方式 |
| currentSize | undefined | 当前每页条数 |
| filterList | Array | 列过滤后的数据列表 |
更多 vxe-table 安装方式、按需引入等说明请参阅 vxe-table 官方安装文档。