数据组件

前端界面采用数据绑定设计模式，输入框、单选、多选、表格等组件绑定数据组件即可展现数据，增删改查不需要写代码

数据组件提供以下能力

• 查询：过滤、分页、排序、关联查询
• 规则：前端校验，只读、必填、计算
• 方法和事件：用于前端编程，例如保存前处理

数据集分为三种类型，分别是动态数据集、静态数据集和统计数据集。系统将这三种类型的数据集，抽成3个数据组件，实现低代码访问数据集。

组件种类

数据组件有三种，分别对应三种类型的数据集。为了便于前端页面上使用临时数据，增加自定义数据组件，在页面上定义列和数据，在页面中使用。

数据组件具有如下的继承关系：

aggregateData → restData → tableData → data

tableData 提供了前端的能力，restData 在此基础上，提供了后端能力。

数据查询

通用查询属性

支持数据查询的数据组件是 restData 和 aggregateData。

数据列

设置查询的数据列，默认为全部列，不包括输出数据集。如果要返回输出数据集，必须设置数据列。输出数据集可以返回嵌套数据，目前只支持嵌套一层数据。

过滤

设置查询条件。单个查询条件的格式为：列 操作符 值，例如：单价 大于 300。支持16种操作符。支持多查询条件，多个条件之间使用连接符连接。

• 列

可以设置查询条件的有数据集里面的列，也可以是数据集上设置的数据集参数。

• 操作符

• 连接符

• 值

关联查询

设置关联查询的数据对象、关联条件和查询列。两个在同一个模块下的数据集可以使用关联查询。具体介绍参考《关联查询》

• 数据对象

选择在同一个模块下的数据集为左表和右表。

• 关联方式

默认为左连接 left，支持右连接 right、内连接 inner、全连接 full

• 关联条件

关联条件类似于过滤条件，但有所不同。

• 查询列

设置右表的某些列也作为查询的返回列，系统为右表的列生成

子查询

设置子查询，支持通过另一个查询结果过滤数据。具体介绍参考《子查询》

排序

设置查询数据的顺序，支持多列排序，支持升序和降序。

分页

系统默认采用分页查询数据，一页20条数据，支持修改，设置为-1表示加载全部数据，请谨慎使用。

使用分页数据查询，查询结果中会包括总记录数，总记录数用于计算总页数。数据组件的总记录数和记录数不同，总记录数是本次查询满足条件的数据的数量，记录数是加载到前端数据组件中的数据的数量。

统计

支持对数值列进行求和、求平均值、求最大值和最小值的统计，支持对所有列进行求记录数的统计。和统计数据集不同，统计数据集是基于分组进行统计的，而动态数据组件的统计是基于全部查询数据进行统计的。

去重

数据集设置指定字段数据去重后，需要自定义主键列（数据集如果没有主键，操作数据时会出现各类问题，无法正常操作数据，因此数据集必须设置主键），如果数据中有字段值唯一，则可以直接设置为主键列，否则需要添加“主键”字段计算列，并设置数据集主键为新增的主键列。新增计算列主键，值不会自动生成，数据集在“规则设置”下，设置主键计算值为 “wx.UUID.createUUID()”（可根据需求自定义函数）。

支持查询去重后的数据，例如在下表中记录了参加考试的学生及成绩，查询参加考试的学生名单，就使用去重查询，数据列选择姓名，去重查询出张三和李四。

树形查询属性

系统默认使用分级加载，先加载根，展开根时，加载子

• 默认加载父列为 null 的数据作为根，可以通过设置树形根过滤，加载符合条件的数据作为树的根节点
• 每一级加载的数据由 limit 控制分页大小

是否树形数据

在数据集上设置为“树形数据”后，数据组件自动感知为树形数据，取消选中“树形数据”，则可以作为普通数据查询

是否加载全部树形数据

选中加载全部树形数据后，符合条件的数据全部加载到前端

• 如果没有设置过滤条件，会加载全部数据，即显示一个完整的树
• 如果设置了过滤条件，例如查询某个节点下的全部数据，会加载出一个子树（注意加载子树时，需要设置过滤条件，而非树形根过滤条件）
• 全部加载时，limit 自动为-1

树形根过滤

设置树形根过滤，加载符合条件的数据作为树的根节点

树展现方式

支持4种展现方式

• 默认
• 虚拟树
• 虚拟树（只保留父）
• 虚拟树（只保留子）

子节点列

用于加载 JSON 嵌套数据，如下图所示，设置子节点列为 children，可将这个 JSON 嵌套数据用作树形数据

计算列

数据组件还提供了前端计算列，列中的数据不来自后端数据集，也不会保存到后端数据集，后端数据集里面也没有这一列。计算列用于前端页面上的业务逻辑。可以设置一个或者多个计算列。每个计算列需要设置名称、数据类型和显示名称。

计算列和数据组件的原有列，使用方法相同，也支持设置数据规则。特别说明：计算列设置默认值无效。

数据规则

数据组件可以设置7种规则，包括数据集全部列只读、列只读、默认值、必填、计算、约束和删除约束规则。通过设置规则控制是否只读、列的默认值、是否必填，设置计算公式，校验输入合法性。所有的规则都支持设置为表达式，即先运算表达式，再将结果作为规则的值。

只读

• 全部只读

全部只读是设置整个数据组件是否只读，只读后不能新增、修改和删除。

• 只读

只读是设置数据组件的某一列是否只读。

默认值

默认值就是设置新增后某一列的值。系统会自动给主键列赋一个UUID作为默认值；给从数据集的外键列赋主数据集主键值作为默认值。特别说明：计算列设置默认值无效。

计算

计算用于自动计算某列的值，设置计算规则后，在规则中涉及的值改变后，该列的值会被自动计算。

必填

必填是设置数据组件的某一列是否可以为空，保存前判断，为空则不允许保存。设置“必填规则提示信息”可以替换系统默认的必填提示信息。

约束

• 约束、约束规则提示信息

约束是验证数据组件某一列中的值的有效性，例如：手机号、邮箱应该符合规范。系统提供了一些常用的约束，例如：格式为邮箱、格式为手机号码，其它约束规则可以自定义。其中约束返回“是”表示输入有效，返回“否”表示输入无效，保存前判断，无效则不允许保存。设置“约束规则提示信息”可以替换系统默认的约束提示信息。

• 删除约束、删除约束提示表达式

删除约束是验证数据组件的记录是否可被删除，删除约束表达式返回“是”表示可以删除，返回“否”表示不可删除。删除前校验。设置“删除约束提示表达式”可以替换系统默认的删除约束提示信息。

组件属性

数据组件提供了很多属性，最重要的就是自动模式。

自动模式

数据组件的自动模式属性用于设置：在打开页面时是否加载数据或是否新增数据。自动模式有4种：无、自动加载、自动新增、自动加载无数据新增。默认是自动加载。 自动加载时，过滤条件如果依赖了其他数据组件，会等待其他数据组件加载数据后，再加载当前数据集的数据。 如果在其他地方调用了数据集的刷新操作或方法，清空自动模式，减少发送无用的请求。 如果自动模式设置为空，或者即使设置为自动加载，但因为数据集没有数据导致页面上的数据组件没有加载到数据，这两种情况都会导致数据组件中没有数据。数据组件中没有数据时，与之绑定的输入框等表单组件将不能正常工作。其实大多数情况下，这时的自动模式应该设置为自动新增，而不是自动加载。即如果要新增数据，必须设置自动模式为自动新增或者调用数据的新增操作来新增一条空记录。

规则检查

设置数据组件的规则的生效时间和生效范围

• 检查时机
  • 默认：始终检查，不符合规则，显示红框及红色提示信息
  • 保存前：只在调用保存操作或方法时检查规则，不符合规则，显示红框及红色提示信息
• 检查范围
  • 所有：检查所有行
  • 当前行：只检查当前行
  • 编辑行：只检查编辑过的行

总记录数

总记录数模式：支持精确计算、优化计算、不计算。详情参考《总记录数》

计算数据集

计算数据集用于将“源数据集”中的数据，经过处理（例如一列变多列、一行变多行、多列变一列、多行变一行）形成新的数据组件

• 源数据集：设置数据来源
• 同步当前行：源数据集的当前行改变后，当前数据组件的当前行是否随之改变
• 数据处理
  • 计算数据集映射：设置源数据集和当前数据组件的列映射关系，未定义“行处理”事件时生效
  • 行处理：源数据集的每一行触发一次行处理事件，传入两个参数
    • sourceData：源数据集
    • row：行对象，包括源数据集和当前数据集的所有列
    • 事件返回行对象或行对象数组，返回的数据就是计算数据集自身的数据

示例：一列变多列，将“源数据集”属性列的值，分为多列显示。属性列中包括 size 和 color，在当前数据组件上添加颜色 color 和尺寸 size 列。

计算数据集属性设置如下图所示，选择“源数据集”，定义行处理事件

行处理事件代码如下

    productCalcDataOnComputedRowFn = ({sourceData,row}) => {
        if(row.props){
            let props = JSON.parse(row.props);
            row.color = props.color;
            row.size = props.size;
        }
        return row;
    }

运行效果如下图所示

子数据集

子数据集用于承载嵌套数据，具体介绍参考《子数据集》

其它属性

• 直接删除

设置调用数据组件的删除操作或方法时，是否删除数据表中的数据。如果设置为不直接删除，删除后进前端页面中删除了数据，当调用数据组件的保存操作或方法时，才删除数据表中的数据。

• 删除提示、删除提示文本

设置删除数据组件的记录时，是否提示删除确认信息。系统删除记录时，默认提示“是否确定删除数据？”，可以通过设置“删除提示文本”属性，重新设置一个删除提示。

• 刷新提示、刷新提示文本

设置在数据组件的数据已被修改后，又要执行刷新操作时，是否提示刷新确认信息。系统刷新时，默认提示“数据已经修改，刷新将丢失修改数据，是否确定刷新数据？”，可以通过设置“刷新提示文本”属性，重新设置一个刷新提示。

• 开启主从设置、主数据、关联列

在数据集设置为从数据集后，将数据组件添加到页面上，系统自动设置“主数据”和“关联列”属性。主数据设置的是关联的主数据集，关联列设置的是从数据集的外键列。

数据组件为主从数据，提供下面3个能力：

1. 主数据当前行改变后，立即刷新从数据
2. 新增从数据时，外键列自动设置为主数据的主键值
3. 级联保存：保存主数据集的同时，自动保存从数据集

如果数据集没有设置为从数据集，但是希望在前端页面中享受数据组件为主从数据提供的能力，可以开启主从设置，设置主数据和关联列，即可实现前端主从功能。

• 是否共享、绑定共享数据

系统提供的共享数据配置实现跨页面共享数据功能，通过在共享数据配置中，将数据集设置为共享数据集，在需要共享数据的页面中，添加该数据组件，并设置“是否共享”为true，绑定共享数据，这个数据组件里面的数据就不从后端数据集中获取，而是使用共享数据。共享数据的原则是：数据组件独立运行，数据部分同步共享。

1. 数据加载原则
   1. 数据组件初次加载数据时，首先判断是否
   2. 存在共享数据，如果存在则直接从共享数据中加载，否则按原逻辑进行数据加载
   3. 初次加载数据后的所有数据操作按原逻辑执行，如：刷新，新增，修改、删除
2. 共享数据同步原则
   1. 数据组件所有的数据操作都即时同步数据到共享数据，同步方式采用异步方式，避免阻塞主逻辑
   2. 数据组件只在页面显示事件中从共享数据同步
   3. 数据组件中数据按整体JSON同步到共享数据，包含数据状态部分

页面中的数据组件，如果要使用共享数据，就设置“是否共享”为 true，在“绑定共享数据”中选择共享数据集名称。如果不使用共享数据，就设置“是否共享”为 false。

• 感知上下文只读

根据页面参数判断是否只读，下面列出认定为只读的四种参数

1. 参数 _pagePattern 等于 readonly
2. 参数 activity-pattern 等于 detail
3. 参数 readonly 等于 true
4. 参数 action 等于 view

组件操作

数据组件提供操作，用于在设计页面的无代码开发。系统在调用操作时，进行了同步调用处理，即操作组合中的操作是顺序执行的。

• 新增、删除、删除全部

  • 新增：给“目标数据集”新增记录，可以设置新记录的插入位置，可以设置列的默认值。当默认值是 JSON 数组时，表示新增多条记录，JSON 中键是列标识，值是列的默认值
  • 删除：删除“目标数据集”中的数据，如果设置了“删除数据条件”，则将满足条件的数据都删除，否则删除当前行数据
  • 删除全部：清空后端数据集里面的全部数据

• 赋值、所有行赋值、多列赋值

  • 赋值：给“目标列”赋“值”
  • 所有行赋值：给“目标数据集”所有行的某“列”赋“值”
  • 多列赋值：给“目标数据集”的多个“列”赋“值”

• 保存、保存并返回

  • 保存：将“目标数据集”中修改的数据提交到后端数据集中，不是指提交当前行，而是所有修改的数据都会提交
  • 保存并返回：配合父页面的“打开子页面”操作使用，将页面中编辑的数据提交到后端数据集，然后将编辑的数据返回给父页面的共享数据集，如果是新增，可以通过设置“新增插入位置”属性，控制新增数据在父页面共享数据集中的插入位置

• 第一行、前一行、下一行、最后一行

  • 第 一 行：移动数据组件的当前行到第一行
  • 前 一 行：移动数据组件的当前行到前一行
  • 下 一 行：移动数据组件的当前行到下一行
  • 最后一行：移动数据组件的当前行到最后一行

• 第一页、上页、下页、最后页

  • 第一页：先清空，再加载“目标数据集”的第一页数据
  • 上 页：先清空，再加载“目标数据集”的前一页数据
  • 下 页：先清空，再加载“目标数据集”的后一页数据
  • 最后页：先清空，再加载“目标数据集”的最后一页数据

• 刷新、加载页、下页（增量）、全部页、加载数据

  • 刷新：先清空，再加载“目标数据集”的第一页数据
  • 加载页：先清空，再加载“目标数据集”的第几页数据
  • 下页（增量）：追加“目标数据集”下一页的数据
  • 全部页：加载全部数据
  • 加载数据：将数据（JSON 数组）加入到“目标数据集”中，设置“增量模式”为 true，表示追加，否则表示先清空，再加载

• 设置过滤、清除所有过滤

  • 设置过滤：增加“目标数据集”的过滤条件，过滤条件的设置方法同过滤属性的设置，给同一个数据集设置过滤时，过滤名称设置的一样，那么后面设置的过滤条件覆盖前面设置的过滤条件，如果过滤名称不同，则不会覆盖
  • 清除所有过滤：删除已经设置的过滤条件，包括在过滤属性中设置的过滤条件

• 设置排序、清除所有排序

  • 设置排序：增加“目标数据集”某列的排序规则，通过多次执行“设置排序”操作，实现设置多列排序
  • 清除所有排序：删除已经设置的排序规则，包括在排序属性中设置的排序规则

• 复制行、清除行

  • 复制行：从源数据集复制记录给目标数据集，如果目标数据集已经存在该记录（id 为标识），该操作会强制覆盖原有记录，如果不存在则会在目标数据集新增记录。行参数支持 id、id 列表、row、row 列表
  • 清除行：清除数据集的行记录，注意是前端数据集数据的清除，而非删除数据库记录的删除。行参数支持 id、id 列表、row、row 列表

组件方法

数据组件提供方法，用于在 js 中的低代码开发。数据组件提供了很多方法，具体介绍参考《数据组件方法》。数据组件中的行对象也提供了汗多方法，具体介绍参考《数据组件行对象方法》。

下面列出几个常用的方法及案例。在调用方法时，需要注意方法是否异步，例如刷新和保存都是异步方法，需要使用异步方法的调用方式。

• 案例一：设置过滤条件，并刷新数据

查询订单编号 orderNo 等于010或100的数据

    let filter = [];
    filter.push({"name":"orderNo","value":"010","op":"eq"});
    filter.push({"name":"orderNo","value":"100","op":"eq","kind":"or"});
    let mainData = this.comp("restData0");
    mainData.setFilter("filter1",filter);
    message.info("开始查询");
    await mainData.refreshData();
    message.info("查询到"+mainData.count()+"条数据");

运行效果如下图所示

• 案例二：保存数据，不能保存则提示

保存成功提示保存成功，否则提示失败信息

    let mainData = this.comp("restData0");
    try{
      await mainData.saveAllData();
      message.info("保存成功");
    }catch(e){
      message.error(e);
    };

保存时校验失败的运行效果如下图所示

保存成功的运行效果如下图所示

• 案例三：查找数据

在数据组件的数据中查找订单编号 orderNo 等于100的数据

    let mainData = this.comp("restData0");
    let rows = mainData.find(["orderNo"],["100"]);
    if(rows.length>0){
      message.info("已找到"+rows[0].orderNo);
    }else{
      message.info("未找到");
    }

运行效果如下图所示

• 案例四：遍历数据

遍历数据，每行进入一次回调，用 row 获取正在遍历的行数据

    let mainData = this.comp("restData0");
    mainData.each(({row})=>{
      message.info(row.orderNo);//取值
      row.status = 2;//赋值
    })

运行效果如下图所示

• 案例五：加载外部数据

使用自定义数据组件加载外部数据，在自定义数据的刷新事件中，获取数据并加载到自定义数据中，limit 在自定义数据组件中设置，offset 系统根据 limit 和当前页数自动计算，仅当查询第一页数据时（offset 等于0）设置总记录数。

    onTableCustomData0CustomRefresh(event){
        event.promise = this.loadOuterData(event.limit,event.offset).then((res)=>{
            event.source.loadData(res.data);
            if(event.offset==0){
                event.source.setTotal(res.total);
            }
        });
    }

    loadOuterData(limit,offset){//模拟异步请求获取数据
        let promise = new Promise((resolve,reject)=>{
            let res = {
                data:[{
                    id:1,
                    name:"张三",
                    age: 15
                },{
                    id:2,
                    name:"李四",
                    age: 16
                }],
                total: 22
            }
            resolve(res);
        });
        return promise;
    }

运行效果如下图所示

组件函数

数据组件提供函数，用于在设计页面的表达式编辑中使用，也是无代码开发。数据组件提供了数据集函数和数据列函数，显示在表达式编辑器的函数区域中。

数据集函数

• 跨页序号：用于在表格中显示连续的序号，具体用法参考《桌面端列表类组件》中的跨页序号
• 记录数：获得数据组件中有几行记录
• 总记录数：本次查询结果总共有多少条记录，和统计列中的计数结果一样
• 是否满足约束：对数据集进行校验
• 不满足约束提示：获取校验结果
• 当前为首行：判断当前行是否是第一行
• 当前为尾行：判断当前行是否是最后一行
• ID 列表：获得数据组件所有行主键值，逗号分隔，可用于从数据集的过滤
• JSON：将数据组件中的数据转为 JSON 对象

数据列函数

• 列名：获取数据集结构中的列标识
• 显示名：获取数据集结构中的列名称
• 是否只读：获取该列是否只读
• 是否隐藏：获取该列是否隐藏
• 是否必填：获取该列是否必填
• 是否满足约束：对该列进行校验
• 不满足约束提示：获取该列的校验结果
• 和、平均值、最大值、最小值：数值列的计算函数，求出数据组件中的数据的和、平均值、最大值和最小值

组件事件

数据组件提供了很多事件，在操作数据时触发，给开发者提供各种时机实现功能。具体介绍参考《数据组件事件》