Element Hooks

外观

useTable ​

useTable 通过配置驱动 ElTable，你可以使用列定义数组代替 <template> 视图模板中的多层 el-table-column 嵌套，并通过控制器统一管理表格状态。

这种方式在列较多、交互复杂或需要动态切换列配置的场景中更具可维护性。

基础表格 ​

带斑马纹表格 ​

带边框表格 ​

带状态表格 ​

固定表头 ​

固定列 ​

固定列和表头 ​

流体高度 ​

多级表头 ​

单选 ​

多选 ​

排序 ​

筛选 ​

自定义列模板 ​

自定义表头 ​

展开行 ​

switch parent border:
switch child border:
preserve expanded:

State:

City:

Address:

Zip:

Family

暂无数据

树形数据与懒加载 ​

自定义索引 ​

表格布局 ​

合并列或行 ​

自定义悬浮提示 ​

始终显示悬浮提示 ​

尾部合计行 ​

API ​

Options ​

useTable 的配置项继承自 Element Plus ElTable 的 Props，并额外增加以下字段：

  • columns: TableColumn[] —— 核心配置，用于声明表格列。
  • data: T[] —— 表格数据。

TableColumn ​

属性与 ElTableColumn 的 props 一致，同时额外支持：

字段说明类型
slot默认插槽名（slots.default 的简写）string
slots具名插槽配置 (default, header, filterIcon, expand)Record<string, string>
children子列配置 (用于多级表头)TableColumn[]
render渲染组件配置{ component: Component | string, props?: Recordable }
render.component ​

当 render.component 为字符串时，会从 app.use(ElementHooks, { components }) 传入的全局组件映射中查找并渲染对应组件（例如 components: { tag: ElTag } 对应 render.component = 'tag'）。

render.props ​

在 render.props 中，如果你需要使用响应式变量来给组件传参，或者需要根据当前行的数据动态传参，可以将其写为一个函数。组件会在渲染时自动执行该函数（函数的默认参数为当前行的数据 row）并追踪依赖。

这意味着当你的响应式数据或当前行数据发生改变时，组件 Props 也会自动重新渲染，从而实现动态传参，无需再手动调用 setState 或 setColumns 刷新整个列表项配置。

注意事项

动态传参的特性会过滤掉以 on 开头的事件属性。例如 onClick 或 onChange 等事件监听器，即使为函数也不会被自动执行。

ts
import { ElTag } from 'element-plus';

const [Table] = useTable({
  columns: [
    {
      prop: 'gender',
      label: '性别',
      render: {
        component: ElTag,
        props: {
          // row 为当前行的数据
          type: row => (row.gender === '男' ? 'primary' : 'danger'),
        },
      },
    },
  ],
});
render.slot ​

slot 是 slots.default 的简写形式。当同一个列同时定义了 slot 和 render 时，插槽优先。

Controller ​

方法说明参数
setState动态更新表格整体配置(state: Partial<TableOptions>) => void
setColumns动态更新列定义(columns: TableColumn[]) => void
setData动态更新表格数据(data: T[]) => void
getData获取当前数据快照() => T[]
instance内部 ElTable 实例（可调用排序、选择等原生方法）Ref<TableInstance>