# 变更记录 | 产品版本 | 更新内容 | 更新日期 | | --- | --- | --- | | V5.0.018 | 单据体平铺视图支持配置帮助文本 | 2023-04-06 | | V5.0.022 | 新增了通过框选中几个单元格，自动对框选单元格进行求和与计算平均值的功能，满足了用户对数据快速计算的需求 | 2023-06-07 | | V5.0.024 | 新增了冻结列的功能，支持开发者配置默认冻结列，满足用户配置冻结列初始数据的需求 | 2023-07-13 | | V6.0.1 | 字段分组支持配置 折叠/展开
分组字段名 支持配置帮助文本
标题行字体大小支持可配置 | 2023-09-11 | | V6.0.1 | 优化了在单据体字段为空时不展示为空提示的问题，优化了用户的录入体验 | 2023-10-25 | | V6.0.9 | 新增了在设计器为单据体预设显示/隐藏字段字段的能力，满足业务希望为单据体配置默认显示/隐藏字段字段的需求 | 2024-04-12 | | V6.0.12 | 1.完善了PC端表格拖拽行排序的能力，支持拖拽选中的单行、多行、不连续行，满足用户快速调整顺序的场景
2.完善了表格使用帮助，可在表格单元格右键查看说明，提升用户体验 | 2024-05-22 | | V6.0.14 | 完善了表格分页功能，表格开启分页属性后，可设置最大分页条数，满足用户使用场景 | 2024-06-20 | | V7.0.1 | 1.完善了表格功能，支持冻结列冻结在右侧，满足用户使用场景
2.完善了块粘贴功能，支持在不连续单元格中粘贴，满足用户使用场景，提升用户体验 | 2024-10-24 | # 1 功能介绍 展示一批具有相同属性的数据，类似Excel。在业务语义上一个单据体对应数据库中一张表，其中一列对应数据库表的一列。单据体可编辑录入数据。 # 2 控件对象 `kd.bos.form.control.EntryGrid` # 3 视觉展示 * 单据体视图  * 平铺视图  # 4 表格属性 ## 4.1 通用属性 >通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976) ## 4.2 样式属性 >样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336) ## 4.3 业务属性 * 单据体 | 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | 行高 | 宽高选择器 | 40 | 设置表格每行的高度 | | 表头高度 | 宽高选择器 | 34 | 设置表头的高度 | | 行高自适应 | 复选框 | false | 行高根据内容自适应。详见4.3.1 | | 显示序号列 | 复选框 | false | 设置序号列是否显示 | | 显示选择列 | 复选框 | false | 设置选择列是否显示 | | 行内增删 | 复选框 | false | 设置行上增删功能,需要打开显示序列号开关,详见4.3.2 | | 可折叠 | 复选框 | false | 设置单据体是否可折叠 | | 默认折叠 | 复选框 | false | 打开可折叠开关会显示这以属性，可以设置单据体默认是否是折叠状态 | | 多选 | 复选框 | true | 设置是否可选择多行 | | 排序和过滤 | 下拉 | 允许排序和过滤 | 设置是否允许列头开启排序过滤功能 | | 过滤刷新合计 | 复选框 | false | 设置表格过滤后是否要刷新合计信息 | | 分页 | 复选框 | false | 是否分页展示数据，开启后出现分页工具栏，详见4.3.3 | | 最大分页条数 | 下拉 | 5000条/页 | 打开分页开关会显示该属性，设置允许选择的最大分页条数 | | 默认分页条数 | 下拉 | 5000条/页 | 打开分页开关会显示该属性，用于设置默认的分页条数，默认分页条数不能大于最大分页条数 | | 工具栏位置 | 下拉 | 默认 | 打开分页开关会显示该属性，用于设置工具栏显示的位置，默认为上 | | 分页类型 | 下拉 | 默认 | 打开分页开关会显示该属性，用于设置分页的类型，可以配置分页器的样式 | | 界面规则 | 弹框选择 | - | 设置列规则来达到预置的条件时触发界面改变，详见4.3.4 | | 显示平铺视图 | 复选框 | false | 设置单据体是否以平铺视图展示，详见4.3.5 | | 显示表格设置 | 复选框 | false | 表格右上角显示设置图标，可对表格进行配置 | | 表名 | 文本 | – | 设置数据库表名，动态表单没有该属性 | | 拆分表 | 弹框选择 | - | 配置存储的纵向拆分表 | | 序号字段名 | 文本 | FSeq | 配置分录序号字段名称 | | 主键 | 文本 | FEntryID | 配置分录主键字段名称 | | 缺省行数 | 整数 | 1 | 设置默认有几个空行 | | 业务规则 | 弹框选择 | - | 配置实体对应的业务规则 | | 关键字段 | 下拉 | – | 配置分录的关键字段,用于表明分录行录入的有效性,详见4.3.6 | | 勾选模式 | 下拉 | 默认 | 默认为空，勾选框选中模式为checkboxSelect，只能通过勾选框来进行选中/反选操作; 列表选中模式为 listSelect,单据体会自动锁定，可以点击整行来进行选中/反选操作，详见4.3.7 | | 字段分组可折叠 | 复选框 | 不展示 | 配置字段分组是否显示展开按钮 | | 字段分组默认折叠 | 复选框 | 不折叠 | 配置字段分组是否默认展开 | | 默认显示列 | 弹框选择 | - | 通过配置默认显示列，可以在设计器为单据体预设显示/隐藏字段，满足业务希望为单据体配置默认显示/隐藏字段的需求 | | 行拖拽 | 复选框 | false | 配置分录是否支持通过拖拽调整行顺序 | * 列属性 | 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | 显示为超链 | 复选框 | false | 设置该列显示为超链接形式，展示数据时才生效 | | 汇总方式 | 下拉 | 不汇总 | 数字列才有该属性，显示这一列汇总信息 | 列属性的其他业务属性跟列的类型有关，可以在相关的字段找到对应的属性说明，这里不再详述。 ### 4.3.1 行高自适应 表格级属性，多行多语言字段、多行文本支持较好，文本、大文本、基础资料和多语言文本可以换行，其他字段如金额、数字等由于规范不会换行。 设置行高自适应后，合计行的高度会取默认的设置的行高。  ### 4.3.2 行内增删 鼠标在行上悬浮时，序号列显示增删按钮，用户可以新增一行或者删除本行。 用户可以使用更新元数据的方式，来动态控制是否显示悬浮按钮。方法名为updateControlMetadata，属性Key为hasOperateIcon。  ### 4.3.3 分页 开启分页属性后，会显示分页工具栏。左侧是信息栏，会显示已选条数等信息，右侧是分页器，可以切换每页条数，上/下一页等  开启分页后可以配置分页类型属性，可以根据自己的需求做选择  ### 4.3.4 界面规则 可设置一系列规则来达到预置的条件时触发某种动作，常用的场景有：隐藏、显示、锁定、解锁列。 * 举个例子，锁定所有18岁的人员姓名列，不是18岁的人员不锁定 1.建立一个18岁规则条件。 2.建立一个条件成立时的动作。 3.建立一个条件不成立时的动作。  ### 4.3.5 显示平铺视图 平铺视图可以将单据体的字段的布局形式改成如单据头一样的平铺形式  要切换平铺视图，可以添加一个按钮然后给按钮的操作代码设置为切换平铺视图。  #### 平铺视图相关属性： * 平铺视图摘要 可以选择平铺视图左侧要显示的辅助文字  * 多字段面板 平铺容器支持多个字段面板,支持多字段面板展示  * 帮助文本 见[通用属性](https://vip.kingdee.com/article/215559076720798976?productLineId=29&isKnowledge=2)-帮助文本 ### 4.3.6 关键字段 关键字段用于保存单据时，单据体中某行数值未经手动修改的场景：若该行的关键字段值为空，则删除该行；反之保存该行。关键字段的效果是验证输入的有效性。举个例子，这个图中标红的值是缺省值（非手动修改输入），但都不是关键字段，所以判断输入无效，即：保存单据时会清空这一行。反之，如果一个字段是关键字段，那么只要这一行中该字段有值，就保存该行。  ### 4.3.7 勾选模式 详情请参考[《单据体新增两种行选中模式》](https://vip.kingdee.com/article/137514024350109440) ### 4.3.8 框选合计 表格支持框选合计功能，进行范围框选时，可以对框选范围的数值类单元格进行求和和计算平均值。框选合计默认开启，可以在表格设置面板中点击“选项”下“框选合计”开关选择关闭。 配置选项：  框选效果：  ### 4.3.9 默认冻结列 表格支持默认冻结列的配置。开发者可以根据业务需求，在设计器配置默认冻结列； 在单据体中“**单据体**”控件下，选择业务属性中“**冻结列**”属性设置默认冻结列；  冻结分为左冻结和右冻洁，左冻结中开启第N列的开关，则N列及N列以前的列都会冻结；右冻结中开启第N列的开关，则N列及N列以后的列都会冻结；  在运行时，冻结列生效优先级为用户数据>设计器数据； ### 4.3.10 为空提示信息 单据体控件内的字段增加“为空提示信息”属性，可以设置数据为空时显示的引导文本。当用户焦点到单据体的分录行上任一单元格、或者是选中这一行单元格时，展示该行上所有空单元格的“为空提示信息” 设计器入口  效果展示  ### 4.3.11 行拖拽 开启行拖拽属性后，表格左侧会显示拖拽图标，拖拽图标移动位置，目标行底部会显示一条横线，鼠标松开后即可实现行拖拽交换位置功能。  拖拽规则： 1. 对选中行进行拖拽操作时，拖拽结束时所有选中行都会插入到目标行底部 2. 对非选中行进行拖拽操作时，拖拽结束时只有该行插入到目标行底部 3. 对树形单据体进行拖拽时，不允许跨层级进行拖拽 ### 4.3.12 表格使用帮助 表格右键提供使用帮助选项，点击会出来一个弹窗显示表格的功能介绍。  # 5 单据体接口介绍 ## 5.1 控件编程模型 ### 5.1.1 控件编程模型定义 插件可以通过单据体控件编程模型实例，间接控制前端的单据体表格。 单据体的控件编程模型类为EntryGrid，派生自表格控件基类AbstractGrid： ```java package kd.bos.form.control; public class EntryGrid extends AbstractGrid implements ISupportInitialize { ``` 插件可以通过如下语句，获取到单据体控件实例： ```java EntryGrid grid = this.getView().getControl(Key_EntryEntity); ``` ### 5.1.2 控件方法清单 单据体控件EntryGrid，继承了表格控件基类的方法，并新增了如下公共方法： | 方法 | 说明 | | --- | --- | | getEntryKey | 获取单据体标识 | | setEntryKey | 设置单据体标识
内部方法，插件勿调用 | | getSubEntryGrids | 获取子分录表格集合 | | setSubEntryGrids | 设置子分录表格集合
内部方法，插件勿调用 | | getRuleCount | 获取实体服务规则个数 | | setRuleCount | 设置实体服务规则个数
内部方法，插件勿调用 | | getFieldEdits | 获取列字段控件集合 | | getRowBindValue | 获取行绑定的值
内部方法，插件勿调用 | | getDataIndex | 生成列索引返回
绑定行数据时，会按照列索引绑定各单元格的值 | | updateColFmt | 刷新字段对应列的格式化信息 | | updateCellFmt | 刷新字段对应单元格的格式化信息 | | setNumFmtInfo | 基于单元格的数据，刷新单元格格式化信息
内部方法，插件勿调用 | | setFloatButtomData | 设置合计单元格的值 | | next | 翻页
内部方法，插件勿调用 | | getSelectRows | 获取选中行 | | beginInit | 序列化处理方法
内部方法，插件勿调用 | | endInit | 序列化处理方法
内部方法，插件勿调用 | | isInitialized | 序列化处理方法
内部方法，插件勿调用 | ## 5.2 数据模型 ### 5.2.1 属性对象 保存单据设计时，系统会把单据体，转为单据主实体模型MainEntityType下的一个属性对象 EntryProp： ```java package kd.bos.entity.property; public class EntryProp extends DynamicCollectionProperty implements IValidatorHanlder { ``` EntryProp是集合型的属性，关联一个子实体模型 EntryType，包含单据体下的全部字段： ```java package kd.bos.entity; public class EntryType extends EntityType { ``` 如下示例代码，演示如何获取到单据体对应的属性对象，以及子实体模型： ```java private EntryProp getEntryProp(){ // 单据体在主实体模型下的属性对象 MainEntityType mainType = this.getModel().getDataEntityType(); EntryProp entryProp = (EntryProp)mainType.getProperties().get(KEY_ENTRYENTITY1); // 单据体关联的子实体对象，其下包含了单据体全部字段 // EntryType entryType = (EntryType)entryProp.getItemType(); // DataEntityPropertyCollection props = entryType.getProperties(); return entryProp; } ``` ### 5.2.2 属性值 在单据数据包中，单据体的数据是DynamicObjectCollection类型，单据体全部行的数据包集合。 单据体每行数据，又是DynamicObject类型，包含了单据体各字段值，以及子单据体数据包。 如下代码，分别演示了几种方法从数据模型中，获取单据体数据： ```java private DynamicObjectCollection getEntryRows(){ DynamicObjectCollection rows = null; // 方法一：利用DataModel提供的方法 rows = this.getModel().getEntryEntity(KEY_ENTRYENTITY1); // 方法二：自行从单据数据包中获取 DynamicObject billObj = this.getModel().getDataEntity(true); rows = billObj.getDynamicObjectCollection(KEY_ENTRYENTITY1); // 方法三：利用单据体属性对象EntryProp，从单据数据包中获取 EntryProp entryProp = (EntryProp)this.getModel().getDataEntityType().getProperties().get(KEY_ENTRYENTITY1); rows = (DynamicObjectCollection)entryProp.getValue(billObj); // 如下代码演示利用单据体属性对象，为单据体行增加新行 EntryType entryType = (EntryType) entryProp.getItemType(); DynamicObject row = new DynamicObject(entryType); rows.add(row); return rows; } ``` ## 5.3 单据体数据操作接口 ### 5.3.1 单据体数据操作接口定义 为方便代码快速访问单据体中的数据，系统特别封装了一个单据体数据操作接口IEntryOperate： ```java package kd.bos.entity.datamodel; public interface IEntryOperate { ``` 动态表单数据模型接口IDataModel，继承了此接口。因此，插件可以直接通过表单数据模型，获取、设置单据体数据： ```java package kd.bos.entity.datamodel; public interface IDataModel extends ISupportInitialize, IEntryOperate, IDataProvider { ``` 插件可以通过如下示例代码，获取到单据体数据模型接口实例： ```java private IEntryOperate getEntryDataModel(){ return this.getModel(); } ``` ### 5.3.2 方法清单 单据体数据模型接口IEntryOperate，提供了如下方法： | 方法 | 说明 | | --- | --- | | getEntryEntity | 获取全部行数据包集合；
有重载方法，可以指定行范围 | | getEntryRowEntity | 获取指定行的数据包 | | getEntryCurrentRowIndex | 获取焦点行索引 | | getEntryRowCount | 获取总行数 | | getEntryNextRowCount | 树表F7返回数据后，需要判断后面有没有足够同级行；
不够就appendEntryRow（不能insert，因为insert是插入下级行） | | getEntryNextRows | 获取树表当前节点后面的同级节点 | | createNewEntryRow | 新建行 | | batchCreateNewEntryRow | 批量新建行 | | insertEntryRow | 插入行
树表会给指定行，插入下级行 | | appendEntryRow | 批量追加分录行
树表F7返回数据时，使用此方法，在分录中间追加同级行 | | copyEntryRow | 复制行 | | deleteEntryRow | 删除行 | | deleteEntryRows | 批量删除行 | | deleteEntryData | 删除全部行 | | moveEntryRowUp | 行上移 | | moveEntryRowsUp | 批量行上移 | | moveEntryRowDown | 行下移 | | moveEntryRowsDown | 批量行下移 | ## 5.4 插件事件 单据体提供如下插件事件： | 分类 | 事件 | 触发时机 | | --- | --- | --- | | 数据行改变 | beforeAddRow | 暂未触发 | | [afterAddRow](https://vip.kingdee.com/article/228930911180655616) | 添加、插入、复制新行完毕，给新行填写了默认值之后触发 | | | [beforeDeleteRow](https://vip.kingdee.com/article/228931959807053056) | 暂未触发 | | | [afterDeleteRow](https://vip.kingdee.com/article/228932421566468352) | 删除行之后触发 | | | [beforeDeleteEntry](https://vip.kingdee.com/article/228933385836858624) | 暂未触发 | | | [afterDeleteEntry](https://vip.kingdee.com/article/228933931029369088) | 单据体数据被清空后触发 | | | [afterMoveEntryUp](https://vip.kingdee.com/article/228935359038886144) | 单据体行往上移动后触发 | | | [afterMoveEntryDown](https://vip.kingdee.com/article/228935359038886144) | 单据体行往下移动后触发 | | | 用户点击 | [cellClick](https://vip.kingdee.com/article/228946723907831040) | 单据体焦点行、焦点单元格切换时触发 | | [entryRowClick](https://vip.kingdee.com/article/228947436923261184) | 单据体焦点行、焦点单元格切换时触发 | | | [cellDoubleClick](https://vip.kingdee.com/article/228948317844311296) | 用户双击单据体中锁定的单元格时，触发此事件；如果单元格未锁定，双击不会触发此事件 | | | [entryRowDoubleClick](https://vip.kingdee.com/article/228949115114095872) | 用户双击单据体中锁定的单元格时，触发此事件；如果单元格未锁定，双击不会触发此事件 | | | [hyperLinkClick](https://vip.kingdee.com/article/228951002181797120) | 用户点击表格中超链接单元格时，触发此事件 | | 响应单据体表格全部事件： ```java package kd.bos.plugin.sample.dynamicform.pcform.entrygrid.template; import java.util.EventObject; import kd.bos.entity.datamodel.events.AfterAddRowEventArgs; import kd.bos.entity.datamodel.events.AfterDeleteEntryEventArgs; import kd.bos.entity.datamodel.events.AfterDeleteRowEventArgs; import kd.bos.entity.datamodel.events.AfterMoveEntryEventArgs; import kd.bos.entity.datamodel.events.BeforeAddRowEventArgs; import kd.bos.entity.datamodel.events.BeforeDeleteEntryEventArgs; import kd.bos.entity.datamodel.events.BeforeDeleteRowEventArgs; import kd.bos.form.control.EntryGrid; import kd.bos.form.control.events.CellClickEvent; import kd.bos.form.control.events.CellClickListener; import kd.bos.form.control.events.RowClickEvent; import kd.bos.form.control.events.RowClickEventListener; import kd.bos.form.events.HyperLinkClickEvent; import kd.bos.form.events.HyperLinkClickListener; import kd.bos.form.plugin.AbstractFormPlugin; public class EntryGridAllEvents extends AbstractFormPlugin implements CellClickListener, RowClickEventListener, HyperLinkClickListener { private final static String KEY_ENTRYENTITY = "entryentity"; @Override public void registerListener(EventObject e) { super.registerListener(e); // 侦听单据体表格事件 EntryGrid entryGrid = this.getView().getControl(KEY_ENTRYENTITY); entryGrid.addCellClickListener(this); // 单元格点击 entryGrid.addRowClickListener(this); // 行点击 entryGrid.addHyperClickListener(this); // 点击超链接单元格 } /****************** 数据行变化触发的事件 **************************/ @Override public void beforeAddRow(BeforeAddRowEventArgs e) { // 此事件暂未触发 } @Override public void afterAddRow(AfterAddRowEventArgs e) { // 添加、插入、复制新行完毕，给新行填写了默认值之后，触发此事件； // 插件可以在此修改新行字段默认值，或者调整界面上控件的状态 // 实例：DataModelChangeListener捕获此事件，给前端单据体增加新行 } @Override public void beforeDeleteRow(BeforeDeleteRowEventArgs e) { // 此事件暂未触发 } @Override public void afterDeleteRow(AfterDeleteRowEventArgs e) { // 删除行之后，触发此事件； // 插件可以在此事件，进行删除行后的数据同步处理，如刷新合计 // 实例：DataModelChangeListener捕获此事件，通知前端单据体删除行及子单据体行 } @Override public void beforeDeleteEntry(BeforeDeleteEntryEventArgs e) { // 此事件暂未触发 } @Override public void afterDeleteEntry(AfterDeleteEntryEventArgs e) { // 单据体数据被清空后，触发此事件； // 插件可以在此事件进行数据同步处理； // 实例：DataModelChangeListener捕获此事件，给前端单据体增加新行 } @Override public void afterMoveEntryUp(AfterMoveEntryEventArgs e) { // 单据体行往上移动后，触发此事件； // 插件可以在此事件中，获知到被移动行的原始行号，进行数据同步处理； // 实例：DataModelChangeListener捕获此事件，给前端单据体表格下达行调整指令 } @Override public void afterMoveEntryDown(AfterMoveEntryEventArgs e) { // 单据体行往下移动后，触发此事件； // 插件可以在此事件中，获知到被移动行的原始行号，进行数据同步处理； // 实例：DataModelChangeListener捕获此事件，给前端单据体表格下达行调整指令 } /******************** 用户与单据体表格交互产生的事件 ***********************/ @Override public void cellClick(CellClickEvent arg0) { // 单据体焦点行、焦点单元格切换时，触发此事件： // 1. 通过点击鼠标，切换行、单元格时，触发事件； // 2. 按键盘上下左右键切换单元格，不触发事件，但是开始编辑单元格值，触发事件 // 插件可以在此事件，第一时间获取表格焦点单元格的变化，据此刷新界面控件状态； // 此事件与entryRowClick事件，先后触发，本事件在先； System.out.println(String.format("cellClick: row = %s; field = %s", arg0.getRow(), arg0.getFieldKey())); } @Override public void entryRowClick(RowClickEvent evt) { // 单据体焦点行、焦点单元格切换时，触发此事件： // 1. 通过点击鼠标，切换行、单元格时，触发事件； // 2. 按键盘上下左右键切换单元格，不触发事件，但是开始编辑单元格值，触发事件 // 插件可以在此事件，第一时间获取表格焦点行的变化，据此刷新界面控件状态； System.out.println(String.format("entryRowClick: row = %s", evt.getRow())); } @Override public void cellDoubleClick(CellClickEvent arg0) { // 用户双击单据体中锁定的单元格时，触发此事件；如果单元格未锁定，双击不会触发此事件 // 插件可以响应此事件，打开焦点单元格字段编辑子界面 // 插件在触发此事件时，会先触发cellClick事件 System.out.println(String.format("cellDoubleClick: row = %s; field = %s", arg0.getRow(), arg0.getFieldKey())); } @Override public void entryRowDoubleClick(RowClickEvent evt) { // 用户双击单据体中锁定的单元格时，触发此事件；如果单元格未锁定，双击不会触发此事件 // 插件可以响应此事件，打开子界面 // 插件在触发此事件时，会先触发entryRowClick事件 System.out.println(String.format("entryRowDoubleClick: row = %s", evt.getRow())); } @Override public void hyperLinkClick(HyperLinkClickEvent arg0) { // 用户点击表格中超链接单元格时，触发此事件； // 插件响应用户点击事件，打开链接页面 // 前提：单据体字段，需要勾选"显示为超链"选项，且锁定； System.out.println(String.format("hyperLinkClick: page = %s; row = %s; field = %s", arg0.getPageIndex(), arg0.getRowIndex(), arg0.getFieldName())); } } ```