自然框架
自然框架

【摸鱼神器】UI库秒变LowCode工具——列表篇（一）设计与实现

内容摘要：

  • 需求分析
  • 定义 interface
  • 定义 json 文件
  • 定义列表控件的 props
  • 基于 el-table 封装，实现依赖 json 渲染
  • 实现内置功能：选择行（单选、多选），格式化、锁定等。
  • 使用 slot 实现自定义扩展
  • 做个工具维护 json 文件（下篇介绍）

管理后台里面，列表是一个常用的功能，UI库提供了列表组件和分页组件实现功能。虽然功能强大，也很灵活，只是还不能称为低代码，不过没关系，我们可以写点代码让UI库变为摸鱼神器！

本篇介绍列表的设计思路和封装方式。

需求分析

如果基于原生HTML来实现显示数据列表的功能的话，那么需考虑如何创建 table，如何设置css等。
如果直接使用UI库的话，那么可以简单很多，只需要设置各种属性，然后绑定数据即可。
以 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
   */
  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,
  /**
   * 是否必须传递属性
   */
  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
   */
  colOrder: Array,
  /**
   * 斑马纹，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

  // 其他扩展属性
  [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,
  /**
   * 多选的数据对象 []
   */
  rows: Array
}

其实我觉得只记录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>,
    default: () => []
  },
  /**
   * 锁定的列数
   */
  fixedIndex: {
    type: Number,
    default: 0
  },
  /**
   * table的列的 meta
   */
  itemMeta: {
    type: Object as PropType<{
      [key:string | number]: IGridItem
    }>
  },
  /**
   * 选择的情况 IGridSelection
   */
  selection: {
    type: Object as PropType,
    default: () => {
      return {
        dataId: '', // 单选ID number 、string
        row: {}, // 单选的数据对象 {}
        dataIds: [], // 多选ID []
        rows: [] // 多选的数据对象 []
      }
    }
  },
  /**
   * 绑定的数据
   */
  dataList: {
    type: Array as PropType>,
    default: () => []
  },
  其他略。。。
}

按照 Option API 的方式设置 props 的定义，这样便于共用属性的定义（好吧似乎也没有需要共用的地方，不过我还是喜欢把 props 的定义写在一个单独的文件里）。

封装列表控件

定义好 json 、props之后，我们基于 el-table 封装列表控件：

  • template 模板

设置 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(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) => {
   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>()

  // 列表选项的事件
  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 扩展的列表控件的封装方式：

模板部分，首先判断一下是否需要使用 slot，做一个分支。
需要使用 slot 的列，通过