@liexx/table

基于 Vue 3 + Element Plus 的增强型表格组件，使用 TypeScript + Vite 构建。

安装

npm install @liexx/table element-plus
# 或
pnpm add @liexx/table element-plus

element-plus 为 peer dependency，需一并安装。

快速开始

全局注册

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import ProTablePlugin from '@liexx/table'
import '@liexx/table/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(ProTablePlugin)
app.mount('#app')

按需引入

<script setup lang="ts">
import { ProTable } from '@liexx/table'
import type { TableColumn } from '@liexx/table'
</script>

ProTable 高级表格

基于 Element Plus 的增强型数据表格，集成分页、搜索筛选、CRUD 表单弹窗、跨页选择、字典加载等功能。

基础用法

<template>
  <ProTable :columns="columns" :api="api" />
</template>

<script setup lang="ts">
import { ProTable } from '@liexx/table'
import type { TableColumn } from '@liexx/table'

const columns: TableColumn[] = [
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', type: 'input' },
  { prop: 'status', label: '状态', type: 'select', options: [
    { label: '启用', value: 1 },
    { label: '禁用', value: 0 }
  ]},
  { prop: 'createTime', label: '创建时间', type: 'date' }
]

const api = (params) => fetch('/api/list', { body: params })
</script>

带搜索栏

<template>
  <ProTable :columns="columns" :filters="filters" :api="api" />
</template>

<script setup lang="ts">
import type { TableColumn, TableFilter } from '@liexx/table'

const filters: TableFilter[] = [
  { prop: 'keyword', label: '关键词', type: 'input', span: 6 },
  { prop: 'status', label: '状态', type: 'select', options: [
    { label: '启用', value: 1 },
    { label: '禁用', value: 0 }
  ], span: 6 }
]
</script>

内置增删改

<template>
  <ProTable
    :columns="columns"
    :api="{ refresh, create, update, delete }"
    form-title="用户"
  />
</template>

<script setup lang="ts">
const refresh = (params) => getUserList(params)
const create = (data) => createUser(data)
const update = (data) => updateUser(data)
const delete = (row) => deleteUser(row.id)
</script>

自定义操作按钮

<template>
  <ProTable :columns="columns" :api="api" :actions="actions" />
</template>

<script setup lang="ts">
import type { TableActions } from '@liexx/table'

const actions: TableActions = [
  {
    key: 'export',
    title: '导出',
    isHeader: true,
    type: 'success',
    click: () => handleExport()
  },
  'create',
  {
    key: 'view',
    title: '查看',
    type: 'info',
    event: (row) => handleView(row)
  }
]
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | columns | TableColumn[] | [] | 表格列配置 | | api | TableApi \| TableApis | — | 接口配置 | | filters | TableFilter[] | [] | 搜索栏字段 | | actions | TableActions | — | 操作按钮 | | rowAction | TableRowAction | — | 行操作预处理 | | immediate | boolean | true | 是否立即请求数据 | | useApi | boolean | true | 是否通过接口操作 | | isPagination | boolean | true | 是否分页 | | selection | boolean | false | 显示复选框 | | hasIndex | boolean | false | 显示序号列 | | isCross | boolean | false | 跨页选择 | | isStorage | boolean | true | 缓存筛选条件 | | rowKey | string | 'id' | 行唯一标识字段 | | border | boolean | false | 表格边框 | | formTitle | string | — | 表单弹窗标题 | | formWidth | string | '750px' | 表单弹窗宽度 | | formLabelWidth | string | '120px' | 表单 label 宽度 | | formLabelPosition | 'left' \| 'right' \| 'top' | 'right' | 表单 label 位置 | | cancelBtnText | string | '取消' | 取消按钮文本 | | submitBtnText | string | '确认' | 确认按钮文本 | | submitBefore | (data, index) => boolean | — | 提交前钩子 | | updateBefore | (data) => any | — | 编辑前数据处理 | | submitExtendKeys | string[] | [] | 提交时额外携带字段 | | pageLayout | string | 'total, sizes, prev, pager, next' | 分页布局 | | smallPagination | boolean | false | 小型分页 | | headerBackground | string | '#ecf5ff' | 表头背景色 | | padding | string | '0px' | 表格内边距 | | searchLabelWidth | string | 'auto' | 搜索栏 label 宽度 | | selectable | (row, index) => boolean | — | 复选框可选条件 | | lazy | boolean | false | 表格懒加载 | | load | (row, treeNode, resolve) => void | — | 懒加载回调 | | defaultValue | Record<string, any> | — | 新增表单默认值 | | options | TableOptions | — | 全局配置 |

TableColumn 列配置

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | prop | string | — | 必填 字段名 | | label | string | — | 必填 列标题 / 表单 label | | type | 'input' \| 'select' \| 'date' \| 'number' \| 'textarea' \| 'switch' \| 'file' \| 'cascader' \| 'tree' \| 'image' \| 'radio' | 'input' | 表单组件类型 | | width | number \| string | — | 列宽度 | | minWidth | number \| string | — | 最小列宽 | | align | 'left' \| 'center' \| 'right' | 'left' | 对齐方式 | | sort | boolean | false | 是否可排序 | | sortData | [any, any] | — | 排序映射 [升序值, 降序值] | | visible | boolean | true | 是否显示在表格中 | | isForm | boolean | 跟随 type | 是否在表单中显示 | | required | boolean | false | 是否必填 | | formDefault | any | — | 表单默认值 | | enum | Record<string, any> | — | 枚举映射 | | options | { label, value, listClass? }[] | — | 下拉选项 | | dict | string | — | 字典标识，通过全局 dictApi 获取 | | optionApi | (column, context) => Promise | — | 异步获取选项 | | render | (row, index) => VNode \| string | — | 自定义渲染函数 | | formatter | (row, cellValue) => string | — | 格式化函数 | | showInfo | boolean | false | 显示溢出详情按钮 | | lineClamp | number | 1 | 文本截断行数 | | unique | boolean | false | 唯一性校验（useApi=false） | | uniqueMessage | string | — | 唯一性校验失败提示 | | span | number | — | 表单栅格占位（24 栏） | | rules | FormRule[] | — | 校验规则 | | tip | string | — | 表单提示信息 | | extends | Record<string, any> | — | 组件扩展属性 | | columnDisabled | boolean | false | 列在列切换中禁用 |

TableFilter 搜索栏配置

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | prop | string | — | 必填 字段名 | | label | string | — | 必填 标签 | | type | 'input' \| 'select' \| 'date' \| 'number' | 'input' | 输入类型 | | options | { label, value }[] | — | 选项 | | span | number | 6 | 栅格宽度（24 等分） | | dict | string | — | 字典标识 | | optionApi | Function | — | 异步获取选项 | | required | boolean | false | 是否必填 | | visible | boolean | true | 是否可见 | | disabled | boolean | false | 是否禁用 | | extends | Record<string, any> | — | 扩展属性 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | ready | — | 组件就绪 | | change | data: any[] | 数据变更 | | search | — | 搜索触发 | | reset | — | 重置触发 | | searchChange | params: Record<string, any>, type: string | 搜索参数变更 | | selectionChange | rows: any[] | 选中行变更 |

Slots

| 插槽 | 作用域 | 说明 | |------|--------|------| | header | — | 表格上方插槽 | | search-extra | — | 搜索栏额外操作 | | leftActions | — | 工具栏左侧 | | action_{key} | { action } | 自定义操作按钮渲染 | | header-{prop} | scope | 自定义列头 | | {prop} | { scope, index } | 自定义列内容 | | actions | { row, index } | 行操作列自定义 | | footer | — | 分页左侧插槽 |

方法 (Ref)

| 方法 | 参数 | 说明 | |------|------|------| | refresh | (page?, updateCache?) | 刷新数据 | | getValue | — | 获取当前数据 | | setValue | (data, extra?) | 设置数据 | | getFilterData | — | 获取筛选参数 | | setFilterValue | (data) | 设置筛选值 | | resetFilterValue | — | 重置筛选值 | | getSelectionRows | — | 获取选中行 | | setSelectionRows | (rows, selected?) | 设置选中行 | | clearSelectionRows | — | 清空选中行 | | native | (method, ...args) | 调用 el-table 原生方法 |

导出类型

export type {
  ProTableProps,      // 组件 Props
  TableColumn,        // 列配置
  TableColumns,       // 列配置数组
  TableFilter,        // 搜索栏配置
  TableAction,        // 操作按钮
  TableActions,       // 操作按钮数组
  TableActionData,    // 操作按钮详细配置
  TableApis,          // API 配置对象
  TableApi,           // API 函数
  ApiResponse         // API 返回格式
} from '@liexx/table'

开发

# 安装依赖
pnpm install

# 本地调试（默认端口 4399）
pnpm dev

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 构建产物
pnpm build

License

MIT