【基础教程】组件数据绑定及数据更新事件

kk 开发者 2022-12-21 16:37:07

数据绑定概述

支持数据绑定的组件可以添加任意数量的数据集绑定。
当组件有且只有一个数据绑定时称为单绑定；
当组件有超过一个数据绑定时称为多绑定。

数据分析请求

BI自助分析工具运行框架根据组件数据绑定配置发起数据分析请求到分析服务获取数据绑定的数据分析结果集。

数据分析请求包含下列特点：

1. 一个数据绑定一个数据分析请求

当需要获取数据分析结果集时，一个数据绑定对应产生一个数据分析HTTP请求。

经过合并的默认数据分析请求除外，此时将按数据绑定高级配置项的配置进行分组合并。
在分析页面初始化期间发送的数据分析请求称为默认数据分析请求，数据绑定支持高级配置项，允许用户根据业务需要将默认数据分析请求合并或阻止，以减少页面初始化期间的数据分析请求数量（http请求），提升分析页面首次呈现性能。

2. 关联的画面参数值变化时自动触发请求

组件数据绑定可通过两种方式来关联画面参数：

指定数据集使用的查询变量值为画面参数值；
设置筛选条件值为画面参数值。

在分析页面运行期间，当BI自助分析工具运行框架检测到关联的画面参数值发送变化时，将发送数据分析请求给分析服务以获取最新的数据分析结果集。
该检测变化并触发发送机制不会在一个数据绑定关联的多个画面参数值同时变化时触发重复的数据分析请求。

根据组件的数据绑定数量及数据更新事件函数定义不同，发送的数据分析请求数量也会不同，在数据更新事件函数章节中做进一步阐述。

数据更新事件函数

当组件收到数据绑定的数据分析结果集时，分析结果将作为数据更新事件回调函数参数传参给用户脚本。
根据用户脚本业务逻辑需要，数据更新事件函数可以定义为下列两种：

默认数据更新事件函数（定义了组件不支持单个数据分析结果集回调）
单个回调的数据更新事件函数（定义了组件支持单个数据分析结果集回调）

数据更新流程由三个数据绑定内置事件组成：

数据更新前
可通过为组件添加名为updateBefore的组件事件函数，启用自定义脚本以处理数据更新前的相关业务逻辑。
数据更新
即 NFDW 事件函数
数据更新后
可通过为组件添加名为updateAfter的组件事件函数，启用自定义脚本以处理数据更新后的相关业务逻辑。
数据更新后事件函数是提供回调参数标识数据更新是否成功及数据分析结果。

1. 默认数据更新事件函数

默认数据更新事件函数参数只包含一个参数，表示该组件的所有数据绑定的数据分析结果集。
默认数据更新事件函数定义如下：

function NFDW(data){
  //用户脚本
  ....
}

当组件为单绑定时，data 参数为数据分析结果集对象。
当组件为多绑定时，data 参数为包含所有数据绑定的数据分析结果集数组，且数组中的结果集元素索引对应数据绑定添加时的顺序。

当组件的数据呈现需要同时依赖多个结果集时，可采用这种数据更新函数事件定义。
同时也请注意，当组件为多绑定时，由于其回调参数的形式为分析结果集数组（需要在每次调用数据更新事件函数时，按顺序生成分析结果集数组传参给用户脚本），这决定了在组件进行数据分析时需要将所有数据绑定都发送请求，而无论其中某些绑定的关联参数是否实际发生变化。

2. 单个回调的数据更新事件函数

单个回调的数据更新事件函数包含两个参数，参数一表示数据分析结果集对象，参数二表示该数据分析结果集的数据绑定索引。
单个回调的数据更新事件函数定义如下：

function NFDW(data, index){
  //用户脚本
  ....
}

当组件为单绑定时，data 参数为数据分析结果集对象，index参数省略。
当组件为多绑定时，data 参数为数据分析结果集对象，index参数为数据绑定索引。

当组件的数据呈现支持分绑定独立呈现时，可采用这种数据更新函数事件定义。
与默认数据更新事件函数不同，当组件需要发生数据分析请求时只会发送需要的绑定请求而不会发生“额外”的数据分析请求，这样有助于提升分析并呈现的及时性。

最后，将组件数据更新事件函数传参逻辑概况为如下三点：
1、单绑定组件，传参为数据分析结果集对象；
2、多绑定组件但不支持单个结果集回调，传参为数据分析结果集数组，其元素索引对应数据绑定索引；
3、多绑定组件且支持单个结果集回调，传参一为数据分析结果集对象，传参二该结果集对应的数据绑定索引。

主动数据分析

修改 vbi.system.updateData(comIdOrName) 更新定义为 vbi.system.updateData(comIdOrName, bindIndex)，以支持用户脚本主动触发支持单个结果集回调的数据更新事件函数定义的组件数据分析请求。
其中bindIndex 表示要触发的数据绑定的索引，当组件为单绑定或组件不支持单个结果集回调时该参数将被忽略。

...全文