By-Components

# ByTable 表格组件

基于 VxeTable (opens new window) 的高级表格组件，提供数据展示、排序、分页、列宽缓存、自定义列配置、虚拟滚动等功能。

注意：本组件基于 VxeTable 实现，支持 VxeTable 的所有功能。如需了解更多高级配置和功能，请参考 VxeTable 官方文档 (opens new window)。

# 基础用法

<template>
  <by-table :grid-options="gridOptions" name="user-table" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          { field: 'name', title: '姓名', width: 120 },
          { field: 'age', title: '年龄', width: 80 },
          { field: 'address', title: '地址', width: 200 }
        ],
        data: [
          { name: '张三', age: 18, address: '厦门市湖里创新园' },
          { name: '李四', age: 20, address: '上海市外滩18号' }
        ]
      }
    }
  }
}
</script>

# 高级功能

# 1. 列宽缓存功能

当设置 name 属性时，表格会自动缓存用户调整的列宽，下次刷新页面时会保持缓存的列宽。

<template>
  <by-table :grid-options="gridOptions" name="user-table" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          { field: 'name', title: '姓名' },
          { field: 'age', title: '年龄' },
          { field: 'address', title: '地址' }
        ],
        data: [...]
      }
    }
  }
}
</script>

特性：

  • 自动缓存用户拖拽调整的列宽
  • 支持多级表头的列宽缓存，多级表头时，缓存的是二级表头
  • 提供"重置列宽"按钮恢复默认宽度

    注意： 注意同一项目中 name 必须唯一，否则会导致缓存数据冲突

# 2. 左侧固定列

支持设置左侧固定列，当固定列数量超过限制时会自动取消固定。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          { field: 'id', title: 'ID', fixed: 'left', width: 80 },
          { field: 'name', title: '姓名', fixed: 'left', width: 120 },
          { field: 'age', title: '年龄', width: 80 },
          { field: 'address', title: '地址', width: 200 }
        ],
        data: [...]
      }
    }
  }
}
</script>

特性：

  • 支持单级和多级表头的固定列
  • 默认最多支持6个固定列，超过会自动取消固定
  • 可通过 customColumnConfig.fixedMaxCount 自定义固定列最大数量
  • 移动设备自适应：在移动设备或屏幕宽度小于1000px时，会自动取消所有固定列，以提升移动端的用户体验

# 3. 前端分页

支持前端分页模式，数据在客户端进行分页处理。（注意：数据量较大时，请务必使用前端分页模式。 并且需要一次性加载所有数据）

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [...],
        data: [...], // 完整数据
        pagerConfig: {
          currentPage: 1,
          pageSize: 10,
          total: 100,
          pageSizes: [10, 20, 50, 100],
          frontendPagination: true // 启用前端分页
        }
      }
    }
  }
}
</script>

特性：

  • 支持大数据量的前端分页（配置pagerConfig.frontendPagination = true 启用前端分页）
  • 启用前端分页后，内部已实现前端排序功能
  • 排序时会自动回到第一页
  • 支持第一条数据置顶处理，可通过 sortConfig.hasTopRow 配置是否有置顶行，影响排序和分页的行为处理

# 4. 前端排序

支持前端排序模式，数据在客户端进行排序处理。（与虚拟滚动配合使用，启用虚拟滚动时，请务必使用前端排序模式）

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          { field: 'name', title: '姓名', sortable: true },
          { field: 'age', title: '年龄', sortable: true },
          { field: 'score', title: '得分', sortable: true }
        ],
        data: [...],
        sortConfig: {
          frontendSort: true, // 启用前端排序
          remote: true,
          trigger: 'cell'
        }
      }
    }
  }
}
</script>

特性：

  • 支持数字、字符串、百分比等多种数据类型的智能排序
  • 与虚拟滚动功能配合使用
  • 排序状态会保持高亮显示
  • 支持特殊字符和空值处理

# 5. 自定义列配置

支持用户自定义显示哪些列，以及列的顺序。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [...],
        data: [...],
        customColumnConfig: {
          showCustomColumn: true, // 显示自定义列按钮
          infoMethod: this.getColumnInfo, // 获取列信息的方法
          submitMethod: this.saveColumnConfig, // 保存列配置的方法
          fixedMaxCount: 6, // 固定列最大数量
          slots: ['action'] // 自定义插槽字段
        }
      }
    }
  },
  methods: {
    getColumnInfo({ page }) {
      // 返回列配置信息
      return Promise.resolve({
        data: {
          id: 1,
          column: [
            {
              label: '基本信息',
              data: [
                { key: 'name', label: '姓名', type: true },
                { key: 'age', label: '年龄', type: true }
              ]
            }
          ]
        }
      })
    },
    saveColumnConfig(config) {
      // 保存列配置
      console.log('保存列配置:', config)
    }
  }
}
</script>

特性：

  • 支持拖拽调整列顺序
  • 支持分组显示列配置
  • 支持搜索列名
  • 支持恢复默认配置
  • 支持固定列数量限制

# 6. 多级表头

支持多级表头配置。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          {
            title: '基本信息',
            children: [
              { field: 'name', title: '姓名', width: 120 },
              { field: 'age', title: '年龄', width: 80 }
            ]
          },
          {
            title: '联系信息',
            children: [
              { field: 'phone', title: '电话', width: 120 },
              { field: 'email', title: '邮箱', width: 150 }
            ]
          }
        ],
        data: [...]
      }
    }
  }
}
</script>

# 7. 复制功能

支持点击单元格复制内容。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [
          { field: 'name', title: '姓名' },
          { field: 'phone', title: '电话' }
        ],
        data: [...],
        copyFields: ['phone'] // 可复制的字段
      }
    }
  }
}
</script>

# 8. 序号列配置

支持自定义序号列。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      gridOptions: {
        columns: [...],
        data: [...],
        seqConfig: {
          seqMethod: ({ rowIndex }) => rowIndex + 1, // 自定义序号方法
          width: 60
        }
      }
    }
  }
}
</script>

# 9. 虚拟滚动

支持虚拟滚动功能，适用于大数据量场景，提升表格性能。

<template>
  <by-table :grid-options="gridOptions" />
</template>

<script>
export default {
  data() {
    return {
      virtualScrollConfig: {
        scrollY: {
          enabled: true,
          gt: 100, // 数据量大于100时启用虚拟滚动
          scrollToTopOnChange: true, // 数据变化时滚动到顶部
        },
        renderConfig: {
          optimize: true, // 启用渲染优化
          useVirtual: true, // 启用虚拟滚动
        },
      },
      gridOptions: {
        height: 720,
        ...this.virtualScrollConfig, //虚拟滚动配置 （启用虚拟滚动，需配置sortConfig.frontendSort = true,以兼容排序逻辑）
        sortConfig: {
          frontendSort:true
        },
        columns: [
          { field: 'name', title: '姓名', width: 120 },
          { field: 'age', title: '年龄', width: 80 },
          { field: 'address', title: '地址', width: 200 }
        ],
        data: [...], // 大数据量
      }
    }
  }
}
</script>

特性：

  • 支持大数据量的高性能渲染
  • 可配置虚拟滚动的触发条件
  • 启用虚拟滚动后，内部实现了排序功能，需配置sortConfig.frontendSort = true,以兼容排序逻辑

# API

# Props

参数 说明 类型 默认值
gridOptions 表格配置 Object {}
name 表格名称（用于列宽缓存） String ''
autoHeight 是否根据内容自动撑高 Boolean false

# gridOptions 配置

参数 说明 类型 默认值
columns 列配置 Array []
data 表格数据 Array []
pagerConfig 分页配置 Object -
sortConfig 排序配置 Object -
seqConfig 序号列配置 Object -
resizableConfig 列宽调整配置 Object -
rowConfig 行配置 Object -
customColumnConfig 自定义列配置 Object -
copyFields 可复制字段列表 Array []
height 表格高度 Number 550
border 是否显示边框 Boolean true
emptyText 空数据文本 String 暂无数据
scrollY 垂直滚动配置 Object -
renderConfig 渲染配置 Object -

# pagerConfig 分页配置

参数 说明 类型 默认值
currentPage 当前页码 Number 1
pageSize 每页条数 Number 10
total 总条数 Number 0
pageSizes 每页条数选项 Array [10, 20, 50, 100]
frontendPagination 是否启用前端分页 Boolean false

# sortConfig 排序配置

参数 说明 类型 默认值
remote 是否远程排序 Boolean false
trigger 排序触发方式 String 'cell'
frontendSort 是否启用前端排序 Boolean false
hasTopRow 是否有置顶行 Boolean false

# customColumnConfig 自定义列配置

参数 说明 类型 默认值
showCustomColumn 是否显示自定义列按钮 Boolean false
infoMethod 获取自定义列信息的方法 Function -
submitMethod 提交自定义列配置的方法 Function -
fixedMaxCount 固定列最大数量 Number 6
slots 自定义插槽配置 Array []

# resizableConfig 列宽调整配置

参数 说明 类型 默认值
minWidth 最小列宽 Number 50

# rowConfig 行配置

参数 说明 类型 默认值
height 行高 Number 41
isHover 是否显示hover效果 Boolean true

# renderConfig 渲染配置

参数 说明 类型 默认值
optimize 启用渲染优化 Boolean false
useVirtual 启用虚拟滚动 Boolean false

# scrollY 垂直滚动配置

参数 说明 类型 默认值
enabled 是否启用虚拟滚动 Boolean false
gt 数据量大于此值时启用虚拟滚动 Number 100
scrollToTopOnChange 数据变化时是否滚动到顶部 Boolean true

# Events

事件名 说明 参数
cell-click 单元格点击 context
page-change 分页改变 values
resizable-change 列宽改变 context
sort-change 排序改变 event
setColumn 设置列配置 columns
setGroupColumn 设置分组列配置 columns

# Methods

方法名 说明 参数
resetCachedTableColumns 重置列宽缓存 -
getCustomColumnRef 获取自定义列组件引用 -
handleOpenCustomColumn 打开自定义列对话框 -
resetSortState 重置排序状态 -

# 列配置 (columns)

参数 说明 类型 默认值
field 字段名 String -
title 列标题 String -
width 列宽 Number -
minWidth 最小列宽 Number -
maxWidth 最大列宽 Number -
fixed 固定列位置 String -
sortable 是否可排序 Boolean true
slots 插槽配置 Object -
children 子列配置 Array -

# 样式类

类名 说明
.table-row-overflow-line-2 文本超出两行显示省略号
.text_pointer_primary 模拟Element按钮的text样式
.table_wrapper 表格外围样式
.group-split 多级表头分隔列样式

# 注意事项

  1. 列宽缓存：设置 name 属性时，同一项目中必须唯一，否则会导致缓存冲突
  2. 固定列限制：默认最多支持6个左侧固定列，超过会自动取消固定（可通过 customColumnConfig.fixedMaxCount 自定义固定列最大数量）
  3. 移动设备适配：在移动设备或屏幕宽度小于1000px时，会自动取消所有固定列，以提升移动端的用户体验
  4. 前端分页：启用前端分页时，需要传入完整的数据集
  5. 自定义列：需要提供 infoMethod 和 submitMethod 两个方法
  6. 多级表头：支持无限层级的表头嵌套
  7. 排序功能：支持数字、字符串、百分比等多种数据类型的智能排序
  8. 虚拟滚动：适用于大数据量场景，建议数据量超过100条时启用虚拟滚动以提升性能
最后更新时间: 7/11/2025, 2:23:12 PM

← ByPager 分页组件 →