Cvue

Table 表格

用于展示多条结构类似的数据， 可对数据进行排序、筛选、对比或其他自定义操作。

基础用法

<template>
  <cvue-table
    :operation="{ width: 200 }"
    :search="search"
    :columns="columns"
    :data="data"
    @row-add="handleRowAdd"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'

  const columns = reactive([
    {
      label: '姓名',
      prop: 'date',
    },
    {
      label: '性别',
      prop: 'name',
    },
    {
      label: '年龄',
      prop: 'age',
    },
  ])
  const data = reactive([
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
  ])

  const onLoad = (val: Record<string, any>) => {
    console.log(val)
  }

  const handleRowAdd = () => {
    console.log('handleRowAdd')
  }

  const search = reactive({
    columns: [
      {
        label: '什么鬼的a',
        prop: 'prop1',
      },
      {
        label: 'label2',
        prop: 'prop2',
      },
      {
        label: 'label3',
        prop: 'prop3',
      },
    ],
  })
</script>

带斑马纹表格

使用带斑马纹的表格，可以更容易区分出不同行的数据。

stripe 可以创建带斑马纹的表格。 如果 true, 表格将会带有斑马纹。

<template>
  <cvue-table
    stripe
    :operation="{ width: 200 }"
    :columns="columns"
    :data="data"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = reactive([
  {
    label: '标题1',
    prop: 'date',
  },
  {
    label: '标题2',
    prop: 'name',
  },
  {
    label: '标题3',
    prop: 'address',
  },
])
const data = reactive([
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
])

const onLoad = (val: Record<string, any>) => {
  console.log(val)
}
</script>

带边框表格

默认情况下，Table 组件是不具有竖直方向的边框的， 如果需要，可以使用 border 属性，把该属性设置为 true 即可启用。

<template>
  <cvue-table
    border
    :operation="{ width: 200 }"
    :columns="columns"
    :data="data"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = reactive([
  {
    label: '标题1',
    prop: 'date',
  },
  {
    label: '标题2',
    prop: 'name',
  },
  {
    label: '标题3',
    prop: 'address',
  },
])
const data = reactive([
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
])

const onLoad = (val: Record<string, any>) => {
  console.log(val)
}
</script>

带状态表格

可将表格内容 highlight 显示，方便区分「成功、信息、警告、危险」等内容。

可以通过指定 Table 组件的 row-class-name 属性来为 Table 中的某一行添加 class， 这样就可以自定义每一行的样式了。

<template>
  <cvue-table
    :operation="{ width: 200 }"
    :columns="columns"
    :data="data"
    :row-class-name="tableRowClassName"
    @row-add="handleRowAdd"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'

  const tableRowClassName = ({ row, rowIndex }: { row: any; rowIndex: number }) => {
    if (rowIndex === 1) {
      return 'warning-row'
    } else if (rowIndex === 3) {
      return 'success-row'
    }
    return ''
  }

  const columns = reactive([
    {
      label: '标题1',
      prop: 'date',
    },
    {
      label: '标题2',
      prop: 'name',
    },
    {
      label: '标题3',
      prop: 'address',
    },
  ])
  const data = reactive([
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
    {
      date: '2022-12-12',
      name: 'wishzhang',
      address: '广州',
    },
  ])

  const onLoad = (val: Record<string, any>) => {
    console.log(val)
  }

  const handleRowAdd = () => {
    console.log('handleRowAdd')
  }
</script>

<style>
  .el-table .warning-row {
    --el-table-tr-bg-color: var(--el-color-warning-light-9);
  }

  .el-table .success-row {
    --el-table-tr-bg-color: var(--el-color-success-light-9);
  }
</style>

固定表头

纵向内容过多时，可选择固定表头。

只要在 el-table 元素中定义了 height 属性，即可实现固定表头的表格，而不需要额外的代码。

<template>
  <cvue-table
    :height="200"
    :operation="{ width: 200 }"
    :columns="columns"
    :data="data"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = reactive([
  {
    label: '标题1',
    prop: 'date',
  },
  {
    label: '标题2',
    prop: 'name',
  },
  {
    label: '标题3',
    prop: 'address',
  },
])
const data = reactive([
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
])

const onLoad = (val: Record<string, any>) => {
  console.log(val)
}
</script>

固定列

横向内容过多时，可选择固定列。

固定列需要使用 fixed 属性，它接受 Boolean 值。 如果为 true, 列将被左侧固定. 它还接受传入字符串，left 或 right，表示左边固定还是右边固定。

<template>
  <cvue-table
    style="width:100%;"
    :operation="{ width: 200, fixed: 'right' }"
    :columns="columns"
    :data="data"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = reactive([
  {
    label: '标题1',
    prop: 'date',
    fixed: 'left',
    width: 200
  },
  {
    label: '标题2',
    prop: 'name',
    width: 600
  },
  {
    label: '标题3',
    prop: 'address'
  },
])
const data = reactive([
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
])

const onLoad = (val: Record<string, any>) => {
  console.log(val)
}
</script>

排序

对表格进行排序，可快速查找或对比数据。

在列中设置 sortable 属性即可实现以该列为基准的排序， 接受一个 Boolean，默认为 false。 可以通过 Table 的 default-sort 属性设置默认的排序列和排序顺序。 可以使用 sort-method 或者 sort-by 使用自定义的排序规则。 如果需要后端排序，需将 sortable 设置为 custom，同时在 Table 上监听 sort-change 事件， 在事件回调中可以获取当前排序的字段名和排序顺序，从而向接口请求排序后的表格数据。 在本例中，我们还使用了 formatter 属性，它用于格式化指定列的值， 接受一个 Function，会传入两个参数：row 和 column， 可以根据自己的需求进行处理。

<template>
  <cvue-table
    :default-sort="{ prop: 'date', order: 'descending' }"
    :operation="{ width: 200 }"
    :columns="columns"
    :data="data"
    @on-load="onLoad"
  ></cvue-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = reactive([
  {
    label: '标题1',
    prop: 'date',
    sortable: true
  },
  {
    label: '标题2',
    prop: 'name',
  },
  {
    label: '标题3',
    prop: 'address',
  },
])
const data = reactive([
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
  {
    date: '2022-12-12',
    name: 'wishzhang',
    address: '广州',
  },
])

const onLoad = (val: Record<string, any>) => {
  console.log(val)
}
</script>

属性

属性名说明类型可选值默认值
data显示的数据array——
heightTable 的高度， 默认为自动高度。 如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height 的值，Table 的高度会受控于外部样式。string / number——
max-heightTable 的最大高度。 合法的值为数字或者单位为 px 的高度。string / number——
stripe是否为斑马纹 tableboolean—false
border是否带有纵向边框boolean—false
sizeTable 的尺寸stringlarge / default /small—
fit列的宽度是否自撑开boolean—true
show-header是否显示表头boolean—true
highlight-current-row是否要高亮当前行boolean—false
current-row-key当前行的 key，只写属性string / number——
row-class-name行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。function({ row, rowIndex }) / string——
row-style行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。function({ row, rowIndex }) / object——
cell-class-name单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className。function({ row, column, rowIndex, columnIndex }) / string——
cell-style单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style。function({ row, column, rowIndex, columnIndex }) / object——
header-row-class-name表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className。function({ row, rowIndex }) / string——
header-row-style表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style。function({ row, rowIndex }) / object——
header-cell-class-name表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className。function({ row, column, rowIndex, columnIndex }) / string——
header-cell-style表头单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有表头单元格设置一样的 Style。function({ row, column, rowIndex, columnIndex }) / object——
row-key行数据的 Key，用来优化 Table 的渲染； 在使用reserve-selection功能与显示树形数据时，该属性是必填的。 类型为 String 时，支持多层访问：user.info.id，但不支持 user.info[0].id，此种情况请使用 Function。function(row) / string——
empty-text空数据时显示的文本内容， 也可以通过 #empty 设置string—No Data
default-expand-all是否默认展开所有行，当 Table 包含展开行存在或者为树形表格时有效boolean—false
expand-row-keys可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组。array——
default-sort默认的排序列的 prop 和顺序。 它的 prop 属性指定默认的排序的列，order 指定默认排序的顺序object(order: 'ascending' 'descending')如果 prop 已配置, 同时 order 未配置, 那么 order 默认为升序
tooltip-effecttooltip effect 属性stringdark / lightdark
show-summary是否在表尾显示合计行boolean—false
sum-text合计行第一列的文本string—合计
summary-method自定义的合计计算方法function({ columns, data })——
span-method合并行或列的计算方法function({ row, column, rowIndex, columnIndex })——
select-on-indeterminate在多选表格中，当仅有部分行被选中时，点击表头的多选框时的行为。 若为 true，则选中所有行；若为 false，则取消选择所有行boolean—true
indent展示树形数据时，树节点的缩进number—16
lazy是否懒加载子节点数据boolean——
load加载子节点数据的函数，lazy 为 true 时生效，函数第二个参数包含了节点的层级信息function(row, treeNode, resolve)——
tree-props渲染嵌套数据的配置选项object—{ hasChildren: 'hasChildren', children: 'children' }
table-layout设置表格单元、行和列的布局方式stringfixed / autofixed
scrollbar-always-on总是显示滚动条boolean—false
flexible2.2.1确保主轴的最小尺寸boolean—false

事件

事件名说明参数
select当用户手动勾选数据行的 Checkbox 时触发的事件selection, row
select-all当用户手动勾选全选 Checkbox 时触发的事件selection
selection-change当选择项发生变化时会触发该事件selection
cell-mouse-enter当单元格 hover 进入时会触发该事件row, column, cell, event
cell-mouse-leave当单元格 hover 退出时会触发该事件row, column, cell, event
cell-click当某个单元格被点击时会触发该事件row, column, cell, event
cell-dblclick当某个单元格被双击击时会触发该事件row, column, cell, event
cell-contextmenu当某个单元格被鼠标右键点击时会触发该事件row, column, cell, event
row-click当某一行被点击时会触发该事件row, column, event
row-contextmenu当某一行被鼠标右键点击时会触发该事件row, column, event
row-dblclick当某一行被双击时会触发该事件row, column, event
header-click当某一列的表头被点击时会触发该事件column, event
header-contextmenu当某一列的表头被鼠标右键点击时触发该事件column, event
sort-change当表格的排序条件发生变化的时候会触发该事件{ column, prop, order }
filter-changecolumn 的 key， 如果需要使用 filter-change 事件，则需要此属性标识是哪个 column 的筛选条件filters
current-change当表格的当前行发生变化的时候会触发该事件，如果要高亮当前行，请打开表格的 highlight-current-row 属性currentRow, oldCurrentRow
header-dragend当拖动表头改变了列的宽度的时候会触发该事件newWidth, oldWidth, column, event
expand-change当用户对某一行展开或者关闭的时候会触发该事件（展开行时，回调的第二个参数为 expandedRows；树形表格时第二参数为 expanded）row, (expandedRows | expanded

方法

方法名说明参数
clearSelection用于多选表格，清空用户的选择—
getSelectionRows返回当前选中的行
toggleRowSelection用于多选表格，切换某一行的选中状态， 如果使用了第二个参数，则可直接设置这一行选中与否row, selected
toggleAllSelection用于多选表格，切换全选和全不选—
toggleRowExpansion用于可扩展的表格或树表格，如果某行被扩展，则切换。 使用第二个参数，您可以直接设置该行应该被扩展或折叠。row, expanded
setCurrentRow用于单选表格，设定某一行为选中行， 如果调用时不加参数，则会取消目前高亮行的选中状态。row
clearSort用于清空排序条件，数据会恢复成未排序的状态—
clearFilter传入由columnKey 组成的数组以清除指定列的过滤条件。 如果没有参数，清除所有过滤器columnKeys
doLayout对 Table 进行重新布局。 当表格可见性变化时，您可能需要调用此方法以获得正确的布局—
sort手动排序表格。 参数 prop 属性指定排序列，order 指定排序顺序。prop: string, order: string
scrollTo滚动到一组特定坐标(options: ScrollToOptions | number, yCoord?: number)
setScrollTop设置垂直滚动位置top
setScrollLeft设置水平滚动位置left
上次更新:
贡献者: wishzhang