8.1. DataSet
DataSet
(以下简称 DS
) 是我们日常使用 C7N
开发中必须使用的管理数据的方法。在一个标准的 DS
文件属性定义中,主要分为以下几个部分:
- 用于控制
DS
整体的数据配置。 - 对于每一行记录的数据配置。
- 接口请求的配置
- 事件监听的配置。
8.1.1. DS 整体数据配置
8.1.2. fields 配置
应当不应使用纯 string
类型定义 fields
中每个 filed
的 name
属性,应当使用 enum
类型。
因为该处的 name
值经常会被 record
的 set、get 方法及 Form
的字段配置中使用,过多的魔法值
会造成数据使用的不清晰。因此应当使用 enum
类型定义,便于被引用的同时又能作为 TS 类型
使用。并且 name
字段经常与后端接口返回字段对应,这样也避免了如果后端接口返回的数据中,字段名称后期发生修改,只需修改 enum
定义的值即可,而不需要处处在使用的地方进行修改。
所谓魔法值
,是指代码中未经过定义直接出现的变量,变量意义必须通过阅读其他代码才能推断出来,这样给后期维护或者其他人员阅读代码,带来了极大不便。在日常开发中应当尽可能避免使用 魔法值
。
import {DataSetProps} from "choerodon-ui/pro/lib/data-set/DataSet";
import {FieldType} from "choerodon-ui/dataset/data-set/enum";
export enum FN {
NAME = 'name', // 姓名
}
const demoDS = (): DataSetProps => ({
fields: [
// 应当这样做!
{
name: FN.NAME,
type: FieldType.string,
},
// 不要这样做!
{
name: 'name',
type: FieldType.string,
},
],
// ......
});
对于 name
的 enum
的定义应当使用统一的命名,如 FieldNames
或使用简称 FN
。
如果一个文件同时导入的 2个
以上的 DS
,应当使用别名的方式,如 import { FN as DemoFN } from './demoDS';
,命名规范遵循帕斯卡命名法。单文件同时存在 2个以上文件内 DS
,命名方式同理。
8.1.3. events 配置
为 DS
添加 event
主要有 3 种方式:
- 通过
DS
上的addEventListener
方法。 - 使用
useDataSetEvents
。 - 在
DS
配置时写上events
属性。
使用 addEventListener
为 DS
添加事件监听时,在组件销毁阶段必须添加 removeEventListener
,销毁监听。
如果把 DS
配置文件写在组件中时,对于复杂逻辑处理的监听应当使用 useDataSetEvents
进行添加。
为什么?
生成一个 DS
实例必须使用 useMemo
以避免被重复创建,因此在创建时 DS
属性内部拿到的外部的值会存在闭包问题。使用 useDataSetEvents
去做监听则不存在该问题。
8.1.4. Record 类型引入规范
应当record 是 DataSet 数据源中存储的记录。类型定义在 choerodon-ui/pro/lib/data-set/Record
中。
由于 TS 默认工具函数中存在 Record
工具函数,为了避免两者理解上冲突,因此在使用时应当使用 C7NRecord
来引入。
import Record from 'choerodon-ui/pro/lib/data-set/Record';
import C7NRecord from 'choerodon-ui/pro/lib/data-set/Record';