內容摘要:
- 需求分析
- 定義 interface
- 定義 json 檔案
- 定義列表控制元件的 props
- 基於 el-table 封裝,實現依賴 json 渲染
- 實現內建功能:選擇行(單選、多選),格式化、鎖定等。
- 使用 slot 實現自定義擴充套件
- 做個工具維護 json 檔案(下篇介紹)
管理後臺裡面,列表是一個常用的功能,UI庫提供了列表元件和分頁元件實現功能。雖然功能強大,也很靈活,只是還不能稱為低程式碼,不過沒關係,我們可以寫點程式碼讓UI庫變為摸魚神器!
本篇介紹列表的設計思路和封裝方式。
需求分析
如果基於原生HTML來實現顯示資料列表的功能的話,那麼需考慮如何建立 table,如何設定css等。
如果直接使用UI庫的話,那麼可以簡單很多,只需要設定各種屬性,然後繫結資料即可。
以 el-table 為例:
<el-table
:data="tableData"
border
stripe
style="width: 100%"
>
<el-table-column prop="date" label="Date" width="180" />
<el-table-column prop="name" label="Name" width="180" />
<el-table-column prop="address" label="Address" />
</el-table>
設定好屬性、記錄集合,然後設定列(el-table-column)即可。
這樣一個列表就搞定了,再加上 el-pagination 分頁元件,編寫一些程式碼即可實現分頁的功能。
如果只是一個列表的話,這種方式沒啥問題,但是管理後臺專案,往往需要n個列表,而每個列表都大同小異,如果要一個一個手擼出來,那就有點麻煩了。
那麼如何解決呢?我們可以參考低程式碼,基於 el-talbe 封裝一個列表控制元件,
實現依賴 json 動態渲染列表,同時支援自定義擴充套件。
定義 interface
最近開始學習 Typescript,發現了一個現象,如果可以先定義好型別,那麼程式碼就可以更清晰的展現出來。
另外 Vue3 的最新文件,也採用了通過 interface 來介紹API功能的方式,所以我們也可以借鑑一下。
依據 el-table 的屬性,定義列表控制元件屬性的 interface。
Vue3 的 props 有一套約束方式,這個似乎和TS的方式有點衝突,沒想出了更好的方法(option API 和 script setup兩種定義props的方式,都有不足 ),所以只好做兩個 interface,一個用於定義元件的 props ,一個用於取值。
- IGridPropsComp:定義元件的 props
/**
* 列表控制元件的屬性的描述,基於el-table
*/
export interface IGridPropsComp {
/**
* 模組ID,number | string
*/
moduleId: IPropsValidation,
/**
* 主鍵欄位的名稱 String,對應 row-key
*/
idName: IPropsValidation,
/**
* table的高度, Number
*/
height: IPropsValidation,
/**
* 列(欄位)顯示的順序 Array<number|string>
*/
colOrder: IPropsValidation,
/**
* 斑馬紋,Boolean
*/
stripe: IPropsValidation,
/**
* 縱向邊框,Boolean
*/
border: IPropsValidation,
/**
* 列的寬度是否自撐開,Boolean
*/
fit: IPropsValidation,
/**
* 要高亮當前行,Boolean
*/
highlightCurrentRow: IPropsValidation,
/**
* 鎖定的列數 Number,設定到 el-table-column 的 fixed
*/
fixedIndex: IPropsValidation,
/**
* table的列的 IGridItem
* * id: number | string,
* * colName: string, 欄位名稱
* * label: string, 列的標籤、標題
* * width: number, 列的寬度
* * align: EAlign, 內容對齊方式
* * headerAlign: EAlign 列標題對齊方式
*/
itemMeta: IPropsValidation, //
/**
* 記錄選擇的行:IGridSelection
* * dataId: '', 單選ID number 、string
* * row: {}, 單選的資料物件 {}
* * dataIds: [], 多選ID []
* * rows: [] 多選的資料物件 []
*/
selection: IPropsValidation,
/**
* 繫結的資料 Array, 對應 data
*/
dataList: IPropsValidation
// 其他擴充套件屬性
[propName: string]: IPropsValidation
}
- moduleId:模組ID,一個模組選單隻能有一個列表,選單可以巢狀。
- itemMeta:列的屬性集合,記錄列表的列的屬性。
- selection:記錄列表的單選、多選的 row。
- dataList:顯示的資料,對應 el-table 的 data
- 其他:對應 el-table 的屬性
IGridPropsComp 的作用是,約束列表控制元件需要設定哪些屬性,屬性的具體型別,就無法在這裡約束了。
- IPropsValidation (不知道vue內部有沒有這樣的 interface)
/**
* vue 的 props 的驗證的型別約束
*/
export interface IPropsValidation {
/**
* 屬性的型別,比較靈活,可以是 String、Number 等,也可以是陣列、class等
*/
type: Array<any> | any,
/**
* 是否必須傳遞屬性
*/
required?: boolean,
/**
* 自定義型別校驗函式(箭頭函式),value:屬性值
*/
validator?: (value: any) => boolean,
/**
* 預設值,可以是值,也可以是函式(箭頭函式)
*/
default?: any
}
取 props 用的 interface
IGridPropsComp 無法約束屬性的具體型別,所以只好再做一個 interface。
- IGridProps
/**
* 列表控制元件的屬性的型別,基於el-table
*/
export interface IGridProps {
/**
* 模組ID,number | string
*/
moduleId: number | string,
/**
* 主鍵欄位的名稱 String,對應 row-key
*/
idName: String,
/**
* table的高度, Number
*/
height: number,
/**
* 列(欄位)顯示的順序 Array<number|string>
*/
colOrder: Array<number|string>,
/**
* 斑馬紋,Boolean
*/
stripe: boolean,
/**
* 縱向邊框,Boolean
*/
border: boolean,
/**
* 列的寬度是否自撐開,Boolean
*/
fit: boolean,
/**
* 要高亮當前行,Boolean
*/
highlightCurrentRow: boolean,
/**
* 鎖定的列數 Number,設定到 el-table-column 的 fixed
*/
fixedIndex: number,
/**
* table的列的 Object< IGridItem >
* * id: number | string,
* * colName: string, 欄位名稱
* * label: string, 列的標籤、標題
* * width: number, 列的寬度
* * align: EAlign, 內容對齊方式
* * headerAlign: EAlign 列標題對齊方式
*/
itemMeta: {
[key:string | number]: IGridItem
}, //
/**
* 選擇行的情況:IGridSelection
* * dataId: '', 單選ID number 、string
* * row: {}, 單選的資料物件 {}
* * dataIds: [], 多選ID []
* * rows: [] 多選的資料物件 []
*/
selection: IGridSelection,
/**
* 繫結的資料 Array, 對應 data
*/
dataList: Array<any>
// 其他擴充套件屬性
[propName: string]: any
}
對比一下就會發現,屬性的型別不一樣。因為定義 props 需要使用一套特定的物件格式,而使用 props 的時候需要的是屬性自己的型別。
理想情況下,應該可以在 script setup 裡面,引入外部檔案 定義的 interface ,然後設定給元件的 props,但是到目前為止還不支援,只能在( script setup方式的)元件內部定義 props。希望早日支援,支援了就不會這麼糾結和痛苦了。
依據 el-table-column 定義列屬性的 interface。
- IGridItem:列表裡面列的屬性
/**
* 列的屬性,基於 el-table-column
*/
export interface IGridItem {
/**
* 欄位ID、列ID
*/
id: number | string,
/**
* 欄位名稱
*/
colName: string,
/**
* 列的標籤、標題
*/
label: string,
/**
* 列的寬度
*/
width: number,
/**
* 內容對齊方式 EAlign
*/
align: EAlign,
/**
* 列標題對齊方式
*/
headerAlign: EAlign,
// 其他擴充套件屬性
[propName: string]: any
}
還是需要擴充套件屬性的,因為這裡只是列出來目前需要的屬性,el-table-column 的其他屬性、方法還有很多,而且以後也可能會新增。
這個屬性不是直接設定給元件的 props,所以不用定義兩套了。
對齊方式的列舉
列舉可以理解為常量,定義之後可以避免低階錯誤,避免手滑。
- EAlign
export const enum EAlign {
left = 'left',
center = 'center',
right = 'right'
}
選擇記錄的 interface。
列表可以單選也可以多選,el-table 在預設情況下似乎是二選一,覺得有點不方便,為啥不能都要?
- 單選:滑鼠單一任意一行就是單選;(清空其他已選項)
- 多選:單擊第一列的(多個)核取方塊,就是多選;
這樣使用者就可以愉快的想單選就單選,想多選就多選了。
- IGridSelection
/**
* 列表裡選擇的資料
*/
export interface IGridSelection {
/**
* 單選ID number 、string
*/
dataId: number | string,
/**
* 單選的資料物件 {}
*/
row: any,
/**
* 多選ID []
*/
dataIds: Array<number | string>,
/**
* 多選的資料物件 []
*/
rows: Array<any>
}
其實我覺得只記錄ID即可,不過既然 el-talble 提供的 row,那麼還是都記錄下來吧。
定義 json 檔案
介面定義好之後,我們可以依據 interface 編寫 json 檔案:
{
"moduleId": 142,
"height": 400,
"idName": "ID",
"colOrder": [
90, 100, 101
],
"stripe": true,
"border": true,
"fit": true,
"highlightCurrentRow": true,
"highlight-current-row": true,
"itemMeta": {
"90": {
"id": 90,
"colName": "kind",
"label": "分類",
"width": 140,
"title": "分類",
"align": "center",
"header-align": "center"
},
"100": {
"id": 100,
"colName": "area",
"label": "多行文字",
"width": 140,
"title": "多行文字",
"align": "center",
"header-align": "center"
},
"101": {
"id": 101,
"colName": "text",
"label": "文字",
"width": 140,
"title": "文字",
"align": "center",
"header-align": "center"
}
}
}
-
為什麼直接設定 json 檔案而不是 js 物件呢?
因為物件會比較長,如果是程式碼形式的話,那還不如直接使用UI庫元件來的方便呢。 -
你可能又會問了,既然直接用 json檔案,為啥還要設計 interface 呢?
當然是為了明確各種型別,interface 可以當做文件使用,另外封裝UI庫的元件的時候,也可以用到這些 interface。使用列表控制元件的時候也可以使用這些 interface。
其實json檔案不用手動編寫,而是通過工具來編寫和維護。
定義列表控制元件的 props
封裝元件之前需要先定義一下元件需要的 props:
- props-grid.ts
import type { PropType } from 'vue'
import type {
IGridProps,
IGridItem,
IGridSelection
} from '../types/50-grid'
/**
* 表單控制元件需要的屬性propsForm
*/
export const gridProps: IGridProps = {
/**
* 模組ID,number | string
*/
moduleId: {
type: Number,
required: true
},
/**
* 主鍵欄位的名稱
*/
idName: {
type: String,
default: 'ID'
},
/**
* 欄位顯示的順序
*/
colOrder: {
type: Array as PropType<Array<number | string>>,
default: () => []
},
/**
* 鎖定的列數
*/
fixedIndex: {
type: Number,
default: 0
},
/**
* table的列的 meta
*/
itemMeta: {
type: Object as PropType<{
[key:string | number]: IGridItem
}>
},
/**
* 選擇的情況 IGridSelection
*/
selection: {
type: Object as PropType<IGridSelection>,
default: () => {
return {
dataId: '', // 單選ID number 、string
row: {}, // 單選的資料物件 {}
dataIds: [], // 多選ID []
rows: [] // 多選的資料物件 []
}
}
},
/**
* 繫結的資料
*/
dataList: {
type: Array as PropType<Array<any>>,
default: () => []
},
其他略。。。
}
按照 Option API 的方式設定 props 的定義,這樣便於共用屬性的定義(好吧似乎也沒有需要共用的地方,不過我還是喜歡把 props 的定義寫在一個單獨的檔案裡)。
封裝列表控制元件
定義好 json 、props之後,我們基於 el-table 封裝列表控制元件:
- template 模板
<el-table
ref="gridRef"
v-bind="$attrs"
:data="dataList"
:height="height"
:stripe="stripe"
:border="border"
:fit="fit"
:highlight-current-row="highlightCurrentRow"
:row-key="idName"
@selection-change="selectionChange"
@current-change="currentChange"
>
<!--多選框,實現多選功能-->
<el-table-column
type="selection"
width="55"
align="center"
header-align="center"
@click="clickCheck"
>
</el-table-column>
<!--依據 json 渲染的欄位列表-->
<el-table-column
v-for="(id, index) in colOrder"
:key="'grid_list_' + index + '_' + id"
v-bind="itemMeta[id]"
:column-key="'col_' + id"
:fixed="index < fixedIndex"
:prop="itemMeta[id].colName"
>
</el-table-column>
</el-table>
設定 type="selection"
列,實現多選的功能。
使用 v-for 的方式,遍歷出動態列。
設定 :fixed="index < fixedIndex"
,實現鎖定左面列的功能。
- js 程式碼
import { defineComponent, ref } from 'vue'
// 列表控制元件的屬性
import { gridProps } from '../map'
/**
* 普通列表控制元件
*/
export default defineComponent({
name: 'nf-elp-grid-list',
inheritAttrs: false,
props: {
...gridProps // 解構共用屬性
},
setup (props, ctx) {
// 獲取 el-table
const gridRef = ref(null)
return {
gridRef
}
}
})
把 props 的定義放在單獨的 ts檔案 裡面,元件內部的程式碼就可以簡潔很多。
實現內建功能
可以按照自己的喜好,設定一些內部功能,比如單選/多選的功能,格式化的功能等。
- 定義控制函式 controller.ts
import type { ElTable } from 'element-plus'
// 列表控制元件的屬性
import type { IGridProps } from '../map'
export interface IRow {
[key: string | number]: any
}
/**
* 列表的單選和多選的事件
* @param props 列表元件的 props
* @param gridRef el-table 的 $ref
*/
export default function choiceManage<T extends IGridProps, V extends typeof ElTable>(props: T, gridRef: V) {
// 是否單選觸發
let isCurrenting = false
// 是否多選觸發
let isMoring = false
// 單選
const currentChange = (row: IRow) => {
if (isMoring) return // 多選程式碼觸發
if (!row) return // 清空
if (gridRef.value) {
isCurrenting = true
gridRef.value.clearSelection() // 清空多選
gridRef.value.toggleRowSelection(row) // 設定核取方塊
gridRef.value.setCurrentRow(row) // 設定單選
// 記錄
props.selection.dataId = row[props.idName]
props.selection.dataIds = [ row[props.idName] ]
props.selection.row = row
props.selection.rows = [ row ]
isCurrenting = false
}
}
// 多選
const selectionChange = (rows: Array<IRow>) => {
if (isCurrenting) return
// 記錄
if (typeof props.selection.dataIds === 'undefined') {
props.selection.dataIds = []
}
props.selection.dataIds.length = 0 // 清空
// 設定多選
rows.forEach((item: IRow) => {
if (typeof item !== 'undefined' && item !== null) {
props.selection.dataIds.push(item[props.idName])
}
})
props.selection.rows = rows
// 設定單選
switch (rows.length) {
case 0:
// 清掉單選
gridRef.value.setCurrentRow()
props.selection.dataId = ''
props.selection.row = {}
break
case 1:
isMoring = true
// 設定新單選
gridRef.value.setCurrentRow(rows[0])
isMoring = false
props.selection.row = rows[0]
props.selection.dataId = rows[0][props.idName]
break
default:
// 去掉單選
gridRef.value.setCurrentRow()
props.selection.row = rows[rows.length - 1]
props.selection.dataId = props.selection.row[props.idName]
}
}
return {
currentChange, // 單選
selectionChange // 多選
}
}
- 列表控制元件的 setup 裡呼叫
setup (props, ctx) {
// 獲取 el-table
const gridRef = ref<InstanceType<typeof ElTable>>()
// 列表選項的事件
const {
currentChange, // 單選
selectionChange // 多選
} = choiceManage(props, gridRef)
return {
selectionChange, // 多選
currentChange, // 單選
gridRef // table 的 dom
}
}
這裡有一個“度”的問題:
-
el-table 完全通過 slot 的方式實現各種功能,這種方法的特點是:非常靈活,可以各種組合;缺點是比較繁瑣。
而我們需要尋找到一個適合的“折中點”,顯然這個折中點很難統一,這也是過渡封裝帶來的問題。 -
不能遇到新的需求,就增加內部功能,這樣就陷入了《人月神話》裡說的“焦油坑”,進去了就很難出來。
這也是低程式碼被詬病的因素。
支援擴充套件
那麼如何找到這個折中點呢?可以按照 “開閉原則”,按照不同的需求,設定多個不同功能的列表控制元件,使用 slot 實現擴充套件功能。或者乾脆改為直接使用 el-table 的方式。(要靈活,不要一刀切)
比如簡單需求,不需要擴充套件功能的情況,設定一個基礎列表控制元件:nf-grid。
需要擴充套件列的情況,設定一個可以擴充套件的列表控制元件:nf-grid-slot。
如果需要多表頭、樹形資料等需求,可以設定一個新的列表控制元件,不過需要先想想,是不是直接用 el-table 更方便。
要不要新增一個控制元件,不要慣性思維,而要多方面全域性考慮。
這裡介紹一下支援 slot 擴充套件的列表控制元件的封裝方式:
<el-table
ref="gridDom"
v-bind="$attrs"
size="mini"
style="width: 100%"
:data="dataList"
:height="height"
:stripe="stripe"
:border="border"
:fit="fit"
:highlight-current-row="highlightCurrentRow"
:current-row-key="idName"
:row-key="idName"
@selection-change="selectionChange"
@current-change="currentChange"
>
<!--顯示選擇框-->
<el-table-column
type="selection"
width="55">
</el-table-column>
<!--顯示欄位列表-->
<template
v-for="(id, index) in colOrder"
:key="'grid_list_' + index + '_' + id"
>
<!--檢查插槽裡是否包含 欄位名,作為判斷依據-->
<!--不帶插槽的列-->
<el-table-column
v-if="!(slotsKey.includes(itemMeta[id].colName))"
:fixed="index < fixedIndex"
v-bind="itemMeta[id]"
:prop="itemMeta[id].colName"
:min-width="50"
>
</el-table-column>
<!--帶插槽的列-->
<el-table-column v-else
v-bind="itemMeta[id]"
>
<template #default="scope">
<!--讀取外部插槽內容,並且傳遞 scope -->
<slot :name="itemMeta[id].colName" v-bind="scope"></slot>
</template>
</el-table-column>
</template>
</el-table>
模板部分,首先判斷一下是否需要使用 slot,做一個分支。
需要使用 slot 的列,通過 <template #default="scope">
設定 slot。
- 程式碼部分
import { defineComponent, ref } from 'vue'
// 表單控制元件的屬性
import { gridProps } from '../map'
import choiceManage from './controller'
export default defineComponent({
name: 'nf-elp-grid-slot',
inheritAttrs: false,
props: {
...gridProps
},
setup (props, ctx) {
// 記錄插槽 的 名稱
const slots = ctx.slots
const slotsKey = Object.keys(slots)
// 列表選項的事件
const {
currentChange, // 單選
selectionChange // 多選
} = choiceManage(props, gridRef)
return {
slotsKey,
selectionChange, // 多選
currentChange // 單選
}
}
})
一般列表的使用方法
封裝之後,使用起來就很方便了,引入 json檔案,設定屬性即可。
- template
<nf-grid
v-bind="gridMeta"
:dataList="dataList"
:selection="selection"
size="small"
/>
是不是簡單多了。
- 程式碼部分
import { defineComponent, reactive } from 'vue'
import { nfGrid, createDataList } from '../../../../lib-elp/main'
import _gridMeta from '../../grid/grid.json'
import _formMeta from '../../form/form.json'
export default defineComponent({
name: 'nf-elp-grid-page',
components: { nfGrid },
setup(props) {
// 不需要動態改變的話,可以不使用 reactive。
const gridMeta = reactive(_gridMeta)
// 設定選擇的行
const selection = reactive({
dataId: '', // 單選ID number 、string
row: {}, // 單選的資料物件 {}
dataIds: [], // 多選ID []
rows: [] // 多選的資料物件 []
})
// 設定記錄集。
const dataList = reactive(_dataList)
return {
dataList,
selection,
gridMeta
}
}
})
控制元件可以做成全域性元件的形式。
- 看看效果
擴充套件列表的使用方法
首先還是依據 json 渲染列表,然後根據需要設定插槽即可,設定插槽後會替換預設的列。
- template
可以使用 slot 自定義擴充套件列 <br>
<!--表單控制元件-->
<nf-grid
v-grid-drag="gridMeta"
v-bind="gridMeta"
:dataList="dataList"
:selection="selection"
size="small"
>
<!--普通欄位,用欄位名作為插槽的名稱-->
<template #text="scope">
<div style="display: flex; align-items: center">
<el-icon><timer /></el-icon>
<span style="margin-left: 10px">擴充套件:{{ scope.row.text }}</span>
</div>
</template>
<!--普通欄位-->
<template #week="scope">
<span style="margin-left: 10px">{{ scope.row.week.replace('-w','年 第') + '周' }}</span>
</template>
<!--操作按鈕-->
<template #option="scope">
<el-button size="small" @click="handleEdit(scope.$index, scope.row)">修改</el-button>
<el-button
size="small"
type="danger"
@click="handleDelete(scope.$index, scope.row)">刪除</el-button>
</template>
</nf-grid>
通過 slot 擴充套件列,可以按照 Table-column 的匿名插槽的方式進行設定。
列的先後順序還是由 colOrder 控制,和插槽的先後順序無關。
- 程式碼部分
import { defineComponent, reactive } from 'vue'
// 使用 圖示
import { Timer } from '@element-plus/icons-vue'
import { nfGridSlot, createDataList } from '../../../../lib-elp/main'
import _gridMeta from '../../grid/grid.json'
import _formMeta from '../../form/form.json'
import { EAlign } from '../../../../lib/types/enum'
import type { IGridSelection, IGridItem } from '../../../../lib/types/50-grid'
export default defineComponent({
name: 'nf-elp-grid-slot-page',
components: {
Timer,
nfGrid: nfGridSlot
},
props: {
moduleID: { // 模組ID
type: [Number, String],
default: 1
}
},
setup(props) {
const gridMeta = reactive(_gridMeta)
// 設定列的先後順序和是否顯示
gridMeta.colOrder = [90, 100, 101, 102, 105, 113, 115, 116, 120,121,150, 2000]
// 設定一個操作按鈕列
const optionCol: IGridItem = {
id: 2000,
colName: "option",
label: "操作",
width: 180,
fixed: EAlign.right,
align: EAlign.center, // 使用列舉
headerAlign: EAlign.center
}
gridMeta.itemMeta['2000'] = optionCol // 設定操作列,也可以直接在json檔案裡設定。
const dataList = reactive(_dataList)
const handleEdit = (index: number, row: any) => {
console.log(index, row)
}
const handleDelete = (index: number, row: any) => {
console.log(index, row)
}
return {
handleEdit,
handleDelete,
dataList,
gridMeta
}
}
})
使用欄位名稱作為插槽的名稱,可以把任意欄位變成插槽的形式。
如果要新增操作按鈕這類的列,可以給 itemMeta 新增對應的列屬性。
- 看看效果:
管理 json
其實,前面介紹的那些大家可能都會想到,也許早就實踐過了,然後發現雖然看著挺好,但是其實沒有解決根本問題!只是把 template 裡的問題轉移到 json 裡面。
雖然不需要設定模板,但是需要設定 json,還不是一樣,有啥本質區別嗎?
其實不一樣的,管理 json 的難度明顯比管理模板要簡單得多。
比如我們可以做一個維護 json 的小工具:
- 首先從資料庫文件生成基礎的 json(毛坯房);
- 然後使用視覺化+拖拽的方式設定格子細節(精裝修)。
這樣就可以很方便的維護 json 了。具體實現方式,將在下一篇再介紹。