DataSet

数据源。

注意事项

DataSet 内部会将普通数据对象转成可观察对象,单次 loadData | create 加载超过 1000+ 或遍历创建 record 时会有明显耗时,在对性能有严格要求的项目建议采取其他方案处理大数据量。 初次使用该组件库建议阅读引导教程

API

DataSet Props

参数说明类型默认值
name对应后台 ds 的 name,自动生成约定的 submitUrl, queryUrl, tlsUrl, validateUrlArray<string>
data初始化数据Array<object>
autoQuery初始化后自动查询booleanfalse
autoQueryAfterSubmit提交成功后响应的数据不符合回写条件时自动查询。注:回写条件是指响应数据中含有提交时的数据时,数据将按数据状态分组进行顺序回写,如果要更准确的回写,响应数据要含有提交时的__id 字段值。booleantrue
autoCreate初始化时,如果没有记录且 autoQuery 为 false,则自动创建记录booleanfalse
autoLocateFirst数据加载后自动定位到第一条记录booleantrue
autoLocateAfterCreate自动定位到新建记录booleantrue
autoLocateAfterRemove当前数据被删除后自动定位到其他记录booleantrue
validateBeforeQuery查询时是否校验查询字段或查询数据集booleantrue
selection选择的模式, 可选值: false ‘multiple’ ‘single’boolean | stringmultiple
modifiedCheck查询前,当有记录更改过时,是否警告提示。booleantrue
modifiedCheckMessage查询前,当有记录更改过时,警告提示。ReactNode | ModalProps
pageSize分页大小number10
paging是否分页,server 主要为 Table 的 Tree 模式服务,约定 total 为根节点数目,index 的定位都是基于根节点,为 server 时候保证同时存在 idField 和 parentField (根节点为空或者 undefined) 不然表现和原有版本一致boolean | ‘server’true
dataKey查询返回的 json 中对应的数据的 key, 当为 null 时对应整个 json 数据, json 不是数组时自动作为新数组的第一条数据string | nullrows
totalKey查询返回的 json 中对应的总数的 keystringtotal
queryDataSet查询条件数据源DataSet
queryUrl查询请求的 url。 当设定 name 时,默认 /dataset/{name}/queriesstring
queryParameter查询请求的初始参数object
submitUrl记录提交请求的 url。 当设定 name 时,默认 /dataset/{name}/mutationsstring
tlsUrl多语言查询请求的 url。 当设定 name 时, 默认 /dataset/{name}/languagesstring
validateUrl远程校验查询请求的 url。 当设定 name 时, 默认 /dataset/{name}/validatestring
exportUrl导出请求的 url。 当设定 name 时, 默认 /dataset/{name}/exportstring
transport自定义 CRUD 请求配置, 详见TransportAxiosRequestConfigTransport
feedback查询和提交数据的反馈配置, 详见FeedbackFeedback
children级联行数据集, 例: { name1: dataSet1, name2: dataSet2 }{ name: DataSet }
primaryKey主键字段名,一般用作级联行表的查询字段string
idField树形数据当前节点 id 字段名string
parentField树形数据当前父节点 id 字段名string
expandField树形数据标记节点是否展开的字段名string
checkField树形数据标记节点是否为选中的字段名,在展开按钮后面会显示 checkboxstring
fields字段属性数组,详见Field Propsobject[]
queryFields查询字段属性数组,在内部生成 queryDataSet,优先级低于 queryDataSet 属性,详见Field Propsobject[]
cacheSelection缓存选中记录,使切换分页时仍保留选中状态。当设置了 primaryKey 或有字段设置了 unique 才起作用。booleanfalse
axios覆盖默认 axiosAxiosInstance
dataToJSON数据转为 json 的方式,详见DataToJSONDataToJSONdirty
cascadeParams级联查询参数(record, primaryKey) => object(record, primaryKey) => primaryKey ? record.get(primaryKey) : record.toData()
exportMode导出模式选择:前端导出,后端导出client | serverclient

DataSet Values

名称说明类型
current获取或者设置当前记录observable<Record>
currentPage当前页码readonly observable<number>
currentIndex当前游标索引observable<number>
totalCount总记录数observable<number>
totalPage总页数readonly observable<number>
pageSize分页大小observable<number>
paging是否分页observable<boolean>
status状态,loading submitting readyobservable<string>
selection选择的模式, 可选值: false ‘multiple’ ‘single’observable<string|boolean>
records所有记录observable<Record[]>
all所有记录, 包括缓存的选择记录observable<Record[]>
data数据, 不包括删除状态的 Recordobservable<Record[]>
created新建的数据readonly observable<Record[]>
updated更新的数据readonly observable<Record[]>
destroyed暂时销毁的数据readonly observable<Record[]>
selected选中记录,包括缓存的选中记录readonly observable<Record[]>
currentSelected当前页选中记录readonly observable<Record[]>
cachedSelected缓存的选中记录readonly observable<Record[]>
length数据量readonly observable<number>
queryDataSet查询数据源observable<DataSet>
parent级联头数据源readonly observable<DataSet>
children所有级联行数据源readonly [key:string]: DataSet}
dirty含有状态不是 sync 的记录及 dirty 为 true 的记录readonly observable<boolean>}

DataSet Methods

名称说明参数返回值类型
ready()判断数据源是否准备就绪Promise
query(page, params)查询page<optional,default:1> - 指定页码 params<optional> - 临时查询参数Promise<any>
submit()将数据集中的增删改的记录先进行校验再进行远程提交。submit 会抛出请求的异常,请用 promise.catch 或 try-await-catch 来处理异常。Promise<any> false - 校验失败,undefined - 无数据提交或提交相关配置不全,如没有 submitUrl。
reset()重置更改, 并清除校验状态
locate(index)定位到指定记录, 如果pagingtrueserver,则做远程查询 为server指代的是根节点节点的index坐标index - 记录索引Promise<Record>
page(page)定位到指定页码,如果pagingtrueserver,则做远程查询page - 页码Promise<any>
first()定位到第一条记录,如果pagingtrueserver,则做远程查询 为server指代的第一个根节点Promise<Record>
last()定位到最后一条记录,如果pagingtrueserver,则做远程查询 为server指代的是最后的根节点Promise<Record>
pre()定位到上一条记录,如果pagingtrueserver,则做远程查询 为server指代的当前根节点的上一个根节点Promise<Record>
next()定位到下一条记录,如果pagingtrueserver,则做远程查询 为server指代的当前根节点的下一个根节点Promise<Record>
firstPage()定位到第一页,如果pagingtrueserver,则做远程查询Promise<any>
lastPage()定位到最后一页,如果pagingtrueserver,则做远程查询Promise<any>
prePage()定位到上一页,如果pagingtrueserver,则做远程查询Promise<any>
nextPage()定位到下一页,如果pagingtrueserver,则做远程查询Promise<any>
create(data, index)创建一条记录data - 记录数据对象;index<optional,default:0> - 记录所在的索引Record
delete(records, confirmMessage: ReactNode | ModalProps)立即删除记录records - 删除的记录或记录组 confirmMessage - 自定义提示信息或弹窗的属性, 设为false时不弹确认直接删除
remove(records)临时删除记录records - 删除的记录或记录组
deleteAll(confirmMessage: ReactNode | ModalProps)立即删除所有记录confirmMessage - 自定义提示信息或弹窗的属性, 设为false时不弹确认直接删除
removeAll()临时删除所有记录
push(…records)将若干数据记录插入记录堆栈顶部records - 插入的记录列表number
unshift(…records)将若干数据记录插入记录堆栈底部records - 插入的记录列表number
pop()从记录堆栈顶部获取记录Record
shift()从记录堆栈底部获取记录Record
splice(from, deleteCount, …records)删除指定索引的若干记录,并可插入若干新记录from<optional,default:0> - 索引开始的位置;deleteCount<optional,default:0> - 删除的数量; records - 插入的若干新记录Record[]
slice(start, end)截取指定索引范围的记录集,不改变原记录堆栈start<optional,default:0> - 开始索引;end<optional,default:记录堆栈长度> - 结束索引Record[]
find(fn)根据函数查找并返回第一条记录fn - 查询函数(record, index, array) => booleanRecord
findIndex(fn)根据函数查找记录所在的索引fn - 查询函数(record, index, array) => booleannumber
forEach(fn, thisArg)根据函数遍历fn - 遍历函数(record, index, array) => void
map(fn, thisArg)根据函数遍历并输出新数组fn - 遍历函数(record, index, array) => anyany[]
some(fn, thisArg)根据函数遍历,当有返回值为 true 时,输出 truefn - 遍历函数(record, index, array) => booleanboolean
every(fn, thisArg)根据函数遍历,当有返回值为 false 时,输出 falsefn - 遍历函数(record, index, array) => booleanboolean
filter(fn, thisArg)根据函数过滤并返回记录集fn - 过滤函数(record, index, array) => booleanRecord[]
reduce(fn, initialValue)为数组中的所有元素调用指定的回调函数。 回调函数的返回值是累计结果,并在下次调用回调函数时作为参数提供fn - 过滤函数(previousValue, record, index, array) => value initialValue - 初始值typeof initialValue
reduceRight(fn, initialValue)按降序调用数组中所有元素的指定回调函数。 回调函数的返回值是累计结果,并在下次调用回调函数时作为参数提供fn - 过滤函数(previousValue, record, index, array) => value initialValue - 初始值typeof initialValue
indexOf(record, fromIndex)获取记录所在索引record - 记录;fromIndex<optional> - 开始检索的索引number
reverse()反转记录的顺序Record[]
select(record)选中记录record - 记录对象或记录的索引
unSelect(record)取消选中记录record - 记录对象或记录的索引
selectAll()全选当前页
unSelectAll()取消全选当前页
clearCachedSelected()清除缓存的选中记录
get(index)获取指定索引的记录index - 记录索引Record
getFromTree(index)从树形数据中获取指定索引的根节点记录index - 记录索引Record
validate()校验数据记录是否有效Promise<boolean>
getField(fieldName)根据字段名获取字段fieldName - 字段名Field
addField(fieldName, fieldProps)增加新字段fieldName - 字段名,fieldProps - 字段属性Field
toJSONData()转换成用于提交的 json 数据object[]
toData()转换成普通数据,不包含删除的数据object[]
bind(ds, name)绑定头 DataSetds - 头 DataSet 对象或 id name - 绑定名
setQueryParameter(para, value)设置查询参数para - 参数名 value - 参数值
loadData(data, total)加载数据data - 数据数组 total - 总数,可选,用于分页

DataSet Events

事件名说明钩子参数参数说明是否可异步
update值更新事件({ dataSet, record, name, value, oldValue }) => voiddataSet - 数据集 record - 更新的记录 name - 更新的字段 value - 新值 oldValue - 旧值
query查询事件,返回值为 false 将阻止查询({ dataSet, params, data }) => booleandataSet - 数据集 params - 查询参数 data - 查询参数
beforeLoad数据加载前的事件, 用于处理请求数据({ dataSet, data }) => voiddataSet - 数据集 data - 请求数据
load数据加载完后事件({ dataSet }) => voiddataSet - 数据集
loadFailed数据加载失败事件({ dataSet }) => voiddataSet - 数据集
submit提交事件,返回值为 false 将阻止提交({ dataSet, data }) => booleandataSet - 数据集 data - json 数据
submitSuccess提交成功事件({ dataSet, data }) => voiddataSet - 数据集 data - 响应数据
submitFailed提交失败事件({ dataSet }) => voiddataSet - 数据集
select选择记录事件({ dataSet, record, previous }) => voiddataSet - 数据集 record - 选择的记录 previous - 之前选择的记录,单选模式下有效
unSelect撤销选择记录事件({ dataSet, record }) => voiddataSet - 数据集 record - 撤销选择的记录
selectAll全选记录事件({ dataSet }) => voiddataSet - 数据集
unSelectAll撤销全选记录事件({ dataSet }) => voiddataSet - 数据集
indexChange当前记录变更事件({ dataSet, record, previous }) => voiddataSet - 数据集 record - 新当前记录 previous - 旧当前记录
fieldChange字段属性变更事件({ dataSet, record, name, propsName, value, oldValue }) => voiddataSet - 数据集 record - 字段所属记录,dataSet 的字段无 record name - 字段名 propsName - 属性名 value - 新值 oldValue - 旧值
create记录创建事件({ dataSet, record }) => voiddataSet - 数据集 record - 创建的记录
remove记录移除事件({ dataSet, records }) => voiddataSet - 数据集 records - 移除的记录
export导出事件,返回值为 false 将阻止导出({ dataSet, params, data }) => booleandataSet - 数据集 params - 查询参数 data - 查询参数
beforeRemove数据临时删除前的事件, 返回值为 false 将阻止临时删除({ dataSet, records }) => booleandataSet - 数据集 records - 记录集
beforeDelete数据删除前的事件, 返回值为 false 将阻止删除({ dataSet, records }) => booleandataSet - 数据集 records - 记录集
reset数据重置事件({ dataSet, records }) => voiddataSet - 数据集 records - 记录集
validate校验事件({ dataSet, result }) => voiddataSet - 数据集 result - 校验结果集

Record Values

详细介绍:Record

名称说明类型
id唯一 ID,自增长的数字number
key唯一键,主键字段或唯一索引键字段的值,默认同 idstring | number
status状态, 可选值 add update delete syncobservable<string>
selectable可选observable<boolean>
isSelected是否选中observable<boolean>
isCurrent是否当前记录observable<boolean>
children树形子数据集Record[] | undefined
parent树形父数据Record | undefined
previousRecord树形中前一条数据Record | undefined
nextRecord树形中后一条数据Record | undefined
level树形层级number
dirty数据是否发生变更, 包含级联数据源是否变更boolean
cascadeParent级联父数据Record | undefined
index在数据源中的索引number

Record Methods

详细介绍:Record

名称说明参数返回值类型
get(fieldName)根据字段名获取字段值。注意:禁止通过 record.data[fieldName]的方式获取字段值。fieldName - 字段名any
getPristineValue(fieldName)根据字段名获取字段的原始值。fieldName - 字段名any
set(fieldName, value)给指定字段赋值fieldName - 字段名或者键值对对象;value - 值
init(fieldName, value)给指定字段初始化值。字段变为净值。fieldName - 字段名或者键值对对象;value - 值
setState(key, value)设置自定义状态值。key - 键名或者键值对对象;value - 值
getState(key)获取自定义状态值。key - 键名
toJSONData()转换成用于提交的 json 数据, 受 DataSet 的 dataToJSON 属性影响。object
toData()转换成普通数据, 包括所有级联数据object
validate(all, noCascade)校验记录all - 校验所有字段,默认为 false,只校验修改或新增字段 noCascade - 为 true 时,不校验级联数据Promise<boolean>
getCascadeRecords(childName)根据级联名获取子级联数据childName - 级联名Record[]
getField(fieldName)根据字段名获取字段fieldName - 字段名Field
clone()克隆记录,自动剔除主键值Record
ready()判断记录是否准备就绪Promise
reset()重置更改
save()保存当前数据至缓存
restore()从缓存恢复保存的数据
clear()清除所有数据

Field Props

详细介绍:Field

参数说明类型默认值
name字段名string
type字段类型,可选值: boolean number string date dateTime time week month year email url intl objectstringstring
order排序类型,只支持单 field 排序, 如果多个 field 设置了 order,取第一个有 order 的 field,可选值: asc descstring
label字段标签string
labelWidth字段标签宽度number
format字符串类型和日期类型字段值格式化。 字符串类型格式化可选值: ‘uppercase’ ‘lowercase’ ‘capitalize’string
pattern正则校验string | RegExp
maxLength最大长度number
minLength最小长度number
max最大值。 fieldName 指向当前记录的 fieldName 值作为最大值。number | MomentInput | fieldName
min最小值。 fieldName 指向当前记录的 fieldName 值作为最小值。number | MomentInput | fieldName
step步距number | { hour: number, minute: number, second: number }
validator校验器,当返回值为 false 或 涵盖错误信息的字符串,则为校验失败(value, name, record) => boolean | string | undefined
required是否必选booleanfalse
readOnly是否只读booleanfalse
disabled是否禁用booleanfalse
textField值列表的文本字段stringmeaning
valueField值列表的值字段stringvalue
trueValue类型为 boolean 时,true 对应的值boolean |string |numbertrue
falseValue类型为 boolean 时,false 对应的值booleanstring |number
options下拉框组件的菜单数据集DataSet
group是否分组,如果是 number,则为分组的顺序(暂无实装)boolean |number
defaultValue默认值any
multiple是否为值数组。 当为字符串时,作为数据分隔符,查询时会将字符串分割成数组,提交时会将数组拼接成字符串boolean | stringfalse
range是否为范围值。 当为 true 时,则值为[startValue, endValue];当为数组时,例如[‘start’, ‘end’]时,则值为{ start: startValue, end: endValue }boolean | [string, string]false
unique唯一索引或联合唯一索引组名。multiple 和 range 字段不适用。当 column 的 editor 设为 true 时,编辑器只会在新增的记录显示,如果要对已有数据进行编辑,请自定义 editorboolean | stringfalse
lovCodeLOV 配置代码string
lovParaLOV 或 Lookup 查询参数对象object
lookupCode值列表代码string
lookupUrl值列表请求地址string | (code) => string
lovDefineUrllov 配置请求地址string | (code) => string
lovQueryUrllov 查询请求地址string | (code, config, { dataSet, params, data }) => string
lookupAxiosConfig值列表请求配置或返回配置的钩子,详见AxiosRequestConfig。配置中默认 url 为 lookupUrl, method 为 post。AxiosRequestConfig| ({ dataSet, record, params, lookupCode }) => AxiosRequestConfig
lovDefineAxiosConfiglov 配置的请求配置或返回配置的钩子,详见AxiosRequestConfig。 配置中默认 url 为 lovDefineUrl, method 为 post。AxiosRequestConfig| (code) => AxiosRequestConfig
lovQueryAxiosConfiglov 查询的请求配置或返回配置的钩子,详见AxiosRequestConfig。 配置中默认 url 为 lovQueryUrl, method 为 post。AxiosRequestConfig| (code, config, { dataSet, params, data }) => AxiosRequestConfig
lookupBatchAxiosConfig返回 lookup 批量查询配置的钩子,优先级高于全局配置的lookupBatchAxiosConfig,根据返回配置的url的不同分别做批量查询,详见AxiosRequestConfig(codes: string[]) => AxiosRequestConfig-
bind内部字段别名绑定string
dynamicProps动态属性对象。对象为字段属性和返回该字段值的钩子的键值对。原对象属性钩子将在 v1.0 版本中废弃。{ fieldProp: ({ dataSet, record, name }) => value }
cascadeMap快码和 LOV 查询时的级联参数映射。 例如:cascadeMap: { parentCodeValue: ‘city’ },其中’city’是当前所在数据源的其他字段名,parentCodeValue 是快码和 LOV 的查询参数object
currency货币代码,详见Current currency & funds code list.string
ignore忽略提交, 可选值: always - 总是忽略 clean - 值未变化时忽略 never - 从不忽略stringnever
transformRequest在发送请求之前对数据进行处理(value: any, record: Record) => any
transformResponse在获得响应之后对数据进行处理(value: any, object: any) => any
trim字符串值是否去掉首尾空格,可选值: both | left | right | nonestringboth
defaultValidationMessages默认校验信息,详见ValidationMessagesValidationMessages

Field Values

详细介绍:Field

名称说明类型
name字段名readonly string
type类型observable<string>
required是否必选observable<boolean>
readOnly是否只读observable<boolean>
disabled是否禁用observable<boolean>

Field Methods

详细介绍:Field

名称说明参数返回值类型
get(propsName)根据属性名获取属性值propsName - 属性名any
set(propsName, value)设置属性值propsName - 属性名;value - 属性值
reset()重置设置的属性
checkValidity()校验字段值boolean
setLovPara(para, value)设置 Lov 的查询参数para - 参数名;value - 参数值
getValue()获取当前记录的本字段值any
getText(lookupValue)根据 lookup 值获取 lookup 描述lookupValue - lookup 值,默认本字段值string
getLookupData(lookupValue)根据 lookup 值获取 lookup 数据对象lookupValue - lookup 值,默认本字段值object
fetchLookup()请求 lookup 数据,若有缓存直接返回缓存数据。Promise<object[]>
isValid()是否校验通过boolean
getValidationMessage()获取校验信息string

Transport

详细介绍:Transport

属性说明类型
create新建请求的 axios 配置或 url 字符串AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
read查询请求的 axios 配置或 url 字符串AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
update更新请求的 axios 配置或 url 字符串AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
destroy删除请求的 axios 配置或 url 字符串AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
validate唯一性校验请求的 axios 配置或 url 字符串。当字段配了 unique 属性时,在当前数据集中没有重复数据的情况下,则会发起远程唯一性校验。校验的请求 data 格式为 { unique: [{fieldName1: fieldValue1,fieldName2: fieldValue2…}] },响应格式为 boolean | boolean[]。AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
submitcreate, update, destroy 的默认配置或 url 字符串。AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
tls多语言数据请求的 axios 配置或 url 字符串。UI 接收的接口返回值格式为:[{ name: { zhCN: ‘简体中文’, enUS: ‘美式英语’, … }}], 其中 name 是字段名。请使用全局配置 transport 的 tls 钩子统一处理。AxiosRequestConfig | ({ data, params, dataSet, record, name }) => AxiosRequestConfig | string
exports导出的配置或 url 字符串AxiosRequestConfig | ({ data, params, dataSet }) => AxiosRequestConfig | string
adapterCRUD 配置适配器(config: AxiosRequestConfig, type: string) => AxiosRequestConfig

Feedback

属性说明类型
loadSuccess(resp)DataSet 查询成功的反馈, resp - 响应值Function
loadFailed(error)DataSet 查询失败的反馈, error - 异常对象Function
submitSuccess(resp)DataSet 提交成功的反馈, resp - 响应值Function
submitFailed(error)DataSet 提交失败的反馈, error - 异常对象Function

DataToJSON

详细介绍:DataToJSON

枚举值说明
dirty只转换变更的数据,包括本身无变更但级联有变更的数据
selected只转换选中的数据,无关数据的变更状态
all转换所有数据
normal转换所有数据为普通 json,不会带上status, id 等附加字段,也不会出现临时删除的数据, 一般用于大 JSON 字段
dirty-self同 dirty, 但不转换级联数据
selected-self同 selected, 但不转换级联数据
all-self同 all, 但不转换级联数据
normal-self同 normal, 但不转换级联数据