JVxeTable表格

JVXETable基于vxe-table组件开发的高性能表格，支持大数据和各种ERP风格的复杂操作，示例请见：JVxeTable示例演示

截图效果

参数配置

基础参数配置

参数	类型	默认值	说明
columns	array	[]	【必填】表格列的配置描述，详见`[columns 参数配置](./JVxeTable.md#columns参数配置)`
dataSource	array	[]	【必填】表格数据
size	string	'medium'	表格尺寸，可选值有：`'medium'、 'small'、 'mini'`
loading	boolean	false	是否正在加载
height	number, string	'auto'	表格的固定高度，如果是string就只能填'auto'，代表自适应高度
maxHeight	number	null	设定最大高度`(px)`，默认null不限定最大高度
disabled	boolean	false	是否禁用全部组件
bordered	boolean	false	是否显示单元格竖向边框线
toolbar	boolean	false	是否显示工具栏
toolbarConfig	object	`{slot: ['prefix', 'suffix'], btn: ['add', 'remove', 'clearSelection']}`	toolbarConfig工具栏配置
rowNumber	boolean	false	是否显示行号
rowNumberFixed	string	left	固定行号(left)或者不固定(none)
rowSelection	boolean	false	是否可选择行
rowSelectionType	string	'checkbox'	选择行类型，可选值：`'checkbox'(多选)`、 `'radio'(单选)`
rowExpand	boolean	false	是否可展开行
expandConfig	object		展开行配置
disabledRows	object		禁用行配置
dragSort	boolean	false	是否可拖拽排序（有固定列的情况下无法拖拽排序，仅可上下排序）
insertRow	boolean	true	`2024-10-15` 是否允许插入一行（在有拖拽排序列时，可单击排序图标选择插入一行）
sortKey	string	'orderNum'	排序字段保存的Key
sortBegin	number	0	排序序号开始值
pagination	object		分页器参数，设置了即可显示分页器，详见（APagination分页）
clickRowShowSubForm	boolean	false	点击行时是否显示子表单
clickRowShowMainForm	boolean	false	点击行时是否显示主表单
clickSelectRow	boolean	false	是否点击选中行，优先级最低
reloadEffect	boolean	false	是否开启 reload 数据效果
editRules	object		校验规则
asyncRemove	boolean	false	是否异步删除行，如果你要实现异步删除，那么需要把这个选项开启；在remove事件里调用confirmRemove方法才会真正删除（除非删除的全是新增的行）
authPre	string	''	配置按钮`/`列权限，通常规则是`[前缀:列编码]`或`[前缀:btn:按钮编码]` 如`vxe:btn:add`（设置新增按钮的权限）；`vxe:name`（设置name列的权限）。如果果需要在该table上作权限控制，就需要配置此属性为权限编码的前缀，此例中为`jvxeauth`
linkageConfig	array	[]	多级联动配置，详见【多级联动配置】
socketReload	boolean	false	是否开启使用 webSocket 无痕刷新
socketKey	string	'vxe-default'	相同的socketKey更改时会互相刷新
addSetActive	boolean	true	新增行时切换行的激活状态
cacheColumnsKey	string	""	列设置缓存key（默认取的路由当做key，当一个页面内有多个JVXETable，需要设置防止列设置缓存冲突）
custom	boolean	false	是否出现自定义列配置 `v3.6.4+`
dragSortFixed	string	'left'	拖拽按钮是否固定左侧，可选值：'none'、 'left' 。（如果字段较多确定会出现横向滚动条，且需要拖动排序功能时应设为'none'） `v3.6.4+`
rowSelectionFixed	string	'left'	chekbox或radio是否固定左侧，可选值：'none'、 'left' `v3.6.4+`
keyboardEdit	boolean	false	是否开启键盘编辑
rowClassName	string	""	jvxe最外层的类名，用自定义样式
notAllowDrag	object	""	不允许拖拽的行,用法：`[{'key':field,'value':value}]`,`field`:当前字段名称,`value`:当前填写的值
addBtnCfg	object	""	新增按钮配置，用法：`{ enabled: true, buttonIcon: 'ant-design:plus-outlined',buttonName: '新增'}`
removeBtnCfg	object	""	删除按钮配置，用法：`{ enabled: true, buttonIcon: 'ant-design:minus-outlined',buttonName: '删除'}`
更多配置详见VXETable文档

columns参数配置

参数	类型	说明
key	string	【必填】列数据在数据项中对应的`key`，必须是唯一的
title	string	表格列头显示的标题
type	string	表单的类型，可以通过`JVxeTypes`赋值（详见：【组件配置文档】）
fixed	string	left（固定左侧）, right（固定右侧）
width	string	列的宽度,`px`、`%`
minWidth		最小列宽度，`px`、`%`；会自动将剩余空间按比例分配
align	string	列对齐方式 left（左对齐）, center（居中对齐）, right（右对齐）
placeholder	string	表单预期值的提示信息，可以使用`${...}`变量替换文本
defaultValue	string	默认值，在新增一行时生效
props	object	设置添加给表单元素的自定义属性，例如:`props:{title: 'show title'}`
disabled	boolean	是否禁用当前列，默认false
validateRules	array	表单验证规则，配置方式见validateRules配置规则
formatter	`Function({cellValue, row, column})`	格式化显示内容，将处理后的值返回即可。注：仅影响展示的值，不会修改实际的值，也就是说，在获取和点击编辑时不会受影响

validateRules配置规则

validateRules需要的是一个数组，数组里每项都是一个规则，规则是object类型，规则的各个参数如下

required是否必填，可选值为trueorfalse
unique唯一校验，不可重复，可选值为trueorfalse
pattern正则表达式验证，只有成功匹配该正则的值才能成功通过验证
handler自定义函数校验，使用方法请见【使用示例_五】)
message当验证未通过时显示的提示文本，可以使用${...}变量替换文本
配置示例请看【使用示例_二】

toolbarConfig工具栏配置

效果展示：显示新增、删除、保存按钮，在新增按钮前面插入检验按钮、在删除按钮后面插入复制按钮

代码示例

<template>
  <a-card>
    <!-- 
       toolbarConfig 中的 prefix对应插槽名称是toolbarPrefix、suffix对应插槽名称是toolbarSuffix
       显示删除按钮需要开启rowSelection
       -->
    <JVxeTable
        toolbar
        :toolbarConfig="toolbarConfig"
        rowSelection
        :height="340"
        :columns="columns"
        :dataSource="dataSource"
    >
      <template #toolbarPrefix>
        <a-button type="primary" danger preIcon="ant-design:safety-outlined">检验</a-button>
      </template>
      <template #toolbarSuffix>
        <a-button type="primary" preIcon="ant-design:copy-outlined">复制</a-button>
      </template>
    </JVxeTable>
  </a-card>
</template>

<script lang="ts" setup>
  // 即时保存示例
  import { reactive, ref } from 'vue';
  import { JVxeColumn, JVxeTypes } from '/@/components/jeecg/JVxeTable/types';
  import JVxeTable from "@/components/jeecg/JVxeTable/src/JVxeTable";
  
  // 工具栏的按钮配置
  const toolbarConfig = reactive({
    // add 新增按钮；save 保存按钮；remove 删除按钮
    btn: ['add', 'save', 'remove'],
    //prefix 按钮前方位置显示的内容 suffix 按钮后方位置显示的内容
    slot:['prefix','suffix']
  });
  // 数据源，控制表格的数据
  const dataSource = ref<Recordable[]>([
    {"num":1,"company":"侭俏侯住有限公司"},
    {"num":2,"company":"侘俯侟佰有限公司"},
  ]);
  // 列配置，控制表格显示的列
  const columns = ref<JVxeColumn[]>([
    { key: 'num', title: '序号', width: 80, type: JVxeTypes.normal },
    {
      key: 'company',
      title: '公司',
      // 最小宽度，与宽度不同的是，这个不是固定的宽度，如果表格有多余的空间，会平均分配给设置了 minWidth 的列
      // 如果要做占满表格的列可以这么写
      minWidth: 180,
      type: JVxeTypes.input,
    },
  ]);
  
</script>

<style scoped></style>

disabledRows禁用行配置

展示效果：序号列不允许编辑

代码示例

<template>
  <a-card>
    <JVxeTable
        toolbar
        rowSelection
        :height="340"
        :columns="columns"
        :dataSource="dataSource"
        :disabledRows="{ dbFieldName: ['num'] }"
    >
    </JVxeTable>
  </a-card>
</template>

<script lang="ts" setup>
  // 即时保存示例
  import { ref } from 'vue';
  import { JVxeColumn, JVxeTypes } from '/@/components/jeecg/JVxeTable/types';
  import JVxeTable from "@/components/jeecg/JVxeTable/src/JVxeTable";
  
  // 数据源，控制表格的数据
  const dataSource = ref<Recordable[]>([
    {"num":1,"company":"侭俏侯住有限公司"},
    {"num":2,"company":"侘俯侟佰有限公司"},
  ]);
  // 列配置，控制表格显示的列
  const columns = ref<JVxeColumn[]>([
    { key: 'num', title: '序号', width: 80, type: JVxeTypes.normal },
    {
      key: 'company',
      title: '公司',
      // 最小宽度，与宽度不同的是，这个不是固定的宽度，如果表格有多余的空间，会平均分配给设置了 minWidth 的列
      // 如果要做占满表格的列可以这么写
      minWidth: 180,
      type: JVxeTypes.input,
    },
  ]);
  
</script>

<style scoped></style>

editRules检验规则

效果展示

editRules更多属性请参考：editRules属性

代码示例

<template>
  <a-card>
    <JVxeTable
        toolbar
        :height="340"
        :columns="columns"
        :dataSource="dataSource"
        :editRules="editRules"
    >
    </JVxeTable>
  </a-card>
</template>

<script lang="ts" setup>
  // 即时保存示例
  import { ref } from 'vue';
  import { JVxeColumn, JVxeTypes } from '/@/components/jeecg/JVxeTable/types';
  import JVxeTable from "@/components/jeecg/JVxeTable/src/JVxeTable";
  
  // 数据源，控制表格的数据
  const dataSource = ref<Recordable[]>([
    {"num":1,"company":"侭俏侯住有限公司"},
    {"num":2,"company":"侘俯侟佰有限公司"},
  ]);

  // 列配置，控制表格显示的列
  const columns = ref<JVxeColumn[]>([
    { key: 'num', title: '序号', width: 80, type: JVxeTypes.normal },
    {
      key: 'company',
      title: '公司',
      // 最小宽度，与宽度不同的是，这个不是固定的宽度，如果表格有多余的空间，会平均分配给设置了 minWidth 的列
      // 如果要做占满表格的列可以这么写
      minWidth: 180,
      type: JVxeTypes.input,
    },
  ]);
  
  //重点
  const editRules = ref({ company: [{required: true, validator: companyValidator}] })

  /**
   * 公司检验
   * @param cellValue
   */
  function companyValidator({cellValue}) {
    return new Promise((resolve, reject) => {
      if (cellValue === '') {
        return reject('公司不能为空！');
      } else {
        const reg = /^[\u4E00-\u9FA5]+$/;
        if (!reg.test(cellValue)) {
          return reject(new Error('请输入中文！'));
        }
        return resolve('');
      }
    })
  }
</script>

事件

save

触发时机：只有点击保存按钮时才会触发

added

触发时机：点击新增按钮、调用addRows方法时会触发
携带参数：
- row：添加完成后的行
- rows：如果添加了多行，将返回此参数

如果调用addRows方法添加多行，则每添加一行都会触发一次该事件

inserted

触发时机：调用insertRows方法时会触发
携带参数：
- row：插入完成后的行
- rows：如果插入了多行，将返回此参数
- insertIndex：插入的下标

如果调用insertRows方法添加多行，则每添加一行都会触发一次该事件

removed

触发时机：点击删除按钮、调用removeRows方法时会触发
携带参数：
- deleteRows：即将被删除的行
- confirmRemove：确认删除方法只有当点击删除按钮，并且开启了asyncRemove属性后才会返回

如果asyncRemove参数设为true，则会传递confirmRemove方法，否者不会，且只有调用了该方法后才会真正删除（除非删除的全是新增的行）
如果asyncRemove参数设为false，就会直接删除行，而不用调用confirmRemove。

dragged

触发时机：拖拽排序后、上下移动后触发
携带参数：
- oldIndex：排序前的 index
- newIndex：排序后的 index

selectRowChange

触发时机：当行被选中或取消选中时触发
携带参数：
- type：选中类型
  - radio：单选
  - checkbox：多选
- action：选中操作
  - selected：选中
  - unselected：取消选中
  - selected-all：全选
- row：当前操作的行（全选时没有该参数）
- selectedRows：所有被选中的行
- selectedRowIds：所有被选中的行的ID
- $event：原生事件

pageChange

触发时机：当分页参数被改变时触发
携带参数：
- current：当前页码
- pageSize：当前页大小

valueChange

触发时机：当数据发生改变的时候触发的事件
携带参数：
- type：组件类型（JVXETypes中定义的类型）
- value：新值
- oldValue：旧值
- row：当前行
- col：当前列
- column：当前列配置
- rowIndex：当前行下标
- columnIndex：当前列下标
- cellTarget：当前组件实例
- isSetValues：为true则代表是通过setValues方法触发的事件

特别注意： 如果是通过setValues方法触发的事件，将不会传递row、rowIndex、columnIndex、cellTarget这几个参数的。

方法

getXTable

获取 vxe-table 实例，用于调用 vxe-table 的原生方法，详见：VxeTable文档

addRows

说明：添加一行或多行临时数据，会填充默认值，总是会激活添加的最后一行的编辑模式
参数：
- rows：[object | array] 要添加的行
- options：object 选项参数
  - setActive：是否激活添加的最后一行的编辑模式，默认继承props.addSetActive
返回值：Promise

pushRows

说明：添加一行或多行临时数据，不会填充默认值，传什么就添加进去什么
参数：
- rows：[object | array] 要添加的行
- options：object 选项参数
  - index：默认-1，插入位置，-1为最后一行
  - setActive：默认false，是否激活添加的最后一行的编辑模式
返回值：Promise

resetScrollTop

说明：重置滚动条Top位置
参数：
- top：number 新top位置，留空则滚动到上次记录的位置，用于解决切换tab选项卡时导致白屏以及自动将滚动条滚动到顶部的问题
返回值：无

validateTable

说明：校验table，失败返回errMap，成功返回null
参数：无
返回值：Promise

setValues

说明：设置某行某列的值
参数：
- values：array
返回值：void

getValues

说明：获取表格的值
参数：
- callback：获取成功后的callback
- rowIds：指定查询的行ID，不传返回所有行
返回值：void

getTableData

说明：获取表格数据
参数：
- options：object 选项参数
  - rowIds：string[] 行ID，传了就只返回传递的行
返回值：row[]

getSelectionData

说明：获取选中数据
参数：
- isFull：如果为 true 则获取全表已选中的数据
返回值：row[]

getNewData

说明：仅获取新增的临时数据
参数：无
返回值：row[]

getNewDataWithId

说明：仅获取新增的临时数据，带有临时ID
参数：无
返回值：row[]

getIfRowById

说明：根据ID获取行，新增的临时行也能查出来
参数：id
返回值：{row, isNew}
- row：获取到的行
- isNew：当前行是否是新增的临时行

getNewRowById

说明：通过临时ID获取新增的临时行
参数：id
返回值：row

getDeleteData

说明：仅获取被删除的数据（新增又被删除的数据不会被获取到）
参数：无
返回值：row[]

clearSelection

说明：清空选择
参数：无
返回值：void

removeRows

说明：删除一行或多行数据
参数：
- rows：[object | array] 要删除的行
返回值：Promise

removeRowsById

说明：根据id删除一行或多行
参数：
- rowId：[string | array] 要删除的行ID
返回值：Promise

removeSelection

说明：删除选中的数据
参数：无
返回值：Promise

isDisabledRow

说明：判断是否是禁用行
参数：
- rowId：行数据
- force：boolean 是否强制刷新，默认=true
返回值：boolean

recalcDisableRows

说明：重新计算禁用行，当修改了 props.disabledRows 参数时需要用到
参数：无
返回值：void

socketSendUpdateRow

说明：发送socket消息更新行，在WebSocket无痕刷新中会用到
参数：
- row：要更新的行
返回值：void

内置插槽

插槽名	说明
toolbarPrefix	在操作按钮的前面插入插槽，和自带的按钮共处于一行，受`toolbar`和`toolbarConfig`属性的影响
toolbarSuffix	在操作按钮的后面插入插槽，和自带的按钮共处于一行，受`toolbar`和`toolbarConfig`属性的影响
toolbarAfter	在工具条的下面插入插槽，不受`toolbar`和`toolbarConfig`属性的影响
subForm	点击展开子表的内容
mainForm	弹出主表的内容

截图效果​

参数配置​

基础参数配置​

columns参数配置​

validateRules配置规则​

toolbarConfig工具栏配置​

disabledRows禁用行配置​

editRules检验规则​

事件​

save​

added​

inserted​

removed​

dragged​

selectRowChange​

pageChange​

valueChange​

方法​

getXTable​

addRows​

pushRows​

resetScrollTop​

validateTable​

setValues​

getValues​

getTableData​

getSelectionData​

getNewData​

getNewDataWithId​

getIfRowById​

getNewRowById​

getDeleteData​

clearSelection​

removeRows​

removeRowsById​

removeSelection​

isDisabledRow​

recalcDisableRows​

socketSendUpdateRow​

内置插槽​

截图效果

参数配置

基础参数配置

columns参数配置

validateRules配置规则

toolbarConfig工具栏配置

disabledRows禁用行配置

editRules检验规则

事件

save

added

inserted

removed

dragged

selectRowChange

pageChange

valueChange

方法

getXTable

addRows

pushRows

resetScrollTop

validateTable

setValues

getValues

getTableData

getSelectionData

getNewData

getNewDataWithId

getIfRowById

getNewRowById

getDeleteData

clearSelection

removeRows

removeRowsById

removeSelection

isDisabledRow

recalcDisableRows

socketSendUpdateRow

内置插槽