# 用户场景
在开发工作中，会面临仅需要用表格展示数据的业务场景，过去苍穹平台仅可通过单据体和单据列表两种控件来实现，并且这两种表格控件均需绑定实体，设置复杂的逻辑，从而消耗大量精力。
现在苍穹平台需提供一种数据驱动的纯展示表格，无需绑定实体，设置复杂的逻辑，从而减轻开发工作量，提升效率。
# 控件对象
`kd.bos.form.control.grid.DataGrid`
# 适用版本
金蝶云苍穹BOS_V5.0.010及以上
# 属性说明
## 通用属性
>通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976)
## 样式属性
>样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336)
## 业务属性
| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 行高自适应 | 复选框 | false | 行高根据单元格内容进行自适应 |
| 行高 | 宽高选择器 | 40 | 设置表格每行的高度 |
| 最大行高 | 宽高选择器 | - | 行高自适应开启后显示该属性，用于限制自适应行高的最大高度，不设置则行高按实际内容显示 |
| 显示序号列 | 复选框 | false | 表格是否显示序号列 |
| 显示选择列 | 复选框 | false | 表格是否显示选择列 |
# 功能介绍
数据表格是数据驱动的纯展示表格，没有绑定实体，只需提供列定义**columns**和行数据**rows**，即可完成表格的渲染。目前实现的功能有：
| **功能点** | **功能说明** |
| --- | --- |
| 数据赋值 | 通过插件赋值，无实体 |
| 字段支持 | 提供常用表格字段，包括文本，整数，小数，日期，时间，金额，图片，操作列。可配置字段格式化、样式等属性 |
| 序号列 | 对数据行进行序号标识，序号列默认左固定 |
| 行选中 | 提供行选中功能 |
| 样式配置 | 支持配置表格样式属性，包括列宽、行高、对齐方式、字体大小、行高自适应等基础样式 |
| 可见性设置 | 支持初始、新增、修改、查看等可见性设置 |
| 操作列 | 提供操作列，支持对行数据操作 |
## 数据赋值
数据表格行列数据格式跟列表的行列数据格式类似，区别在于数据表格行列数据不存在meta和data中，而是通过控件方法来赋值。
目前支持的控件方法有：**setColumns，setData**，**setDataIndex**，**setRows**
### setColumns
`setColumns`控件方法用于给数据表格设置列定义
列数据格式为：
```
[
{ dataIndex: 'No', header: {zh_CN: "序号"}, width: 60, align: 'center' },
{ dataIndex: 'order', header: {zh_CN: "单据号"}, width: 200 },
{ dataIndex: 'from', header: {zh_CN: "来户"}, width: 200 },
{ dataIndex: 'to', header: {zh_CN: "往户"}, width: 200 },
{ dataIndex: 'amount',header: {zh_CN: "应付金额"}, width: 100, align: 'right' },
{ dataIndex: 'balance', header: {zh_CN: "应收金额"}, width: 100, align: 'right' }
]
```
一般来说，在设计器里面配置好列定义后预览时可以直接生成。如果有动态修改列定义的需求，则需要自己的业务逻辑重新调用`setColumns`控件方法去修改列定义。
要创建列干预时，首先需要在插件initialize方法中为表格控件注册列创建和绑定数据列监听事件；表格控件列创建时触发创建列事件，插件需要实现BeforeCreateDataGridColumnsListener接口并重写beforeCreateDataGridColumns方法，从参数获取columns操作列集合进行自身的业务逻辑。
示例代码：
```java
/**
* 动态创建列、数据绑定
*/
public class DataGridSamplePlugin extends AbstractFormPlugin implements DataGridBindDataListener, BeforeCreateDataGridColumnsListener {
/**
* 初始化为控件增加监听事件
*/
@Override
public void initialize() {
DataGrid dataGrid = this.getControl("datagridap");
// 注册创建列监听事件
dataGrid.addBeforeCreateDataGridColumnsListener(this);
// 注册绑定数据监听事件
dataGrid.addBindDataListener(this);
}
/**
* 监听创建列事件
* @param event
*/
@Override
public void beforeCreateDataGridColumns(BeforeCreateDataGridColumnsEvent event) {
// 所有列集合
List<DataGridColumn> dataGridColumns = event.getDataGridColumns();
// 动态创建文本列
TextDataGridColumn column = new TextDataGridColumn();
column.setKey("colKey");
column.setCaption(new LocaleString("测试列"));
// 加入列集合
dataGridColumns.add(column);
}
}
```
*注意：列定义修改是全量替换的，暂时还没有支持差量修改某一列的列定义；*
### setData
`setData`控件方法是为了方便初始化数据，将dataIndex，行数据，postCols等放到一起处理的一个控件方法，一般只在初始化的时候调用。
1.dataIndex是列标识对应行数据下标的映射，和列表的dataIndex是一样的，数据格式为：
```
{
rk:0,
order:1,
from: 2,
to: 3,
amount: 4,
balance: 5,
id:6
}
```
2.rows是表格行数据，数据格式为：
```
[
[ 0, 'AP-202009-00001', '陕西环宇科技', '深圳环球科技', '26,800.00', '5,200.00','1520610889135349760' ],
[ 1, 'AP-202009-00001', '陕西环宇科技', '深圳环球科技', '236,800.00', '1,500.00','1480537202210419712' ],
[ 2, 'AP-202009-00002', '陕西环宇科技', '深圳环球科技', '246,800.00', '5,300.00','1464513025938567168' ],
[ 3, 'AP-202009-00003', '陕西环宇科技', '深圳环球科技', '216,800.00', '5,400.00','577197513895838720' ],
[ 4, 'AP-202009-00004', '陕西环宇科技', '深圳环球科技', '236,800.00', '1,500.00','1505169947813265408' ]
]
```
3.postcols是行选中时需要回传到后端的列数据，是一个列标识的数组, 一般用于后端确认具体选中哪行数据，数据格式为
```
["id"]
```
表格控件刷新时触发绑定数据，插件需要实现DataGridBindDataListener接口并重写dataGridBindData方法，通过参数setData设置自定义数据。本方法参数提供DataGridRowBuilder方便创建行数据。
示例代码：
```java
/**
* 数据绑定
*/
@Override
public void dataGridBindData(DataGridBindDataEvent e) {
List<Object> list = new ArrayList<>();
int index = 0;
// 从参数获取rowBuilder来辅助构造行数据
DataGridRowBuilder builder = e.getDataGridRowBuilder();
for (int i = 0; i < 10; i++) {
DataGridRow row = builder.buildRow();
// rk和seq为系统保留字段(主键和序列号)，支持自定义传值
row.setValue("rk", index); // rk必须存在且唯一不能重复
row.setValue("seq", index + 1);
row.setValue("textfield", "文本列数据");
row.setValue("colKey", "动态列数据");
list.add(row.get());
index++;
}
// 重要: 传递列表数据
e.setData(list);
// 设置postCols数据
e.addPostCol("kdtest_idcolumn");
}
```
### setDataIndex
`setDataIndex`控件方法用于设置dataIndex，一般在动态修改列定义之后需要重新调用
### setRows
`setRows`用于设置表格行数据，在更新行数据的时候调用
## 字段支持
目前支持的表格列类型有：**表格文本**，**表格整数**，**表格小数**，**表格日期**，**表格时间**，**表格金额**，**表格图片**，**操作列**。每种列类型有特定的列格式化信息配置，比如表格小数可以配置精度，表格日期可以配置掩码等，使用时可以按照实际场景添加。
列类型支持样式配置，包括列宽，字体大小，前景色，背景色，文本对齐方式。
在配置列格式化信息时，如果不想使用设计器里面的格式化信息或者设计器里面的不能满足需求，也可以自己返回格式化的值。具体实现是在行数据里面返回值时不要返回字符串或者数字，而是返回一个数组，数组第一个值是格式化后的值，第二个值是原始值。比如有一个小数12.34567, 想要显示的值是保留两位小数的，那么可以设置值为[‘’12.35‘’, 12.34567]。
## 行选中
数据表格提供行选中功能，支持单选和多选。行选中是差量的选中，提供两个指令`addRowSelection**`**和`clearRowSelection**`，**每次点击只能选中或者取消选中当前行
## 操作列
数据表格提供操作列功能。
操作列需要在设计器中绑定操作项，点击操作项时，会发一个`itemClick`的指令。请求参数包含当前点击的行号，postcols指定要回传的数据，操作项id和操作项名称。点击操作项后，具体的业务逻辑需要自己监听处理
# 使用示例
这里以数据表格和列表之前实现简单的数据联动为例，介绍数据表格的一些使用场景。插件脚本以ks脚本为例，java插件脚本类似。
1.新建一个单据作为数据表格的数据源，加入相应的列
2.新建一个动态表单，加入一个工具栏和一个数据表格，给数据表格加入和上面列表对应的列
工具栏上的新增按钮绑定跳转页面的操作代码，跳转的表单设置为上面步骤1中作为数据源的单据，方便点击新增时可以快速到单据上新增数据。
操作列上用donothing类型增加编辑和删除两个操作项
3. 注册一个新的插件脚本。动态表单根节点下找到【插件】→【注册脚本】→【KDE】, 插件类型选择表单插件,填好名称和编码后生成一个ks文件。
4.插件示例代码，处理操作列点击逻辑和单据数据到数据表格的转换
```js
var plugin = new FormPlugin({
initialize : function(e) {
var dataGrid = this.getControl("kdtest_datagridap");
dataGrid.addBindDataListener(this);
},
registerListener : function(e){
this.addItemClickListeners("kdtest_datagridap", "kdtest_toolbarap");
var dataGrid = this.getControl("kdtest_datagridap");
dataGrid.addBindDataListener(this);
},
afterCreateNewData: function(e) {
var dataGrid = this.getControl("kdtest_datagridap");
dataGrid.addBindDataListener(this);
},
itemClick : function(e){
var key = e.getOperationKey();
if ("kdtest_baritemap2" == e.getItemKey()){
this.getView().updateView("kdtest_datagridap");
}
// 编辑逻辑处理
if (key == "editing"){
var selectedRow = e.getParamsMap().get("selectedRow");
var parameter = new BillShowParameter();
parameter.setFormId("kdtest_qing_bill");
parameter.getOpenStyle().setShowType(ShowType.Modal);
parameter.setPkId(selectedRow.getPostRowData().get(0));
parameter.setCloseCallBack(new CloseCallBack(this, "myEdit"));
this.getView().showForm(parameter);
}
// 删除逻辑处理
if (key == "delete") {
var selectedRow = e.getParamsMap().get("selectedRow");
var orm = new ORM();
var result = orm.delete("kdtest_qing_bill", selectedRow.getPostRowData().get(0));
this.getView().updateView("kdtest_datagridap");
}
},
closedCallBack: function(e) {
var dataGrid = this.getControl("kdtest_datagridap");
dataGrid.addBindDataListener(this);
this.getView().updateView("kdtest_datagridap");
},
dataGridBindData: function(e) {
// 单据列表对应的列标识
var fields = "id,kdtest_textfield,kdtest_integerfield,kdtest_decimalfield,kdtest_datefield,kdtest_timefield,kdtest_amountfield,kdtest_picturefield";
var dynamicObject = BusinessDataServiceHelper.load("kdtest_qing_bill", fields, []);
// 数据表格对应的列标识
const columns = ["kdtest_textcolumn","kdtest_integercolumn","kdtest_decimalcolumn","kdtest_datecolumn","kdtest_timecolumn","kdtest_amountcolumn","kdtest_picturecolumn"]
var list = new ArrayList();
var builder = e.getDataGridRowBuilder();
for (var i = 0; i < dynamicObject.length; i++) {
var row = builder.buildRow();
row.setValue("rk",i);
row.setValue("seq", i + 1);
row.setValue(columns[0], dynamicObject[i].get("kdtest_textfield"));
row.setValue(columns[1], dynamicObject[i].get("kdtest_integerfield"));
row.setValue(columns[2], dynamicObject[i].get("kdtest_decimalfield"));
var date = dynamicObject[i].get("kdtest_datefield");
row.setValue(columns[3], date);
row.setValue(columns[4], dynamicObject[i].get("kdtest_timefield"));
row.setValue(columns[5], dynamicObject[i].get("kdtest_amountfield"));
row.setValue(columns[6], dynamicObject[i].get("kdtest_picturefield"));
row.setValue("kdtest_idcolumn", ""+dynamicObject[i].getLong("id"));
list.add(row.get());
}
e.setData(list);
e.addPostCol("kdtest_idcolumn");
}
});
```
5. 数据新增，打开数据表格单据，点击新增
录完数据保存后，点击刷新，可以看到刚才录的数据已经显示到数据表格上了
6. 数据修改，点击刚才新建数据的编辑按钮，进入到单据页面，修改文本值为‘’文本123‘’
回到数据表格界面，数据已经刷新了
7.数据删除，点击数据的删除按钮，可以看到数据已经删除掉了，对应单据的列表上也没有数据。
至此，一个简单实现数据增删改的数据表格就算完成了。当然，这里只是其中一种使用场景，实际上数据表格完全是自定义的，数据源可以是列表，数据库，也可以是自定义的一些数据，这个完成取决于自己的业务需要。
# 注意事项
*1. 数据表格设计的初衷是满足纯展示数据的表格场景，没有很多复杂业务逻辑的实现。如果业务包含一些复杂的业务逻辑，建议使用列表或者单据体实现*
*2.数据表格使用上是简单的，但是控件本身是复杂的，需要编写插件设置数据才能正常运行*
