ClTablePage 组件

基于 Vue 3 + Element Plus 的高性能表格页面组件，支持搜索、分页、自动高度、数据格式化等功能。

特性

• 🚀 开箱即用：只需配置 columnList 和 apiFun 即可快速构建表格页面
• 🔍 丰富的表单组件：支持 ElInput、ElSelect、ElRadioGroup、ElInputNumber、ElDatePicker
• 📐 灵活布局：支持响应式布局配置，可自定义每列宽度和倍数
• 📄 智能分页：自动处理分页逻辑，支持自定义分页参数
• 📊 数据格式化：支持 formatter 函数、枚举映射、空值默认文本
• 💫 溢出提示：支持单行/多行溢出展示 tooltip
• 🎯 插槽系统：丰富的插槽支持，高度自定义
• ⚡ 自动高度：智能计算表格高度，适配不同屏幕

安装

npm install cl-table-page

注册

全局注册

import { createApp } from 'vue'
import ClTablePage from 'cl-table-page'

const app = createApp(App)
app.use(ClTablePage, {
  // 全局配置（可选）
  tableProps: {},
  defaultContentEmptyText: '-',
  isAutoHeight: true,
  // ...其他配置
})

全局注册支持的配置项有：
- `tableProps`：Element Plus 表格属性，默认 `{}`
- `defaultContentEmptyText`：空值默认显示文本，默认 `'-'`
- `isShowLabel`：是否显示搜索标签，默认 `true`
- `serialConfig`：序号列配置，默认 `{ label: '序号', width: 60, align: 'center' }`
- `isAutoHeight`：是否自动计算高度，默认 `true`
- `formProps`：表单属性，默认 `{}`
- `layoutConfig`：布局配置，默认 `{ xs: 12, sm: 8, md: 6, lg: 4, xl: 4 }`
- `pageProps`：分页属性，默认 `{ pageSize: 10, total: 0, currentPage: 1, pageSizes: [10, 20, 30, 50, 100], pagerCount: 7 }`
- `isAutoLoad`：是否自动加载数据，默认 `true`
- `isShowBackTopBtn`：是否显示返回顶部按钮，默认 `false`
- `isEnterSearch`：是否回车搜索，默认 `true`
- `moreRowShowTooltip`：多行溢出展示行数，默认 `1`

局部注册

<template>
  <ClTablePage />
</template>

<script setup>
import ClTablePage from 'cl-table-page'
</script>

基础使用

<template>
  <ClTablePage
    v-model="formData"
    :apiFun="getListApi"
    :columnList="columnList"
  />
</template>

<script setup>
import { ref } from 'vue'

const formData = ref({})

const columnList = [
  { prop: 'id', label: '用户ID', formItem: { componentName: 'ElInput' } },
  { prop: 'name', label: '姓名', formItem: { componentName: 'ElInput' } },
  {
    prop: 'age',
    label: '年龄',
    align: 'center',
    formItem: { componentName: 'ElInputNumber' },
  },
  {
    prop: 'status',
    label: '状态',
    align: 'center',
    formItem: {
      componentName: 'ElSelect',
      options: [
        { value: 1, label: '启用' },
        { value: 0, label: '禁用' },
      ],
    },
  },
]

const getListApi = (params) => {
  return new Promise((resolve) => {
    resolve({
      rows: [],
      total: 0,
    })
  })
}
</script>

Props 配置

| 属性名 | 类型 | 默认值 | 说明 | | ------------------------- | ---------------- | --------------------------------------------------------------------------------------------- | -------------------------------------- | | columnList | Array | columnItem[] | 表格列配置 | | apiFun | Function | null | 接口请求函数 | | title | String | '' | 页面标题 | | isShowSearch | Boolean | true | 是否显示搜索模块 | | isShowLabel | Boolean | true | 是否显示搜索标签 | | formProps | Object | {} | el-form组件的属性 | | layoutConfig | Object | { xs: 12, sm: 8, md: 6, lg: 4, xl: 4 } | 布局配置 | | isEnterSearch | Boolean | true | 是否回车搜索 | | tableProps | Object | {} | el-table组件的属性 | | isAutoHeight | Boolean | true | 是否自动计算高度 | | defaultContentEmptyText | String | '-' | 空值默认显示文本 | | showOverflowTooltip | Boolean/Object | false | 是否显示溢出提示，或溢出提示配置 | | moreRowShowTooltip | Number | 1 | 超出多少行开启溢出展示 | | serialConfig | Object/Boolean | { label: '序号', width: 60, align: 'center' } | 序号列配置，设为 false 隐藏 | | isShowPagination | Boolean | true | 是否显示分页 | | pageProps | Object | { pageSize: 10, total: 0, currentPage: 1, pageSizes: [10, 20, 30, 50, 100], pagerCount: 7 } | el-pagination组件的属性 | | receiveListField | String | 'rows' | 接口返回数据中列表字段的名称 | | isAutoLoad | Boolean | true | 是否自动加载数据 | | isShowBackTopBtn | Boolean | false | 是否显示返回顶部按钮 | | defaultSearchParams | Object | {} | 默认查询参数,不会被重置 | | beforeGetList | Function | null | 请求前钩子，可以进行请求参数的修改，必须返回参数对象 | | afterGetList | Function | null | 请求后钩子，修改数据，必须返回数据数组 |

columnItem 配置,其实就是el-table组件里面的column组件的各个属性

| 属性名 | 类型 | 默认值 | 说明 | | ---------- | --------- | ------- | ------------ | | prop | String | '' | 字段名 | | label | String | '' | 列标题 | | formItem | Object | {} | 表单组件配置 | | hide | Boolean | false | 是否隐藏该列 |

其他属性请参考el-table组件的column组件属性

formItem 配置,其实就是el-input,el-select等表单组件的属性

| 属性名 | 类型 | 默认值 | 说明 | | ---------------- | --------- | -------------- | ------------------------------------------------------------------------ | | componentName | String | '' | 组件名 | | multiples | Number | 2 | 宽度倍数 | | sort | Number | 1 | 排序优先级 | | hide | Boolean | false | 是否隐藏该表单项 | | splitFieldList | Array | ['x1', 'x2'] | 时间区间分割字段, 当选择时间区间的组件时, 用于指定时间区间分割字段的名称 |

其他属性请参考各个表单组件的属性

表单组件支持

ElInput

{
  formItem: {
    componentName: 'ElInput',
    placeholder: '请输入内容',
    maxlength: 50,
    showWordLimit: true,
  }
}

ElSelect

{
  formItem: {
    componentName: 'ElSelect',
    placeholder: '请选择',
    options: [
      { value: 1, label: '选项一' },
      { value: 2, label: '选项二' },
    ],
    props: {
      label: 'label',
      value: 'value',
    },
  }
}

ElRadioGroup

{
  formItem: {
    componentName: 'ElRadioGroup',
    options: [
      { value: 1, label: '是' },
      { value: 0, label: '否' },
    ],
  }
}

ElInputNumber

{
  formItem: {
    componentName: 'ElInputNumber',
    min: 1,
    max: 100,
    step: 1,
  }
}

ElDatePicker

{
  formItem: {
    componentName: 'ElDatePicker',
    type: 'daterange',        // daterange | datetime | monthpicker...
    valueFormat: 'YYYY-MM-DD',
    splitFieldList: ['startDate', 'endDate'],  // 分割为两个字段
  }
}

插槽（Slots）

操作按钮区域

<ClTablePage>
  <template #operation-box>
    <el-button type="primary">新增</el-button>
    <el-button>导出</el-button>
  </template>
</ClTablePage>

表格列插槽

<ClTablePage :columnList="columnList">
  <!-- column 中设置 slot: true 启用 -->
  <template #action="{ row }">
    <el-button size="small">编辑</el-button>
    <el-button size="small" type="danger">删除</el-button>
  </template>
  
  <template #name="{ row }">
    <el-button type="link">{{ row.name }}</el-button>
  </template>
</ClTablePage>

表单字段插槽

<ClTablePage>
  <template #name-form="{ formData, column }">
    <el-input v-model="formData.customName" placeholder="自定义输入"></el-input>
  </template>
</ClTablePage>

其他插槽

| 插槽名 | 说明 | | -------------- | ------------ | | title | 标题插槽 | | table-bottom | 表格底部插槽 | | serial | 序号列插槽 |

方法（Methods）

通过 ref 调用组件方法：

<template>
  <ClTablePage ref="tableRef" />
</template>

<script setup>
import { ref } from 'vue'

const tableRef = ref(null)

// 刷新列表
tableRef.value?.getList()

// 重置表单
tableRef.value?.handleReset()

// 删除后自动处理分页
tableRef.value?.getListWithPrevPage()

// 获取表格数据
const data = tableRef.value?.tableData
</script>

布局配置

全局布局

<ClTablePage
  :layoutConfig="{
    xs: 12, // < 576px
    sm: 8, // >= 576px
    md: 6, // >= 768px
    lg: 4, // >= 992px
    xl: 3, // >= 1200px
  }"
/>

单个表单项倍数

{
  prop: 'id',
  label: '用户ID',
  formItem: {
    componentName: 'ElInput',
    multiples: 2,  // 在 xl:3 布局下占用 6 个单位
  },
}

溢出提示

基础溢出提示

<ClTablePage show-overflow-tooltip />

多行溢出提示

<ClTablePage show-overflow-tooltip :more-row-show-tooltip="2" />

自定义 tooltip 配置

<ClTablePage
  :show-overflow-tooltip="{
    popperStyle: { width: '300px' },
    enterable: false,
    placement: 'bottom',
    effect: 'light',
  }"
/>

列级别配置

{
  prop: 'description',
  label: '描述',
  showOverflowTooltip: {
    popperStyle: { maxWidth: '400px' },
  },
  moreRowShowTooltip: 3,
}

示例

完整示例

<template>
  <ClTablePage
    ref="tableRef"
    v-model="formData"
    title="用户管理"
    :apiFun="getListApi"
    :columnList="columnList"
    :pageProps="pageConfig"
    :isAutoHeight="true"
    :beforeGetList="beforeGetList"
    :afterGetList="afterGetList"
  >
    <template #operation-box>
      <el-button type="primary" @click="handleAdd">新增</el-button>
    </template>
    <template #action="{ row }">
      <el-button size="small" @click="handleEdit(row)">编辑</el-button>
      <el-button size="small" type="danger" @click="handleDelete(row)"
        >删除</el-button
      >
    </template>
  </ClTablePage>
</template>

<script setup>
import { ref, reactive } from 'vue'

const tableRef = ref(null)
const formData = ref({})

const pageConfig = reactive({
  pageSize: 10,
  currentPage: 1,
})

const columnList = [
  { prop: 'id', label: '用户ID', formItem: { componentName: 'ElInput' } },
  {
    prop: 'name',
    label: '姓名',
    formItem: { componentName: 'ElInput', sort: 1 },
  },
  {
    prop: 'age',
    label: '年龄',
    align: 'center',
    formItem: { componentName: 'ElInputNumber', min: 1, max: 150 },
  },
  {
    prop: 'gender',
    label: '性别',
    align: 'center',
    formatter: (v) => ['男', '女', '未知'][v],
  },
  {
    prop: 'status',
    label: '状态',
    align: 'center',
    formItem: {
      componentName: 'ElSelect',
      options: [
        { value: 1, label: '启用', style: 'color: #67c23a' },
        { value: 0, label: '禁用', style: 'color: #f56c6c' },
      ],
    },
  },
  {
    prop: 'createTime',
    label: '创建时间',
    align: 'center',
    formItem: {
      componentName: 'ElDatePicker',
      type: 'daterange',
      splitFieldList: ['startTime', 'endTime'],
    },
  },
  { prop: 'action', label: '操作', align: 'center', width: 200, slot: true },
]

const getListApi = (params) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        rows: [],
        total: 100,
      })
    }, 300)
  })
}

const beforeGetList = (params) => {
  params.timestamp = Date.now()
  return params
}

const afterGetList = (rows) => {
  return rows.map((row) => ({ ...row, flag: true }))
}

const handleAdd = () => {}
const handleEdit = (row) => {}
const handleDelete = (row) => {}
</script>

注意事项

1. apiFun 函数必须返回 Promise，且 resolve 的数据结构为 { rows: [], total: 0 }
2. formItem.componentName 支持的组件：ElInput、ElSelect、ElRadioGroup、ElInputNumber、ElDatePicker
3. 时间区间字段需配置 splitFieldList，将数组分割为两个独立字段
4. 插槽名称使用 prop 值，表单插槽使用 prop-form 格式
5. serialConfig 设为 false 可隐藏序号列

许可证

MIT