苍穹插件常用事件与方法

1、常用方法

1. getView 获取动态表单界面视图模型接口IFormView的实例
2. getModel 获取动态表单界面数据模型接口IDataModel的实例
3. getPageCache 获取页面缓存管理器，存取数据到缓存中
4. getControl 获取界面上的控件 addClickListeners 注册插件，监听按钮点击事件
5. addItemClickListeners 注册插件，监听子菜单项点击事件

2、设置默认值

//key为修改组件的编号，value修改后的值
this.getModel().setValue("key",value);

3、获取创建人userId和部门Id

String userId = RequestContext.get().getUserId();
long deptId = UserServiceHelper.getUserMainOrgId(Long.valueOf(userId));

4、常用表单插入事件

1. preOpenForm
   时机：系统收到showForm指令，显示界面前，准备构建界面显示参数时，触发此事件。
   场景：此事件触发时，新界面还没有显示出来，可以在此事件，取消界面的显示，或者修改显示参数。

2. registerListener
   时机：用户与界面上的控件进行交互时，即会触发此事件。
   场景：建议在此事件，侦听各个控件的插件事件

public class RegisterListenerSample extends AbstractFormPlugin implements ItemClickListener, ClickListener, RowClickEventListener, TreeNodeClickListener {
	
	private final static String KEY_MBAR = "tbmain";
	private final static String KEY_BARITEM1 = "baritem1";
	private final static String KEY_BUTTON1 = "buttonap1";
	private final static String KEY_ENTRYENTITY = "entryentity";
	private final static String KEY_TREEVIEW1 = "treeviewap1";
	
	@Override
	public void registerListener(EventObject e) {
		super.registerListener(e);
		
		// 侦听各控件的插件事件，传入实现了事件接口的插件实例
		
		// 主菜单按钮点击
		Toolbar mbar = this.getView().getControl(KEY_MBAR);
		mbar.addItemClickListener(this);
		
		// 按钮点击
		Button button = this.getView().getControl(KEY_BUTTON1);
		button.addClickListener(this);
		
		// 单据体行点击
		EntryGrid entryGrid = this.getView().getControl(KEY_ENTRYENTITY);
		entryGrid.addRowClickListener(this);
		
		// 树型控件点击
		TreeView treeView = this.getView().getControl(KEY_TREEVIEW1);
		treeView.addTreeNodeClickListener(this);
	}
	
	@Override
	public void itemClick(ItemClickEvent evt) {
		super.itemClick(evt);
		if (StringUtils.equals(KEY_BARITEM1, evt.getItemKey())){
			// 事件处理代码略过
		}
	}
	
	@Override
	public void click(EventObject evt) {
		super.click(evt);
		Control source = (Control)evt.getSource();
		if (StringUtils.equals(KEY_BUTTON1, source.getKey())){
			// 事件处理代码略过
		}
	}
	
	@Override
	public void entryRowClick(RowClickEvent evt) {
		Control source = (Control) evt.getSource();
		if (StringUtils.equals(KEY_ENTRYENTITY, source.getKey())){
			// 事件处理代码略过
		}
	}
	
	@Override
	public void treeNodeClick(TreeNodeEvent evt) {
		// 事件处理代码略过
		TreeView treeView = (TreeView)evt.getSource();
		if (StringUtils.equals(KEY_TREEVIEW1, treeView.getKey())){
			// 事件处理代码略过
		}
	}
}

5、createNewData
时机：界面初始化或刷新，开始新建数据包时触发此事件；
场景：插件可以在此事件，自行创建界面数据包传回给系统，跳过系统内置的数据包创建过程。
1. 需要由外部传入完整地界面数据包，显示在界面上：就可以在此事件，先读取传入的数据包，然后传回表单，替代系统创建数据包的过程；
2. 动态添加字段时，系统内置创建的数据包，没有新字段的值，需要自行创建界面数据包；

6、afterCreateNewData
时机：界面初始化或刷新，新建表单数据包成功，并给字段填写了默认值之后，触发此事件；
场景：插件可以在此事件，重设字段的默认值。

7、beforeBindData
时机：面数据包构建完毕，开始生成指令，刷新前端字段值、控件状态之前，触发此事件；
场景：插件可以在此事件中，调整后台视图模型(IFormView)中的字段、控件属性，间接控制前端界面字段值、控件状态
特别说明：
本事件与afterCreateNewData事件的区别：

• 本事件比afterCreateNewData事件晚触发；
• 适合在afterCreateNewData事件中，修改数据模型中的字段值：
• 在afterCreateNewData改变字段值，数据修改标志为false；退出时，不会提示数据被修改；而在此事件中修改字段值，数据修改标志为true，退出时系统可能会提示数据被修改。
• 适合在beforeBindData中，调整视图模型中的控件属性；
• 单据界面插件，afterCreateNewData不是必然会被触发（与afterLoadData互斥），而beforeBindData必然触发

本事件与afterBindData事件的差别：

• 本事件比afterBindData早触发：在本事件之后，系统会调用内置的字段值绑定过程，随后才会触发afterBindData事件；
• beforeBindData事件，适合设置字段、控件的属性，以间接的控制前端字段值、控件状态的刷新过程；
• 在beforeBindData事件中设置控件状态会没有效果，因为系统随后会清空所有控件的状态；
• afterBindData事件，适合直接设置控件在前端表现的内容、状态；

8、afterBindData
时机：界面数据包构建完毕，生成指令，刷新前端字段值、控件状态之后，触发此事件；
场景：插件可以在此事件，根据各字段值数据，重新设置控件、字段的可用、可见性等。
注意：不要在此事件，修改字段值！

9、beforeItemClick
时机：用户点击菜单按钮后，在执行按钮绑定的操作前，触发此事件；
场景：插件可以在此事件，取消菜单绑定的操作；

import java.util.EventObject;

import kd.bos.dataentity.utils.StringUtils;
import kd.bos.form.control.events.BeforeItemClickEvent;
import kd.bos.form.plugin.AbstractFormPlugin;

public class BeforeItemClick extends AbstractFormPlugin {
	
	private final static String KEY_MAINBAR = "tbar_main";//菜单标识
	private final static String KEY_BARITEM_NEW = "baritem_new";//按钮标识
	
	@Override
	public void registerListener(EventObject e) {
		super.registerListener(e);
		// 侦听主菜单按钮点击事件
		this.addItemClickListeners(KEY_MAINBAR);
	}

	@Override
	public void beforeItemClick(BeforeItemClickEvent evt) {
		if (StringUtils.equals(KEY_BARITEM_NEW, evt.getItemKey())){
			// TODO 在此添加业务逻辑
		}
	}
}

10、itemClick
时机：用户点击菜单项时，触发此事件；
场景：插件可以在此响应自定义菜单项的点击处理。

import java.util.EventObject;

import kd.bos.dataentity.utils.StringUtils;
import kd.bos.form.control.events.ItemClickEvent;
import kd.bos.form.plugin.AbstractFormPlugin;

public class ItemClick extends AbstractFormPlugin {
	
	private final static String KEY_MAINBAR = "tbar_main";//菜单标识
	private final static String KEY_BARITEM_NEW = "baritem_new";//按钮标识
	
	@Override
	public void registerListener(EventObject e) {
		super.registerListener(e);
		// 侦听主菜单按钮点击事件
		this.addItemClickListeners(KEY_MAINBAR);
	}

	@Override
	public void itemClick(ItemClickEvent evt) {
		super.itemClick(evt);
		if (StringUtils.equals(KEY_BARITEM_NEW, evt.getItemKey())){
			// TODO 在此添加业务逻辑
		}
	}
}

11、beforeDoOperation
时机：用户点击按钮、菜单，执行绑定的操作逻辑前，触发此事件
场景：1、提示确认信息；2、校验数据，取消操作的执行；3、传递给自定义操作参数给操作服务、操作插件；

表单beforeDoOperation事件与操作校验器的区别：

1、运行时机不同

• 表单beforeDoOperation事件， 是由表单触发的，只有在表单上执行操作时，才会被触发；后台直接操作服务，不会触发此事件；数据校验放在这个事件，有可能漏过；
• 操作校验器，是由微服务层操作引擎执行的，不管是在表单上执行操作，还是后台调用操作服务，都会执行微服务层操作引擎，都会执行操作校验器；

2、适用操作类型不同

• 操作分为两种大类：表单操作：对界面进行处理，如关闭界面；实体操作：更新数据库，如保存；
• 只有实体操作，才允许配置操作校验
• 对普通的表单操作进行数据校验，只能使用表单插件beforeDoOperation事件；

3、控制颗粒度不同

• 批量操作时，操作校验器，对批量数据进行逐个校验，略过校验失败的数据，继续执行校验成功数据；
• 表单beforeDoOperation事件，只能整体取消操作，不能对批量数据进行区分；

注意：对操作进行数据校验，尽可能配置操作校验器、或使用操作插件，而不是使用表单beforeDoOperation事件。

public class BeforeDoOperation extends AbstractFormPlugin {
	
	final static String KEY_OPKEY = "myoperation";//操作标识
	
	@Override
	public void beforeDoOperation(BeforeDoOperationEventArgs args) {
		super.beforeDoOperation(args);
		
		FormOperate formOperate = (FormOperate)args.getSource(); 
		if ( StringUtils.equals(KEY_OPKEY, formOperate.getOperateKey())){
			// TODO 在此添加业务逻辑
			//取消操作
			args.setCancel(true);
		}
	}
}