管理后台里面,列表是一个常用的功能,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 动态渲染列表,同时支持自定义扩展。
最近开始学习 Typescript,发现了一个现象,如果可以先定义好类型,那么代码就可以更清晰的展现出来。
另外 Vue3 的最新文档,也采用了通过 interface 来介绍API功能的方式,所以我们也可以借鉴一下。
Vue3 的 props 有一套约束方式,这个似乎和TS的方式有点冲突,没想出了更好的方法(option API 和 script setup两种定义props的方式,都有不足 ),所以只好做两个 interface,一个用于定义组件的 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
}
IGridPropsComp 的作用是,约束列表控件需要设置哪些属性,属性的具体类型,就无法在这里约束了。
/**
* vue 的 props 的验证的类型约束
*/
export interface IPropsValidation {
/**
* 属性的类型,比较灵活,可以是 String、Number 等,也可以是数组、class等
*/
type: Array<any> | any,
/**
* 是否必须传递属性
*/
required?: boolean,
/**
* 自定义类型校验函数(箭头函数),value:属性值
*/
validator?: (value: any) => boolean,
/**
* 默认值,可以是值,也可以是函数(箭头函数)
*/
default?: any
}
IGridPropsComp 无法约束属性的具体类型,所以只好再做一个 interface。
/**
* 列表控件的属性的类型,基于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
*/
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,所以不用定义两套了。
枚举可以理解为常量,定义之后可以避免低级错误,避免手滑。
export const enum EAlign {
left = 'left',
center = 'center',
right = 'right'
}
列表可以单选也可以多选,el-table 在默认情况下似乎是二选一,觉得有点不方便,为啥不能都要?
这样用户就可以愉快的想单选就单选,想多选就多选了。
/**
* 列表里选择的数据
*/
export interface IGridSelection {
/**
* 单选ID number 、string
*/
dataId: number | string,
/**
* 单选的数据对象 {}
*/
row: any,
/**
* 多选ID []
*/
dataIds: Array<number | string>,
/**
* 多选的数据对象 []
*/
rows: Array<any>
}
其实我觉得只记录ID即可,不过既然 el-talble 提供的 row,那么还是都记录下来吧。
接口定义好之后,我们可以依据 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文件不用手动编写,而是通过工具来编写和维护。
封装组件之前需要先定义一下组件需要的 props:
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 封装列表控件:
<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"
,实现锁定左面列的功能。
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文件 里面,组件内部的代码就可以简洁很多。
可以按照自己的喜好,设置一些内部功能,比如单选/多选的功能,格式化的功能等。
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 (props, ctx) {
// 获取 el-table
const gridRef = ref<InstanceType<typeof ElTable>>()
// 列表选项的事件
const {
currentChange, // 单选
selectionChange // 多选
} = choiceManage(props, gridRef)
return {
selectionChange, // 多选
currentChange, // 单选
gridRef // table 的 dom
}
}
这也是低代码被诟病的因素。
那么如何找到这个折中点呢?可以按照 “开闭原则”,按照不同的需求,设置多个不同功能的列表控件,使用 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文件,设置属性即可。
<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 渲染列表,然后根据需要设置插槽即可,设置插槽后会替换默认的列。
可以使用 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 添加对应的列属性。
其实,前面介绍的那些大家可能都会想到,也许早就实践过了,然后发现虽然看着挺好,但是其实没有解决根本问题!只是把 template 里的问题转移到 json 里面。
虽然不需要设置模板,但是需要设置 json,还不是一样,有啥本质区别吗?
其实不一样的,管理 json 的难度明显比管理模板要简单得多。
比如我们可以做一个维护 json 的小工具:
这样就可以很方便的维护 json 了。具体实现方式,将在下一篇再介绍。