JVxeTable行编辑 · JeecgBoot 开发文档

# JVXETable 文档 [2020-09-14 | v2.3.0 版本] [TOC=2,2] >[info] [vxe-table 官方文档](https://xuliangzhan_admin.gitee.io/vxe-table/#/table/base/basic) > `JVXETable`基于`vxe-table`组件开发，使用方式与`JEditableTable`类似，但也不完全一样 ## 参数配置 ### 基础参数配置 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | columns | array | | **【必填】** 表格列的配置描述，详见【columns 参数配置】 | | dataSource | array | | **【必填】** 表格数据 | | size | string | 'medium' | 表格尺寸，可选值有：'medium'、 'small'、 'mini'、 'tiny' | | 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'\]} | 工具栏配置 | | rowNumber | boolean | false | 是否显示行号 | | rowSelection | boolean | false | 是否可选择行 | | rowSelectionType | string | 'checkbox' | 选择行类型，可选值：'checkbox'、 'radio' | | rowExpand | boolean | false | 是否可展开行 | | expandConfig | object | {} | 展开行配置 | | pagination | object | {} | 分页器参数，设置了即可显示分页器，详见（[APagination分页](https://antdv.com/components/pagination-cn/#API)） | | clickRowShowSubForm | boolean | false | 点击行时是否显示子表单 | | clickRowShowMainForm | boolean | false | 点击行时是否显示主表单 | | clickSelectRow | boolean | false | 是否点击选中行，优先级最低 | | reloadEffect | boolean | false | 是否开启 reload 数据效果 | | editRules | object | {} | 校验规则 | | asyncRemove | boolean | false | 是否异步删除行，如果你要实现异步删除，那么需要把这个选项开启；在remove事件里调用confirmRemove方法才会真正删除（除非删除的全是新增的行） | | authPre| string | | 配置按钮/列权限，通常规则是[前缀:列/按钮编码] 如`jvxeauth:add` ,如果需要在该table上作权限控制，就需要配置此属性为权限编码的前缀，此例中为`jvxeauth` | | alwaysEdit | boolean | false | 是否一直显示输入框，如果为false则只有点击的时候才出现输入框。注：该参数不能动态修改；如果行、列字段多的情况下，会根据机器性能造成不同程度的卡顿，谨慎使用 2.4.4+| | linkageConfig | array| [] | `2.4.7+` 多级联动配置，详见[【多级联动配置】](多级联动配置.md) | >[info] [更多配置详见VXETable文档](https://vxetable.cn/v2/#/table/api?filterName=columns) ### columns 参数配置 | 参数 | 类型 | 说明 | | --- | --- | --- | | title | string | **【必填】** 表格列头显示的标题 | | key | string | **【必填】** 列数据在数据项中对应的`key`，必须是**唯一**的 | | type | string | **【必填】** 表单的类型，可以通过`JVXETypes`赋值（详见：[【组件配置文档】](组件配置文档.md)） | | 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`是否必填，可选值为`true`or`false` * `unique`唯一校验，不可重复，可选值为`true`or`false` * `pattern`正则表达式验证，只有成功匹配该正则的值才能成功通过验证 * `handler`自定义函数校验，使用方法请见【使用示例\_五】) * `message`当验证未通过时显示的提示文本，可以使用`${...}`变量替换文本（详见【常见问题_${...} 变量如何使用】） * 配置示例请看【使用示例\_二】 ## 事件 ### added * `触发时机`：点击`新增`按钮、调用`addRows`方法时会触发 * `携带参数`： * `row`：添加完成后的行 >[info] 如果调用`addRows`方法添加多行，则每添加一行都会触发一次该事件 ### save * `触发时机`：只有点击`保存`按钮时才会触发 ### remove * `触发时机`：只有点击`删除`按钮时才会触发 * `携带参数`： * `deleteRows`：即将被删除的行的ID * `confirmRemove`：确认删除方法 >[info] 如果`asyncRemove`参数设为true，则会传递`confirmRemove`方法，否者不会，且只有调用了该方法后才会真正删除（除非删除的全是新增的行） > 如果`asyncRemove`参数设为false，就会直接删除行，而不用调用`confirmRemove`。 ### 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`方法触发的事件 >[info] **特别注意：** 如果是通过`setValues`方法触发的事件，将不会传递`row`、`rowIndex`、`columnIndex`、`cellTarget`这几个参数的。 ## 方法 ### addRows * `说明`：添加一行或多行临时数据，会填充默认值，总是会激活添加的最后一行的编辑模式 * `参数`： * `rows`：\[object | array\] 要添加的行 * `返回值`：Promise<row,rows> ### pushRows * `说明`：添加一行或多行临时数据，不会填充默认值，传什么就添加进去什么 * `参数`： * `rows`：\[object | array\] 要添加的行 * `options`：object 选项参数 * `index`：默认-1，插入位置，-1为最后一行 * `setActive`：默认false，是否激活添加的最后一行的编辑模式 * `返回值`：Promise<row,rows> ### loadData * `说明`：加载数据，和`dataSource`不同的是，由于该方法不直接绑定到页面上，所以可以防止vue监听大数据，提高性能。当然如果数据量少的话就模棱两可了。 * `参数`： * `dataSource`：array * `返回值`：Promise ### loadNewData * `说明`：加载新数据，和`loadData`不同的是，用该方法加载的数据都是相当于点新增按钮新增的数据，适用于不是数据库里查出来的没有id的临时数据。 * `参数`： * `dataSource`：array * `返回值`：Promise ### resetScrollTop * `说明`：重置滚动条Top位置 * `参数`： * `top`：number 新top位置，留空则滚动到上次记录的位置，用于解决切换tab选项卡时导致白屏以及自动将滚动条滚动到顶部的问题 * `返回值`：无 ### validateTable * `说明`：校验table，失败返回errMap，成功返回null * `参数`：无 * `返回值`：Promise ### setValues * `说明`：设置某行某列的值 * `参数`： * `values`：array * `返回值`：void ### getAll * `说明`：获取所有的数据，包括`tableData`、`deleteData` * `参数`：无 * `返回值`：{ tableData, deleteData } ### getTableData * `说明`：获取表格数据 * `参数`： * `options`：object 选项参数 * `rowIds`：string\[\] 行ID，传了就只返回传递的行 * `返回值`：row\[\] ### getNewData * `说明`：仅获取新增的临时数据 * `参数`：无 * `返回值`：row\[\] ### getIfRowById * `说明`：根据ID获取行，新增的临时行也能查出来 * `参数`：id * `返回值`：{row, isNew} * `row`：获取到的行 * `isNew`：当前行是否是新增的临时行 ### getNewRowById * `说明`：通过临时ID获取新增的临时行 * `参数`：id * `返回值`：row ### getDeleteData * `说明`：仅获取被删除的数据（新增又被删除的数据不会被获取到） * `参数`：无 * `返回值`：row\[\] ### clearSelection * `说明`：清空选择 * `参数`：无 * `返回值`：void ### removeRows * `说明`：删除一行或多行数据 * `参数`： * `rows`：\[object | array\] * `返回值`：void ### removeRowsById * `说明`：根据id删除一行或多行 * `参数`： * `rowId`：\[string | array\] * `返回值`：void >[info] [更多方法见VXETable文档](https://vxetable.cn/v2/#/grid/api?filterName=methods) ## 内置插槽 | 插槽名 | 说明 | | --- | --- | | toolbarPrefix | 在操作按钮的**前面**插入插槽，和自带的按钮共处于一行，受`toolbar`和`toolbarConfig`属性的影响 | | toolbarSuffix | 在操作按钮的**后面**插入插槽，和自带的按钮共处于一行，受`toolbar`和`toolbarConfig`属性的影响 | | toolbarAfter | 在工具条的**下面**插入插槽，不受`toolbar`和`toolbarConfig`属性的影响 | | subForm | 点击展开子表的内容 | | mainForm | 弹出主表的内容 | ## vxeUtils.js 使用说明引用路径：`@/components/jeecg/JVxeTable/utils/vxeUtils.js` ### export 的常量 * `VALIDATE_FAILED` 在判断表单验证是否通过时使用，如果 reject 的值 === VALIDATE\_NO\_PASSED 则代表表单验证未通过，你可以做相应的其他处理，反之则可能是发生了报错，可以使用`console.error`输出 ### 封装的方法 #### validateTables * `说明`：一次性验证多个JVxeTable实例当你的页面中存在多个JVxeTable实例的时候，如果要获取每个实例的值、判断表单验证是否通过，就会让代码变得极其冗余、繁琐，于是我们就将该操作封装成了一个函数供你调用，它可以同时获取并验证多个JVxeTable实例的值，只有当所有实例的表单验证都通过后才会返回值，否则将会告诉你具体哪个实例没有通过验证。具体使用方法请看下面的示例 * `参数`： - `cases`：array，传入一个数组，数组中的每项都是一个JVxeTable的实例 - `autoJumpTab` boolean，默认true，校验失败后，是否自动跳转tab选项仅限于在ATab组件下使用的情况，如果没有就可以无视该参数 * `返回值`：Promise<tablesData[]> 返回表格数据数组，与传入的顺序一一对应 * `示例：` ``` js import { validateTables, VALIDATE_FAILED } from '@/components/jeecg/JVxeTable/utils/vxeUtils.js' // 封装cases let cases = [] cases.push(this.$refs.editableTable1) cases.push(this.$refs.editableTable2) cases.push(this.$refs.editableTable3) cases.push(this.$refs.editableTable4) cases.push(this.$refs.editableTable5) // 同时验证并获取多个实例的值 validateTables(cases).then(tablesData => { // tablesData 是一个数组，每项都对应传入cases的下标，包含values和deleteIds console.log('所有实例的值：', tablesData) }).catch((e = {}) => { // 判断表单验证是否未通过 if (e.error === VALIDATE_FAILED) { console.log('未通过验证的实例下标:', e.index) } else { console.error('发生异常:', e) } }) ``` #### validateFormAndTables * `说明`：同时验证AFrom实例和多个JVxeTable实例和`validateTables`功能相同，只不过该方法进一步验证了AForm实例。 * `参数`： - `form`：AForm实例 - `cases`：array，传入一个数组，数组中的每项都是一个JVxeTable的实例 - `autoJumpTab` boolean，默认true，校验失败后，是否自动跳转tab选项 * `返回值`：Promise<dataMap> dataMap.formValue=主表数据，dataMap.tablesValue=子表数据 ### vxePackageToSuperQuery * `说明`：vxe columns 封装成高级查询可识别的选项 * `参数`： - `columns`：array，columns - `handler`：function、单独处理方法 * `返回值`：array，高级查询所需要的`fieldList` ### getRefPromise * `说明`：获取指定的 $refs 对象有时候可能会遇到组件未挂载到页面中的情况，导致无法获取 $refs 中的某个对象这个方法可以等待挂载完成之后再返回 $refs 的对象，避免报错 * `参数`： - `vm`：vue实例 - `name`：string，ref的名称 * `返回值`：Promise，获取到的ref实例