# 变更记录
| 产品版本 | 更新内容 | 更新日期 |
| --- | --- | --- |
| V6.0.1 | 新增了通过开关控制表头字段合并/不合并展示的功能，满足用户个性化展示表格数据的需求 | 2023年10月25日 |
| V6.0.1 | 优化了表格复制功能，支持了表格复制单元格文本内容的功能，满足了用户想要复制单元格中部分文本的需求 | 2023年10月25日 |
| V6.0.1 | 新增了通过框选中几个单元格，自动对框选单元格进行求和与计算平均值的功能，满足了用户对数据快速计算的需求 | 2023年10月25日 |
| V6.0.5 | 新增“列宽显示模式”的属性，支持对表格设定“固定列宽”，设定后不再受主题和个人设置的列宽显示模式的影响，满足业务严格控制表格列宽的需求 | 2024年1月11日 |
| V6.0.6 | 支持了列表子表格高度自适应功能，满足用户希望根据内容高度来展示子表的需求 | 2024年1月24日 |
| V7.0.1 | 优化了表格内容复制功能，当复制非连续单元格时，按照单元格原行列位置进行粘贴，提升用户体验 | 2024-10-24 |
# 1 功能介绍
以表格列表形式展示单据的数据。很多属性和单据上是一样的，这里只介绍列表中特有的属性。
这里分为两种形式
* 列表设计器，列表的映射实体是确定的，就是当前的单据实体，不需要配置单据实体和字段映射关系。
* 单据列表控件，表单中使用列表，需要配置单据实体和字段映射关系。
# 2 控件对象
`kd.bos.list.IListView`
# 3 视觉展示
* 设计时视图
* 运行时视图
# 4 属性说明
## 4.1 通用属性
>通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976)
## 4.2 样式属性
>样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336)
## 4.3 业务属性
* 单据列表
| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 单据实体 | 弹框选择 | - | 选择绑定的单据实体 |
| 缺省视图 | 下拉 | 表格视图 | 配置展示的视图，分为表格视图和卡片视图 |
| 已选合计字段 | 弹框选择 | - | 配置已选合计字段 |
| 过滤条件 | 弹框选择 | - | 配置基础资料对应的过滤条件 |
| 查询方式 | 下拉 | IdQuery查询模式 | 配置查询方式,IdQuery |
| 繁忙提示 | 文本 | - | 长时间服务端请求时的提示信息 |
* 单头显示
| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 单头显示 | 复选框 | false | 设置分录字段在折叠面板中是否显示 |
| 折叠显示高 | 宽高选择器 | - | 设置折叠面板显示高度 |
| 折叠表单 | 弹框选择 | - | 配置折叠表单信息 |
其他业务属性和单据体类型，请参考[单据体](https://vip.kingdee.com/article/224093028678171392)
### 4.3.1 单头显示
单头显示默认折叠的是该条单据下的单据体，也可以通过设置折叠表单来修改成要展示的页面。
### 4.3.2 行高自适应
表格级属性，多行多语言字段、多行文本支持较好，文本、大文本、基础资料和多语言文本可以换行，其他字段如金额、数字等由于规范不会换行。
设置行高自适应后，合计行的高度会取默认的设置的行高。
注意：*行融合下该属性不会生效*
### 4.3.3 列宽自适应
列表默认有列宽自适应功能，详情请参考[列宽自适应](https://vip.kingdee.com/article/167943096242927360)
支持设计器中配置单个表格的列宽规则
### 4.3.4 用户个性化数据
* 列宽: 用户拖拽过的列宽，关闭表单，该数据会存储在服务端，下次再打开该列表将是拖拽过的列宽。
* 每页显示条数：用户修改每页显示条数，关闭表单，该数据会存储在服务端，下次再打开该列表会每页将以上次关闭的每页条数显示。
### 4.3.5 表格设置
列表右上角齿轮按钮打开，用户级别的个性化设置。
* 只显示单据头 （只会显示单据头字段）
* 设置列对齐方式 （居中、居右还是居左）
* 设置冻结列 （设置后该列会固定在左侧）
* 设置隐藏列 (该列将会被隐藏)
* 上移、下移 （改变列的显示顺序）
### 4.3.6 缺省视图
缺省视图分为表格视图和卡片视图，表格视图是以表格的形式展示数据，卡片视图是以卡片的形式展示，点击工具栏右侧的按钮图标可以切换
表格视图：
卡片视图：
### 4.3.7 单头字段合并
列表默认情况下，单头字段会自行合并，在较少数据行合并时体验尚佳，但数据过多时因合并导致的空白行会过多，体验大打折扣。为了优化不同的数据下显示体验，此次在表格设置中增加“单头字段合并”控制选项，可以控制单头字段是否合并，默认开启合并。
* 开启单头字段合并效果
* 关闭单头字段合并效果
### 4.3.8 表格复制
复制规则优先对更小范围粒度的生效，目前支持复制的粒度有：单元格文本内容，单个单元格内容，范围框选，数据行
所以复制的生效优先级为：
单元格文本内容 > 单个单元格内容 > 范围框选 > 数据行
**单元格文本内容复制**
在单元格中拖选选中某几个文字时，按Ctrl + C 或者右键复制时可以仅复制拖选文字的内容。需要注意的是，如果拖选范围超过一个单元格，则变成框选效果
**单个单元格内容复制**
点击某个单元格高亮，按Ctrl + C 可以复制这个单元格内容
**范围框选复制**
范围框选后，按Ctrl+ C 或者右键复制，可以复制出框选范围的内容；框选多个范围时（按住Ctrl可以进行连续框选），复制出来的内容会保留单元格位置的相对关系，这样复制出来的内容粘贴到其他地方也可以保留框选的位置关系
比如以下界面复制，粘贴时中间会有一个空白列占位，保持原有的位置关系
粘贴结果：
**行复制**
点击勾选框选中行，在没有选中单元格的情况下，按住Ctrl+ C可以复制整行数据
### 4.3.9 框选合计
表格支持框选合计功能，进行范围框选时，可以对框选范围的数值类单元格进行求和和计算平均值。列表框选合计默认关闭，可以在表格设置面板中点击“选项”下“框选合计”开关选择开启。
配置选项：
框选效果：
### 4.3.10 折叠高度自适应
开启单头显示属性时，折叠区域的高度是固定的，开启该属性后，会根据折叠区域内容的高度去自适应，自适应的最大高度不会超过表体可显示的高度。
配置选项：
显示效果：
# 5 单据列表接口介绍
## 5.1 控件编程模型
### 5.1.1 控件编程模型定义
列表视图模型IListView，派生自表单视图模型[IFormView](https://vip.kingdee.com/article/221658844018031616)，增加了列表访问方法：
```java
package kd.bos.list;
public interface IListView extends IFormView {
```
在列表界面插件(AbstractListPlugin)中，通过this.getView()，返回的是ListView实例，该实例即可以转为IFormView接口，也可以转为IListView接口：
```java
package kd.bos.plugin.sample.bill.list.bizcase;
import kd.bos.form.IFormView;
import kd.bos.list.IListView;
import kd.bos.list.plugin.AbstractListPlugin;
public class ListViewSample extends AbstractListPlugin {
private void getListView(){
IFormView formview = this.getView();
IListView listview = (IListView)this.getView();
}
}
```
### 5.1.2 控件方法清单
列表视图模型接口IListView，在动态表单视图模型接口[IFormView](https://vip.kingdee.com/article/221658844018031616)基础上，新增加如下方法：
| 方法 | 说明 |
| --- | --- |
| getBillFormId | 获取列表界面绑定的单据 |
| setBillFormId | 设置列表界面绑定的单据
内部方法，插件请勿调用 |
| getListModel | 获取列表数据模型 |
| getFocusRow | 获取当前焦点行号，整数 |
| getFocusRowPkId | 获取当前焦点行显示的单据数据内码 |
| getCurrentSelectedRowInfo | 获取当前焦点行数据详情，明细到单据体行、子单据体行 |
| getSelectedRows | 获取当前勾选了的全部行数据详情 |
| getCurrentListAllRowCollection | 获取列表全部行数据详情 |
| clearSelection | 清除所选的行 |
| returnLookupData | 把当前所选行，返回给父界面 |
| refresh | 刷新列表，重新取数 |
| getSelectedMainOrgIds | 获取选中的主业务组织 |
| setSelectedMainOrgIds | 设置选中的主业务组织 |
| export | 引出 |
| importData | 引入 |
| getTreeListView | 获取树形列表视图模型ITreeListView
仅适用于左树右表列表模式 |
| focusRootNode | 树形列表，切换到根节点 |
## 5.2 数据模型
### 5.2.1 属性对象
单据列表界面，包含了两个层次的数据模型：
* 表单数据模型[IDataModel](https://vip.kingdee.com/article/221682121515831552)：据此访问列表控件所在的表单数据，在动态表单章节介绍：
列表界面，除了单据列表控件，还可以增加自定义字段，需通过表单数据模型IDataModel访问这些自定义字段的值；
* 列表数据模型IListModel：据此访问单据列表控件中的数据。
```java
package kd.bos.entity.datamodel;
public interface IListModel {
```
表单数据模型IDataModel与列表数据模型IListModel，分别有各自的实现类及实例，没有派生关系，不能互相转换。
单据列表插件([AbstractListPlugin](https://vip.kingdee.com/article/223814038843400192))，可以如下代码，分别获取表单数据模型IDataModel、列表数据模型IListModel的实例：
```java
package kd.bos.plugin.sample.bill.list.bizcase;
import kd.bos.entity.datamodel.IDataModel;
import kd.bos.entity.datamodel.IListModel;
import kd.bos.list.IListView;
import kd.bos.list.plugin.AbstractListPlugin;
public class ListModelSample extends AbstractListPlugin {
private void getListModel(){
IDataModel formmodel = this.getModel();
IListModel listmodel = ((IListView)this.getView()).getListModel();
}
}
```
### 5.2.2 方法清单
IListModel提供的方法如下：
IListModel提供的方法如下：
| 方法 |
| --- |
| getDataEntityType |
| setDataEntityType |
| setPageId |
| getData |
| getQingData |
| setEntityId |
| getEntityId |
| setLookup |
| isLookup |
| getDataCount |
| setFilterParameter |
| setListFields |
| getProvider |
| setProvider |
| getPkFields |
| setPkFields |
| setFieldCotnrolRules |
| getQueryResult |
| getRegisterPropertyListeners |
| setRegisterPropertyListeners |
| getSelectFields |
| setSelectFields |
## 5.3 插件事件
详情请参考[标准单据列表插件事件](https://vip.kingdee.com/knowledge/specialDetail/218022218066869248?category=238607792339561472&id=223887352173535232)
