【摸魚神器】UI庫秒變LowCode工具——列表篇（一）設計與實現
2022-06-06 15:07:15
內容摘要：
- 需求分析
- 定義 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 了。具體實現方式，將在下一篇再介紹。
原始碼
https://gitee.com/naturefw-code/nf-rollup-ui-controller
https://gitee.com/naturefw-code/nf-rollup-ui-element-plus