BaseTable 表格组件

来源：@jhlc/common-core 远程组件

BaseTable 是一个功能强大的表格组件，支持数据展示、排序、筛选、选择、操作按钮、可编辑单元格等功能。支持 DataTable 和 AGGrid 两种渲染模式。

📦 导入方式

typescript


// 全局注册（已在项目中配置）

// 直接使用 <BaseTable /> 即可



// 类型导入

import type { TableColumnDesc } from "@jhlc/common-core/src/components/table/base-table/type";

🚀 基本用法

vue


<template>

  <BaseTable

    ref="tableRef"

    :data="list"

    :columns="columns"

    showToolbar

    border

  />

</template>



<script setup lang="ts">

import { ref, computed } from "vue";



const tableRef = ref();

const list = ref([

  { id: 1, name: "张三", age: 25, status: "在职" },

  { id: 2, name: "李四", age: 30, status: "离职" }

]);



const columns = computed(() => [

  { type: "selection" },

  { type: "index" },

  { label: "姓名", name: "name" },

  { label: "年龄", name: "age" },

  { label: "状态", name: "status" }

]);

</script>

📋 Props 属性

基础属性

| 属性名 | 类型 | 默认值 | 说明 |

| ----------------------------- | -------------------------------- | ------------------- | -------------------------- |

外观属性

| 属性名 | 类型 | 默认值 | 说明 |

| ----------------------------- | -------------------------------- | ------------------- | -------------------------- |

选择相关

| 属性名 | 类型 | 默认值 | 说明 |

| ----------------------------- | -------------------------------- | ------------------- | -------------------------- |

功能相关

| 属性名 | 类型 | 默认值 | 说明 |

| ----------------------------- | -------------------------------- | ------------------- | -------------------------- |

AGGrid 专用

| 属性名 | 类型 | 默认值 | 说明 |

| ----------------------------- | -------------------------------- | ------------------- | -------------------------- |

| selection | Array | - | 选中项 |

| rowStyle | Function | - | 行样式 |

📋 Events 事件

| 事件名 | 参数 | 说明 |

| ------------------- | --------------------------------------- | ------------------ |

| selectionChange | selection: any[] | 多选项发生变化 |

| select | selection, row, status, params | 选择某一行 |

| selectAll | selection, status | 全选/取消全选 |

| currentChange | currentRow | 当前行变化 |

| row-click | row, column, event | 行点击事件 |

| row-dblclick | row, column, event | 行双击事件 |

| expand-change | row, expanded | 展开/收起变化 |

| filterModified | - | 过滤条件修改 |

| filterChanged | - | 过滤条件变化 |

| update:selectedRow| row | 单选行更新 |

| update:selectedValue| value | 单选值更新 |

| mounted | { parentEl } | 组件挂载完成 |

📋 Expose 方法 (通过 ref 调用)

选择相关

| 方法名 | 参数 | 返回值 | 说明 |

| --------------------- | --------------------------------- | --------- | -------------------------- |

| getSelectionRows | - | any[] | 获取选中的行 |

| toggleAllSelection | - | - | 切换全选状态 |

| setCurrentRow | row | - | 设置当前高亮行 |

| clearSelection | - | - | 清空选中 |

| setSelection | - | - | 设置选中 |

| selectAll | - | - | 全选 |

| deselectAll | - | - | 取消全选 |

验证相关

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| validateRow | - | - | 验证单行 |

| clearValidation | - | - | 清除验证 |

| clearRowValidation | - | - | 清除行验证 |

数据操作

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| getTableData | - | any[] | 获取表格数据 |

编辑状态

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| resetRowEditState | - | - | 重置行编辑状态 |

| resetEditState | - | - | 重置编辑状态 |

刷新相关

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| refresh | - | - | 刷新表格 |

| forceRefresh | - | - | 强制刷新 |

| forceRefreshTable | - | - | 强制刷新表格 |

| refreshColumnVisible | - | - | 刷新列可见性 |

| refreshHeader | - | - | 刷新表头 |

展开/折叠

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| expandAll | - | - | 展开所有行 |

| collapseAll | - | - | 折叠所有行 |

| collRow | row | - | 折叠指定行 |

滚动/定位

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

导出

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

其他

| 方法名 | 参数 | 返回值 | 说明 |

| -------------------- | --------------------------------- | --------- | -------------------------- |

| closeLoading | - | - | 关闭加载状态 |

| clearFilters | - | - | 清除过滤 |

| data | - | any[] | 表格数据 (computed) |

📋 列配置 TableColumnDesc

基础属性

typescript


interface TableColumnDesc<T = any> {

  // 列名（字段名）⚠️ 重要：使用 name 而非 prop

  name?: string;

  // 列标题

  label?: string;

  // 列类型

  type?: "index" | "selection" | "radio" | "expand";

  // 列宽

  width?: number;

  // 最小列宽

  minWidth?: number;

  // 弹性宽度

  flex?: number;

  // 对齐方式

  align?: "left" | "center" | "right";

  // 表头对齐

  headerAlign?: "left" | "center" | "right";

  // 固定列

  fixed?: "left" | "right";

  // 列宽可调整

  resizable?: boolean;

  // 是否可排序

  sortable?: boolean;

  // 超出省略号

  showOverflowTooltip?: boolean;

  // 允许换行

  wrapText?: boolean;

  // 自动调整行高

  autoHeight?: boolean;

  // 是否可过滤

  filterable?: boolean;

}

自定义渲染 (⚠️ 重要)

BaseTable 支持多种自定义渲染方式：

1. defaultSlot - 默认插槽 (推荐)

typescript


import { h } from "vue";



{

  name: "title",

  label: "标题",

  // ✅ 正确方式：使用 defaultSlot + h 函数

  defaultSlot: ({ row, $index }) => {

    return h(

      "span",

      { style: "color: #409eff; cursor: pointer;" },

      row.title

    );

  }

}

2. defaultNode - 低代码插槽

typescript


{

  name: "status",

  label: "状态",

  defaultNode: ({ row, $index, params }) => {

    return {

      tag: "el-tag",

      props: { type: row.status === 1 ? "success" : "danger" },

      children: row.status === 1 ? "启用" : "禁用"

    };

  }

}

3. formatter - 文本格式化

typescript


{

  name: "amount",

  label: "金额",

  // ⚠️ formatter 返回纯文本，不支持 HTML

  formatter: (row, params) => {

    return `¥${Number(row.amount).toLocaleString()}`;

  }

}

4. headerSlot - 表头插槽

typescript


import { h } from "vue";



{

  name: "price",

  label: "价格",

  headerSlot: () => {

    return h("span", { class: "custom-header" }, [

      h("span", "价格"),

      h("el-tooltip", { content: "含税价格" }, h("i", { class: "el-icon-info" }))

    ]);

  }

}

可编辑列

typescript


{

  name: "quantity",

  label: "数量",

  // 开启编辑

  editable: true,

  // 或条件编辑

  editable: (row) => row.status !== "locked",

  // 单击编辑

  singleClickEdit: true,

  // 始终显示编辑框

  alwaysEditable: true,

  // 自动聚焦

  autoFocusInput: true,

  // 校验规则

  rules: [{ required: true, message: "请输入数量" }],

  required: true,

  // 生效校验规则

  effectRule: (row) => row.needValidate,

  // 自定义编辑组件

  editComponent: (row, value, params) => ({

    tag: "el-input-number",

    props: { min: 0, max: 100 }

  })

}

操作列

typescript


{

  label: "操作",

  width: 200,

  fixed: "right",

  operations: [

    {

      name: "edit",

      label: "编辑",

      type: "primary",

      // 权限控制

      permission: ["user:edit"],

      // 点击事件

      onClick: (row, index, params) => {

        console.log("编辑", row);

      }

    },

    {

      name: "delete",

      label: "删除",

      type: "danger",

      // 禁用条件

      disabled: (row) => row.status === "locked",

      // 显示条件

      show: (row, index) => row.canDelete,

      onClick: (row, index) => {

        console.log("删除", row);

      }

    }

  ]

}

逻辑数据类型

typescript


{

  name: "status",

  label: "状态",

  // 自动从字典获取显示值

  logicType: "ORDER_STATUS",

  logicValue: "status"

}

行合并配置

BaseTable 支持在列配置中直接定义行合并规则，无需手动编写 span-method。

方式一：使用 `spanOnceRow` 自动合并相同值

typescript


{

  name: "category",

  label: "类别",

  width: 120,

  // 自动合并相邻相同值的单元格

  spanOnceRow: true

}

方式二：使用 `span` 函数自定义合并逻辑（推荐）

typescript


{

  name: "testCategory",

  label: "试验种类",

  width: 150,

  align: "center",

  // 自定义行合并逻辑

  span: ({ rowIndex, data }: any) => {

    if (!data || data.length === 0) {

      return { rowSpan: 1, colSpan: 1 };

    }

    

    const currentCategory = data[rowIndex]?.testCategory;

    const prevCategory = rowIndex > 0 ? data[rowIndex - 1]?.testCategory : null;

    

    // 如果是分组的第一行，计算需要合并的行数

    if (rowIndex === 0 || currentCategory !== prevCategory) {

      let rowSpan = 1;

      for (let i = rowIndex + 1; i < data.length; i++) {

        if (data[i].testCategory === currentCategory) {

          rowSpan++;

        } else {

          break;

        }

      }

      return { rowSpan, colSpan: 1 };

    }

    

    // 非第一行则隐藏

    return { rowSpan: 0, colSpan: 0 };

  }

}

完整示例：分组合并表格

vue


<template>

  <BaseTable

    :data="experimentData"

    :columns="columns"

    border

  />

</template>



<script setup lang="ts">

import { ref, computed } from "vue";

import { h } from "vue";



const experimentData = ref([

  { id: 1, testCategory: "化学成分", testItem: "C", value: "0.15" },

  { id: 2, testCategory: "化学成分", testItem: "Si", value: "0.30" },

  { id: 3, testCategory: "化学成分", testItem: "Mn", value: "1.20" },

  { id: 4, testCategory: "力学性能", testItem: "抗拉强度", value: "≥500" },

  { id: 5, testCategory: "力学性能", testItem: "屈服强度", value: "≥350" }

]);



const columns = computed(() => [

  {

    type: "index",

    label: "序号",

    width: 60,

    // 序号列也需要合并

    span: ({ rowIndex, data }: any) => {

      if (!data || data.length === 0) return { rowSpan: 1, colSpan: 1 };

      

      const currentCategory = data[rowIndex]?.testCategory;

      const prevCategory = rowIndex > 0 ? data[rowIndex - 1]?.testCategory : null;

      

      if (rowIndex === 0 || currentCategory !== prevCategory) {

        let rowSpan = 1;

        for (let i = rowIndex + 1; i < data.length; i++) {

          if (data[i].testCategory === currentCategory) {

            rowSpan++;

          } else {

            break;

          }

        }

        return { rowSpan, colSpan: 1 };

      }

      return { rowSpan: 0, colSpan: 0 };

    }

  },

  {

    name: "testCategory",

    label: "试验种类",

    width: 120,

    align: "center",

    span: ({ rowIndex, data }: any) => {

      if (!data || data.length === 0) return { rowSpan: 1, colSpan: 1 };

      

      const currentCategory = data[rowIndex]?.testCategory;

      const prevCategory = rowIndex > 0 ? data[rowIndex - 1]?.testCategory : null;

      

      if (rowIndex === 0 || currentCategory !== prevCategory) {

        let rowSpan = 1;

        for (let i = rowIndex + 1; i < data.length; i++) {

          if (data[i].testCategory === currentCategory) {

            rowSpan++;

          } else {

            break;

          }

        }

        return { rowSpan, colSpan: 1 };

      }

      return { rowSpan: 0, colSpan: 0 };

    }

  },

  {

    name: "testItem",

    label: "试验项目",

    width: 150

  },

  {

    name: "value",

    label: "标准值",

    width: 100

  }

]);

</script>

span 函数参数说明

typescript


interface SpanParams {

  rowIndex: number;    // 当前行索引

  columnIndex: number; // 当前列索引

  row: any;           // 当前行数据

  column: any;        // 当前列配置

  data: any[];        // 全部表格数据

}



// 返回值

interface SpanResult {

  rowSpan: number;  // 行合并数量，0 表示隐藏

  colSpan: number;  // 列合并数量，0 表示隐藏

}

行合并最佳实践

使用 spanOnceRow: true - 适用于简单的相邻相同值合并
使用 span 函数 - 适用于复杂的分组合并逻辑
多列合并 - 需要合并的每一列都要配置 span 函数
注意性能 - span 函数会在每次渲染时调用，避免复杂计算
数据排序 - 确保数据按分组字段排序，否则合并效果不正确

样式控制

typescript


{

  name: "amount",

  label: "金额",

  // 单元格样式类

  cellClass: (params) => {

    return params.value < 0 ? "negative-amount" : "";

  },

  // 单元格样式

  cellStyle: (params) => {

    return { color: params.value < 0 ? "red" : "green" };

  },

  // 链接样式

  isLink: (row) => true,

  // 单元格点击

  onCellClick: (params) => {

    console.log("点击", params.data);

  },

  onCellDblclick: (params) => {

    console.log("双击", params.data);

  }

}

分组与汇总

typescript


{

  name: "amount",

  label: "金额",

  // 聚合函数

  aggregationFn: ["sum", "avg"],

  // 行分组

  rowGroup: true

}

数字精度

typescript


{

  name: "price",

  label: "单价",

  logicType: "number",

  // 保留2位小数

  precision: 2,

  // 不足自动补0

  precisionAutoFillZero: true

}

🎯 操作按钮配置 TableRowOperation

typescript


interface TableRowOperation {

  // 按钮标识

  name?: string;

  // 按钮文本

  label: string;

  // 主题颜色

  type?: "primary" | "success" | "warning" | "danger" | "info";

  // 图标

  icon?: string;

  // 自动加载状态

  autoLoading?: boolean;

  // 禁用

  disabled?: boolean | ((row) => boolean);

  // 显示条件

  show?: (row, index) => boolean;

  // 点击事件

  onClick?: (row, index, params) => void;

  // 按钮权限

  permission?: string[];

}

💡 完整示例

基础列表页

vue


<template>

  <div class="app-container">

    <BaseTable

      ref="tableRef"

      :data="list"

      :columns="columns"

      :loading="loading"

      showToolbar

      border

      @selectionChange="handleSelectionChange"

    />



    <jh-pagination

      v-show="page.total > 0"

      :total="page.total"

      v-model:currentPage="page.current"

      v-model:pageSize="page.size"

      @current-change="loadData"

      @size-change="loadData"

    />

  </div>

</template>



<script setup lang="ts">

import { ref, computed, onMounted, h } from "vue";

import type { TableColumnDesc } from "@jhlc/common-core/src/components/table/base-table/type";



const tableRef = ref();

const list = ref([]);

const loading = ref(false);

const selectedRows = ref([]);

const page = ref({ current: 1, size: 10, total: 0 });



const columns = computed<TableColumnDesc[]>(() => [

  { type: "selection", width: 40 },

  { type: "index", label: "序号", width: 60 },

  {

    name: "orderNo",

    label: "订单号",

    width: 150,

    // 蓝色链接样式

    defaultSlot: ({ row }) => {

      return h(

        "span",

        {

          style: "color: #409eff; cursor: pointer;",

          onClick: () => viewDetail(row)

        },

        row.orderNo

      );

    }

  },

  {

    name: "customerName",

    label: "客户名称",

    showOverflowTooltip: true

  },

  {

    name: "amount",

    label: "金额",

    align: "right",

    formatter: (row) => `¥${Number(row.amount).toLocaleString()}`

  },

  {

    name: "status",

    label: "状态",

    logicType: "ORDER_STATUS"

  },

  {

    name: "createTime",

    label: "创建时间",

    width: 180

  },

  {

    label: "操作",

    width: 180,

    fixed: "right",

    operations: [

      {

        name: "view",

        label: "查看",

        onClick: (row) => viewDetail(row)

      },

      {

        name: "edit",

        label: "编辑",

        type: "primary",

        permission: ["order:edit"],

        onClick: (row) => editRecord(row)

      },

      {

        name: "delete",

        label: "删除",

        type: "danger",

        permission: ["order:delete"],

        disabled: (row) => row.status !== "draft",

        onClick: (row) => deleteRecord(row)

      }

    ]

  }

]);



const handleSelectionChange = (selection) => {

  selectedRows.value = selection;

};



const viewDetail = (row) => {

  // 查看详情

};



const editRecord = (row) => {

  // 编辑记录

};



const deleteRecord = (row) => {

  // 删除记录

};



const loadData = async () => {

  loading.value = true;

  try {

    // 加载数据

  } finally {

    loading.value = false;

  }

};



onMounted(() => {

  loadData();

});

</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263

可编辑表格

vue


<template>

  <BaseTable

    ref="tableRef"

    :data="list"

    :columns="editableColumns"

    border

  />

  <el-button @click="handleValidate">验证</el-button>

  <el-button @click="handleSave">保存</el-button>

</template>



<script setup lang="ts">

import { ref, computed } from "vue";



const tableRef = ref();

const list = ref([

  { id: 1, name: "", quantity: 0, price: 0 }

]);



const editableColumns = computed(() => [

  { type: "index", label: "序号", width: 60 },

  {

    name: "name",

    label: "名称",

    editable: true,

    rules: [{ required: true, message: "请输入名称" }]

  },

  {

    name: "quantity",

    label: "数量",

    editable: true,

    editComponent: () => ({

      tag: "el-input-number",

      props: { min: 1 }

    })

  },

  {

    name: "price",

    label: "单价",

    editable: true,

    precision: 2

  }

]);



const handleValidate = () => {

  tableRef.value?.validate((valid) => {

    console.log("验证结果:", valid);

  });

};



const handleSave = () => {

  const data = tableRef.value?.getTableData();

  console.log("保存数据:", data);

};

</script>

⚠️ 注意事项

列字段名使用 name 而非 prop

typescript


// ✅ 正确

{ label: "姓名", name: "userName" }



// ❌ 错误

{ label: "姓名", prop: "userName" }

自定义渲染使用 defaultSlot 而非 render

typescript


// ✅ 正确

{

  name: "title",

  defaultSlot: ({ row }) => h("span", { style: "color: blue;" }, row.title)

}



// ❌ 错误

{

  name: "title",

  render: (value) => `<span style="color: blue;">${value}</span>`

}

formatter 只能返回纯文本

typescript


// ✅ 正确 - 返回文本

formatter: (row) => `¥${row.amount}`



// ❌ 错误 - 返回 HTML（不会解析）

formatter: (row) => `<span class="red">${row.amount}</span>`

操作按钮的权限控制
- 使用 permission 属性配置权限标识数组
- 系统会自动根据用户权限显示/隐藏按钮
表格高度设置
- 固定高度：height="400"
- 自适应：配合 flex 布局，设置 height="100%" 或 autoHeight

树形数据必须设置 rowKey

vue


<BaseTable :data="treeData" :columns="columns" rowKey="id" />

BaseTable 表格组件 ​

📦 导入方式 ​

🚀 基本用法 ​

📋 Props 属性 ​

基础属性 ​

外观属性 ​

选择相关 ​

功能相关 ​

AGGrid 专用 ​

📋 Events 事件 ​

📋 Expose 方法 (通过 ref 调用) ​

选择相关 ​

验证相关 ​

数据操作 ​

编辑状态 ​

刷新相关 ​

展开/折叠 ​

滚动/定位 ​

导出 ​

其他 ​

📋 列配置 TableColumnDesc ​

基础属性 ​

自定义渲染 (⚠️ 重要) ​

1. defaultSlot - 默认插槽 (推荐) ​

2. defaultNode - 低代码插槽 ​

3. formatter - 文本格式化 ​

4. headerSlot - 表头插槽 ​

可编辑列 ​

操作列 ​

逻辑数据类型 ​

行合并配置 ​

方式一：使用 spanOnceRow 自动合并相同值 ​

方式二：使用 span 函数自定义合并逻辑（推荐） ​

完整示例：分组合并表格 ​

span 函数参数说明 ​

行合并最佳实践 ​

样式控制 ​

分组与汇总 ​

数字精度 ​

🎯 操作按钮配置 TableRowOperation ​

💡 完整示例 ​

基础列表页 ​

可编辑表格 ​

⚠️ 注意事项 ​

📚 相关文档 ​

BaseTable 表格组件

📦 导入方式

🚀 基本用法

📋 Props 属性

基础属性

外观属性

选择相关

功能相关

AGGrid 专用

📋 Events 事件

📋 Expose 方法 (通过 ref 调用)

选择相关

验证相关

数据操作

编辑状态

刷新相关

展开/折叠

滚动/定位

导出

其他

📋 列配置 TableColumnDesc

基础属性

自定义渲染 (⚠️ 重要)

1. defaultSlot - 默认插槽 (推荐)

2. defaultNode - 低代码插槽

3. formatter - 文本格式化

4. headerSlot - 表头插槽

可编辑列

操作列

逻辑数据类型

行合并配置

方式一：使用 `spanOnceRow` 自动合并相同值

方式二：使用 `span` 函数自定义合并逻辑（推荐）

完整示例：分组合并表格

span 函数参数说明

行合并最佳实践

样式控制

分组与汇总

数字精度

🎯 操作按钮配置 TableRowOperation

💡 完整示例

基础列表页

可编辑表格

⚠️ 注意事项

📚 相关文档