# 列表插件模型

##  插件模板

- 列表分为PC列表和移动列表，PC列表分为普通列表，分组列表和树型列表
- 普通列表的插件基类是kd.bos.list.plugin.AbstractListPlugin,
- 移动列表插件基类是kd.bos.list.plugin.AbstractMobListPlugin,
- 对于分组列表的开发从kd.bos.list.plugin.StandardTreeListPlugin开始，
- 树型列表继承kd.bos.list.plugin.AbstractTreeListPlugin



## 场景与示例

###### 过滤容器初始化

场景：需要动态增加过滤字段，或者需要自己生成虚拟字段，自己解析的场景

```java
@Override
	public void filterContainerInit(FilterContainerInitArgs args) {
		System.err.println("filterContainerInit");
		FilterColumn filterColumn = args.getFilterColumn("datefield");
		filterColumn.setDefaultValues("2019-1-30", "2019-1-31");
		FilterColumn filterColumn2 = new FilterColumn("textfield");
		args.addFilterColumn(filterColumn2);
		CommonFilterColumn commonFilterColumn = new CommonFilterColumn("combofield");
		args.addFilterColumn(commonFilterColumn);
		SchemeFilterColumn schemeFilterColumn = new SchemeFilterColumn("combofield");
		args.addFilterColumn(schemeFilterColumn);
		super.filterContainerInit(args);
	}
```

 

###### 过滤值解析

场景：对于虚拟字段或者过滤字段间有级联的情况可以重写这个方法来处理，此处可以拿到过滤字段值做缓存在setFilter方法使用

```
   @Override
	public void filterContainerSearchClick(FilterContainerSearchClickArgs args) {
		System.err.println("filterContainerSearchClick");
		System.err.println(args.getFilterValue("datefield"));
		System.err.println(args.getFastFilterValues());
		System.err.println(args.getQFilter("datefield"));
		System.err.println(args.getSelectMainOrgIds());
		args.addConstFilter("datefield", CompareTypeEnum.TODAY);
		args.addFastFilter("textfield", "test");
		args.addFilter("textfield", CompareTypeEnum.EQUAL, "123");
		super.filterContainerSearchClick(args);
	}
```

 

###### 过滤容器控件弹窗

 场景：需要在常用过滤基础资料字段点击“更多”或者方案过滤基础资料字段输入框的弹窗增加过滤条件

```java
@Override
	public void filterContainerBeforeF7Select(BeforeFilterF7SelectEvent args) {
		System.err.println("filterContainerBeforeF7Select");
		if ("basedatafield2.name".equals(args.getFieldName()))
			args.addCustomQFilter(new QFilter("name", QFilter.equals, "test123"));

		super.filterContainerBeforeF7Select(args);
	}
```



###### 常用过滤基础资料字段取值

 场景：需要在常用过滤基础资料字段初始化时增加过滤条件

```java
@Override
	public void filterColumnSetFilter(SetFilterEvent args) {
		System.err.println("filterColumnSetFilter");
		if ("basedatafield2.name".equals(args.getFieldName()))
			args.addCustomQFilter(new QFilter("name", QFilter.equals, "test123"));

// 基础资料依赖于上面的选择字段orgfield1,将orgfield1的已选中值添加到basedatafield2
		if ("basedatafield2.name".equals(args.getFieldName())) {
			FilterColumnSetFilterEvent args2 = (FilterColumnSetFilterEvent) args;
			args.addCustomQFilter(new QFilter("name", QFilter.equals, args2.getCommonFilterValue("orgfield1.number")));
		}

		super.filterColumnSetFilter(args);
	}
```

 

###### 列表查询字段动态构造

 场景：多个列表共用一个列表插件的场景，需要动态增减字段，或者动态改变字段的可见性

```java
@Override
	public void beforeCreateListColumns(BeforeCreateListColumnsArgs beforecreatelistcolumnsargs) {
		ComboListColumn comboListColumn = new ComboListColumn();
		comboListColumn.setListFieldKey("combofield");
		MergeListColumn mergeListColumn = new MergeListColumn();
		mergeListColumn.setKey("mergelistcolumn");
		mergeListColumn.getItems().add(comboListColumn);
		beforecreatelistcolumnsargs.addListColumn(mergeListColumn);
		IListColumn listColumn = beforecreatelistcolumnsargs.getListColumn("textfield");
		System.err.println("beforeCreateListColumns");
		System.err.println(listColumn);
		System.err.println(beforecreatelistcolumnsargs.getDynamicTextListColumns());
		System.err.println(beforecreatelistcolumnsargs.getMergeListColumns());
		System.err.println(beforecreatelistcolumnsargs.getListGroupColumns());
		super.beforeCreateListColumns(beforecreatelistcolumnsargs);
	}
```

 

###### 过滤条件设置

 场景：单据需要增加固定过滤条件场景，对于基础资料不推荐使用，基础资料最好是写“个性化控制器”，其他情况优先使用设计器传值或设计器配置。

```java
@Override
	public void setFilter(SetFilterEvent e) {
		e.setCustomQFilter(new QFilter("combofield", "=", "1"));
	}
```



###### 数据包装

 场景：对于基础资料属性字段的字段值格式化用这个方法或者操作列设置字体颜色和根据条件修改文本字段内容等

```java
@Override
	public void packageData(PackageDataEvent e) {
		System.err.println("packageData");
		if (e.getSource() instanceof ListOperationColumnDesc) {
			List<OperationColItem> operationColItems = (List<OperationColItem>) e.getFormatValue();
			for (OperationColItem operationColItem : operationColItems) {
				operationColItem.setForeColor("green");
			}
		}
		else if (e.getSource() instanceof ColumnDesc) {
			ColumnDesc columnDesc = (ColumnDesc) e.getSource();
			if ("textfield".equals(columnDesc.getKey()) && "1".equals(e.getFormatValue()))
				e.setFormatValue("test");
		}
		super.packageData(e);
	}
```

 

###### 云之家聊天

 场景：取消云之家聊天

```java
@Override
	public void chat(ChatEvent e) {
		System.err.println("setFilter");
		// 取消云之家聊天
		e.setCancel(true);
		super.chat(e);
	}
```

 

###### 数据包装方法

 场景：动态修改非基础资料字段的值，注意不要修改基础资料的引用属性，因为会打乱缓存数据，此方法只适合非基础资料字段修改



```java
@Override
	public void beforePackageData(BeforePackageDataEvent e) {
		super.beforePackageData(e);
		for (DynamicObject object : e.getPageData()) { 
			object.set("test", "test");
		}
	}
```

 

###### 自定义取数

 场景：数据源不是来自于数据库，或者数据源来源于多个类似的单据场景，或者需要做一些数据的缓存的情况等

```java
@Override
	public void beforeCreateListDataProvider(BeforeCreateListDataProviderArgs args) {
		System.err.println("beforeCreateListDataProvider");
		args.setListDataProvider(new ListDataProvider(){

			@Override
			public DynamicObjectCollection getData(int start, int end) {
				int dataCount=selfQueryDataCount();
				int billDataCount=selfQueryBillDataCount();
				List<SummaryResult> summaryResults=selfQuerySummaryResult();
				
				// 自己的取数逻辑得到DynamicObjectCollection
				DynamicObjectCollection dynamicObjectCollection = selfQueryData(); 
				getQueryResult().setCollection(dynamicObjectCollection);
				getQueryResult().setDataCount(dataCount);
				getQueryResult().setBillDataCount(billDataCount);
				getQueryResult().setSummaryResults(summaryResults);
				
				return dynamicObjectCollection;
			}
			
		});
		super.beforeCreateListDataProvider(args);
	}
```





## API概览

 

**BillList**



| 事件名称                     | 对应控件监听                      | 说明                                                         |
| ---------------------------- | --------------------------------- | ------------------------------------------------------------ |
| billListHyperLinkClick       | addHyperClickListener             | 超链接点击                                                   |
| beforeCreateListColumns      | addCreateListColumnsListener      | 列创建                                                       |
| beforeCreateListDataProvider | addCreateListDataProviderListener | 自定义取数(注意不要修改基础资料的引用属性，因为会打乱缓存数据，此方法只适合非基础资料字段修改) |
| setFilter                    | addSetFilterListener              | 设置过滤条件                                                 |
| beforePackageData            | addBeforePackageDataListener      | 包装数据前，需要遍历这个数据包，用于格式化数据(注意不要修改基础资料的引用属性，因为会打乱缓存数据，此方法只适合非基础资料字段修改) |
| packageData                  | addPackageDataListener            | 包装数据，单元格填值，用于格式化数据                         |
| chat                         | addChatListener                   | 打开云之家监听                                               |

 

**FilterContainer**

| 事件名称                        | 对应控件监听                   | 说明                                                         |
| ------------------------------- | ------------------------------ | ------------------------------------------------------------ |
| filterContainerInit             | addFilterContainerInitListener | 过滤字段元数据初始化                                         |
| filterContainerSearchClick      | addSearchClickListener         | 查询，过滤条件第一次解析，过滤条件是界面上的初始过滤值       |
| filterContainerAfterSearchClick | addAfterSearchClickListener    | 最终查询条件解析后，可以在此事件得到最终解析后的过滤条件，然后做自定义处理 |
| filterContainerBeforeF7Select   | addBeforeF7SelectListener      | 常用过滤和方案过滤的F7监听                                   |

 

**CommonFilterColumn**

| 事件名称              | 对应控件监听          | 说明                                     |
| --------------------- | --------------------- | ---------------------------------------- |
| filterColumnSetFilter | addSetFilterListeners | 过滤字段上的基础资料字段过滤条件调整事件 |

 

**事件生命周期**

 

页面加载

1. beforeCreateListDataProvider
2. filterColumnSetFilter
3. filterContainerInit
4. beforeCreateListColumns
5. setFilter
6. packageData

 

点击查询

1. filterColumnSetFilter
2. filterContainerInit
3. filterContainerSearchClick
4. filterContainerAfterSearchClick
5. beforeCreateListColumns
6. beforeCreateListDataProvider
7. setFilter
8. packageData

 

**接口参数说明**

 

BeforeCreateListColumnsArgs

| **方法名**                | **说明**               |
| ------------------------- | ---------------------- |
| getListColumns            | 获取列表字段           |
| setListColumns            | 设置列表字段           |
| getListGroupColumns       | 获取分组字段           |
| setListGroupColumns       | 设置分组字段           |
| getMergeListColumns       | 获取合并列表字段       |
| getDynamicTextListColumns | 获取动态文本字段       |
| getListColumn             | 通过字段名获取列表字段 |
| addListColumn             | 添加列表字段           |

 

FilterContainerInitArgs

 

| **方法名**                  | **说明**               |
| --------------------------- | ---------------------- |
| getFilterContainerInitEvent | 获取过滤容器初始事件   |
| setFilterContainerInitEvent | 设置过滤容器初始事件   |
| getFastFilterColumns        | 获取快速过滤字段       |
| getCommonFilterColumns      | 获取常用过滤字段       |
| getSchemeFilterColumns      | 获取方案过滤字段       |
| getFilterColumn             | 通过字段名获取过滤字段 |
| addFilterColumn             | 添加过滤字段           |



FilterContainerSearchClickArgs

 

| **方法名**                                    | **说明**                         |
| --------------------------------------------- | -------------------------------- |
| getSearchClickEvent                           | 获取查询点击事件                 |
| setSearchClickEvent                           | 设置查询点击事件                 |
| getFastQFilters                               | 获取快速过滤条件                 |
| getCurrentCommonFilter                        | 获取当前常用过滤条件             |
| setCurrentCommonFilter                        | 设置当前点击的常用过滤条件       |
| getFilterValues                               | 过滤条件原始值                   |
| setFilterValues                               | 设置过滤条件原始值               |
| getEntryEntity                                | 获取当前选择的最小单位分录       |
| getFilterModel                                | 获取过滤模型                     |
| getFilterParameter                            | 获取常用过滤条件                 |
| setFilterParameter                            | 设置常用过滤条件                 |
| getFilterValue                                | 通过字段名获取过滤值             |
| getQFilter                                    | 通过字段名获取供ORM取数的QFilter |
| getSelectMainOrgIds                           | 获取选中组织                     |
| getFieldName                                  | 获取过滤字段控件映射的实体字段名 |
| addConstFilter                                | 添加常量过滤条件                 |
| addFilter                                     | 添加过滤条件(不包括快速过滤)     |
| addFastFilter(String fieldName, String value) | 添加快速过滤条件                 |

 

BeforeFilterF7SelectEvent

 

| **方法名**        | **说明**                             |
| ----------------- | ------------------------------------ |
| getRefEntityId    | 获取绑定的实体编码                   |
| setRefEntityId    | 设置绑定的实体编码                   |
| isCancel          | 是否取消                             |
| setCancel         | 设置是否取消                         |
| getSelectedIds    | 获取已选择的基础资料                 |
| isMulti           | 是否多选                             |
| getFieldName      | 映射的实体字段名                     |
| getRefPropKey     | 实际字段名(多级的情况下最后一级)     |
| setRefPropKey     | 设置实际字段名(多级的情况下最后一级) |
| getQfilters       | 获取过滤条件                         |
| setQfilters       | 设置过滤条件                         |
| getCustomQFilters | 获取插件设置的过滤条件               |
| setCustomQFilters | 设置插件设置的过滤条件(多个)         |
| addCustomQFilter  | 添加插件设置的过滤条件               |
| getMergeQFilters  | 获取最终合并的所有过滤条件           |

 

SetFilterEvent

 

| **方法名**                | **说明**                                             |
| ------------------------- | ---------------------------------------------------- |
| getQFilters               | 获取所有过滤条件(不包括权限相关的以及插件设置的过滤) |
| getCustomQFilters         | 获取插件设置的过滤条件                               |
| setCustomQFilters         | 设置插件设置的过滤条件(多个)                         |
| addCustomQFilter          | 添加插件设置的过滤条件                               |
| getMainOrgQFilter         | 获取主业务组织数据权限                               |
| setMainOrgQFilter         | 设置主业务组织数据权限                               |
| getSpecialDataPermQFilter | 获取特殊数据权限                                     |
| setSpecialDataPermQFilter | 设置特殊数据权限                                     |
| getDataPermQFilters       | 获取数据权限                                         |
| setDataPermQFilters       | 设置数据权限                                         |
| getOrderBy                | 获取排序                                             |
| setOrderBy                | 设置排序                                             |
| getFieldName              | 获取过滤字段控件映射的实体字段名                     |



HyperLinkClickArgs

 

| **方法名**             | **说明**           |
| ---------------------- | ------------------ |
| getHyperLinkClickEvent | 获取超链接点击事件 |
| setHyperLinkClickEvent | 设置超链接点击事件 |
| isCancel               | 是否取消           |
| setCancel              | 设置是否取消       |
| getFieldName           | 获取字段名         |
| getRowIndex            | 获取行索引         |



BeforeCreateListDataProviderArgs

 

| **方法名**          | **说明**       |
| ------------------- | -------------- |
| getListDataProvider | 获取取数接口类 |
| setListDataProvider | 设置取数接口类 |

 

PackageDataEvent

 

| **方法名**     | **说明**                          |
| -------------- | --------------------------------- |
| getRowData     | 获取当前行数据                    |
| setRowData     | 设置当前行数据                    |
| getFormatValue | 获取格式化的单元格数据            |
| setFormatValue | 设置格式化后的单元格数据          |
| isCancel       | 是否取消本行数据(rowData)输出     |
| setCancel      | 设置是否取消本行数据(rowData)输出 |

 

ChatEvent

 

| **方法名**                | **说明**               |
| ------------------------- | ---------------------- |
| isCancel                  | 是否取消云之家聊天     |
| setCancel                 | 设置是否取消云之家聊天 |
| getCurrentListSelectedRow | 获取当前记录行         |
| getFieldKey               | 当前字段key            |

 

分组和树型列表插件事件

 

| **方法名**          | **说明**                           |
| ------------------- | ---------------------------------- |
| initializeTree      | 树初始化事件                       |
| initTreeToolbar     | 树左侧工具栏初始化事件             |
| treeToolbarClick    | 树左侧工具栏点击事件               |
| beforeBuildTreeNode | TreeListView初始化TreeNode前调用   |
| expendTreeNode      | 树结点展开事件                     |
| refreshNode         | 树结点刷新事件                     |
| beforeTreeNodeClick | 树结点点击前事件                   |
| treeNodeClick       | 树结点点击事件                     |
| buildTreeListFilter | 设置树结点的过滤条件到右侧单据列表 |
| search              | 树结点搜索事件                     |

 
