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實例