金蝶苍穹-动态表单插件开发
AI 摘要salmon-ai
本文详细解析了金蝶苍穹动态表单插件开发的核心框架与常用事件,先说明动态表单插件基类 AbstractFormPlugin 及 MVC 结构中数据模型、视图模型和控制器的职责,
官方文档:动态表单插件
一、总体介绍
动态表单基类
动态表单:
- 最基本的交互界面,移动端表单、单据、基础资料、报表,都是基于动态表单。同样,表单的视图模型、数据模型、控件模型等,会被单据、基础资料这些业务对象继承扩展。
插件基类:
- 动态表单插件基类:
AbstractFormPlugin,已经实现了动态表单界面插件事件接口IFormPlugin,以及表单数据事件接口IDataModelListener,自定义的动态表单界面插件,必须派生自此类。
MVC 模型
数据模型(model)
- 表单的界面与数据分离,系统封装了数据模型对象来管理界面上显示的数据
this.getModel()方法获取到表单数据模型接口实例
作用:数据模型提供了数据查询和数据操作接口,最常用的就是获取字段值和设置字段值
| 方法 | 说明 |
|---|---|
getDataEntityType |
获取运行时表单实体元数据对象,又称为主实体模型 |
getProperty |
获取某个字段的属性对象 |
createNewData |
根据表单主实体模型,创建表单新的数据包,字段填写好默认值 |
getDataEntity |
获取表单数据包 |
updateCache |
提交当前表单数据包到缓存 |
getValue |
获取某个字段的值 |
setValue |
设置某个字段的值 |
batchCreateNewEntryRow* |
批量创建分录行 |
表单视图模型(IFormView)
- 界面显示在浏览器客户端,业务插件运行在服务端,插件通过往前端发送指令控制前端界面
- 通过系统封装的视图模型接口
IFormView,通过间接的访问、控制前端界面 this.getView()方法获取到表单视图模型接口实例,关注常用方法
| 方法 | 说明 |
|---|---|
getControl |
获取表单的控件实例 |
invokeOperation |
执行操作 |
updateView |
刷新界面 |
close |
关闭界面 |
setEnable |
控制控件的可用性 |
setVisible |
控制控件的可见性 |
showForm |
打开一个新的表单,作为本表单的子表单 |
returnDataToParent |
设置返回到父表单的返回值 |
showMessage |
单据内悬浮消息框,默认没有按钮,自动消失 |
showConfirm |
显示确认消息;用户确认完毕,会触发confirmCallBack事件 |
表单控制器(FormController)
动态表单页面加载或者交互过程中,表单控制器处理前端发送过来的各种请求,包括页面加载、页面点击交互过程的处理。
单据表单控制器(BillController)
继承于FormController,kd.bos.mvc.bill.BillController#loadData处理加载已有的表单数据包或新增单据时新数据包的创建过程,并打包更新给表单视图模型(IFormView),在数据包构建和视图刷新等过程中会调用特定的二开插件事件进行定制化干预。
其他表单控制器实例:
基础资料表单控制器:kd.bos.mvc.base.BaseController
移动端单据表单控制器:kd.bos.mvc.bill MobileBillController
报表表单控制器:kd.bos.mvc.report.ReportController
...
插件事件触发过程

事件分类

二、界面打开前事件(常用事件:preOpenForm)
界面打开前事件总览
| 事件 | 触发时机 | 应用场景 |
|---|---|---|
setPluginName |
显示界面,准备构建界面显示配置formConfig前,构建插件时触发此事件,传入脚本名称 |
只有 JS 代码插件会触发这个事件;Java 代码插件不触发。触发时机过早,无实际用处。 |
preOpenForm |
显示界面前,准备构建界面显示参数时,触发此事件 | 取消页面的打开,修改被打开页面的参数 |
loadCustomControlMetas |
显示界面前,构建界面显示参数时,触发此事件 | 向前端动态增加控件,相对复杂 |
preOpenForm 事件的用法
- 触发时机:
显示界面前,准备构建界面显示参数时,触发此事件。 - 应用场景:
界面打开前事件,常用于调整单据类型、页面布局、主题标识。根据条件判断是否打开页面。 - 常见问题:
此事件无法获取视图模型view以及设置表单控件的可见性。
java
@Override
public void preOpenForm(PreOpenFormEventArgs e) {
FormShowParameter fsp = (FormShowParameter) e.getSource();
// 设置显示参数 - 是否触发 TimerElapsed 事件
fsp.setListenTimerElapsed(true);
// 检查用户是否获授权,如未授权,取消界面显示
if (1 == 1) { // 这里条件语句应该根据实际逻辑进行修改
e.setCancel(true);
e.setCancelMessage("对不起,您无权访问此页面!");
} else {
// 设置显示参数 - 界面标题
fsp.setCaption("hello world");
}
super.preOpenForm(e);
}
三、界面初始化事件
常用事件:
- afterCreateNewData
- afterBindData
界面初始化事件总览
| 事件 | 触发时机 | 应用场景 |
|---|---|---|
setView |
表单视图模型初始化 | 二次开发用不上,后台服务向插件传入表单视图模型 IFormView 实例。 |
initialize |
表单视图模型初始化,创建插件后,触发此事件 | 表单界面在服务端是无状态的。界面加载完之后,表单及数据模型实例,会销毁并存到缓存中;页面交互过程会从缓存中重新构建这些模型实例,并从缓存中恢复数据 |
registerListener |
用户与界面上的控件交互时,触发此事件 | 用于注册监听器 |
getEntityType |
表单基于实体模型,创建数据包之前,触发此事件 | |
createNewData |
界面初始化或刷新,开始新建数据包时触发此事件 | |
afterCreateNewData |
界面初始化或刷新,新建数据包完毕后,触发此事件 | 常用于实体字段赋值 |
beforeBindData |
界面数据包构建完毕,开始生成指令,刷新前端字段值、控件状态之前,触发此事件 | |
afterBindData |
界面数据包构建完毕,生成指令,刷新前端字段值、控件状态之后,触发此事件 | 常用于修改控件的属性或状态 |
afterCreateNewData 事件
- 触发时机:
界面初始化或刷新,新建数据包完毕后,触发此事件; - 应用场景:
常用于新增页面,设置初始值; - 常见问题:
从列表打开查看页面时不触发该方法。下推、列表引入数据都不会触发该事件。
java
@Override
public void afterCreateNewData(EventObject e) {
// 1、简单类型(整数、文本等)字段 x 赋值
this.getModel().setValue("kdec_notes", "备注字段的默认值");
// 2、复杂类型(币别、组织、用户、基础资料)y 字段赋值
long currentUserId = UserServiceHelper.getCurrentUserId();
// 复杂字段赋值方式1:通过 id 赋值 - 推荐
this.getModel().setValue("kdec_requser", currentUserId);
// 复杂字段赋值方式2:通过对象赋值
DynamicObject user = BusinessDataServiceHelper.loadSingle(currentUserId, "bos_user");
this.getModel().setValue("字段标识y", user);
// 3、单据体赋值:第一行分录的申请数量默认值为 10
this.getModel().setValue("kdec_qty", 10, 0);
super.afterCreateNewData(e);
}
afterBindData 事件
- 触发时机:
界面数据包构建完毕之后,发送给前端之前。 - 应用场景:
设置可见性、设置锁定性、设置控件颜色、设置控件类型的值 - 常见问题:
禁止在此事件中修改字段值(无字段名的可以修改,常见于每次打开详情时,数据都是动态赋值的)
java
@Override
public void afterBindData(EventObject e) {
// 修改某字段/控件 x 的锁定性
this.getView().setEnable(false, "某字段标识x");
// 修改某字段/控件 y 的可见性
this.getView().setVisible(true, "字段标识y");
// 修改某控件(富文本)z 的控件值
RichTextEditor edit = (RichTextEditor) this.getView().getControl("控件标识z");
edit.setText("要设置的内容");
// 调用父类方法
super.afterBindData(e);
}
四、用户点击交互事件
常用事件:
- beforeItemClick
- itemClick
- beforeClick
- click
- beforeDoOperation
- afterDoOperation
- beforeF7Select
- propertyChanged
| 事件 | 触发时机 | 应用场景 |
|---|---|---|
beforeItemClick |
用户点击界面菜单按钮时,执行绑定的操作前,触发此事件 | 业务校验 |
itemClick |
用户点击界面菜单按钮时触发此事件 | 业务处理 |
beforeClick |
点击触发 click 事件前的校验事件 |
业务校验 |
click |
点击后触发操作事件 | 业务处理 |
beforeDoOperation |
用户点击按钮、菜单,执行绑定的操作前,触发此事件 | 业务校验 |
afterDoOperation |
用户点击按钮、菜单,执行完绑定的操作后,不论成功与否,均会触发此事件 | 操作后业务处理 |
customEvent |
触发自定义控件的定制事件 | 后端响应自定义控件前端的请求 |
beforeF7Selected |
用户点击基础资料字段的按钮,打开基础资料选择列表界面前,触发此事件 | 基础资料 F7 过滤 |
propertyChanged |
控件值更新事件 | 字段 a 变化时,同步修改字段 b |
beforeltemClick 事件
- 触发时机:
在正式执行itemclick事件之前 - 应用场景:
业务数据校验,如点击下载附件时,先校验附件是否为空。 - 常见问题:
工具栏是一个控件整体,只能注册工具栏的监听器
java
@Override
public void registerListener(EventObject e) {
// 工具栏项注册点击监听
Toolbar tbmain = this.getView().getControl("tbmain");
tbmain.addItemClickListener(this);
super.registerListener(e);
}
@Override
public void beforeItemClick(BeforeItemClickEvent evt) {
if (evt.getItemKey().equals("kdec_download")) {
// 附件字段取值(附件字段继承于多选基础资料,是集合类型对象)
DynamicObjectCollection atts = (DynamicObjectCollection) this.getModel().getValue("kdec_attachmentfield1");
if (atts.size() == 0) {
this.getView().showTipNotification("请先上传附件");
evt.setCancel(true);
}
}
super.beforeItemClick(evt);
}
itemClick 事件
- 触发时机:
用户点击工具栏项时,触发此事件。 - 应用场景:
点击下载附件时,执行下载附件字段里所有的附件的功能。
= 常见问题:
工具栏是一个控件整体,只能注册工具栏的监听器,不能对某个工具栏项进行监听。
java
@Override
public void registerListener(EventObject e) {
// 工具栏项注册点击监听
Toolbar tbmain = this.getView().getControl("tbmain");
tbmain.addItemClickListener(this);
super.registerListener(e);
}
@Override
public void itemClick(ItemClickEvent evt) {
if (evt.getItemKey().equals("kdec_download")) {
// 附件字段取值(附件字段继承于多选基础资料,是集合类型对象)
DynamicObjectCollection atts = (DynamicObjectCollection) this.getModel().getValue("kdec_attachmentfield1");
for (DynamicObject att : atts) {
// 附件字段的固定结构,要根据 fbasedataid 去获取每个附件的实体数据
DynamicObject attObj = att.getDynamicObject("fbasedataid");
String url = attObj.getString("url");
this.getView().download(url);
}
}
super.itemClick(evt);
}
beforeClick 事件
- 触发时机:
按钮点击事件dlick的一个前置事件。 - 应用场景:
业务校验,如有当前登录用户是创建人用户时,才能锁定/解锁单据按钮。
java
@Override
public void registerListener(EventObject e) {
// 获取按钮控件并注册点击监听器
Button button = this.getView().getControl("kdec_buttonap");
button.addClickListener(this);
super.registerListener(e);
}
@Override
public void beforeClick(BeforeClickEvent evt) {
if (evt.getSource() instanceof Button) {
Button button = (Button) evt.getSource();
String key = button.getKey();
// 处理按钮的点击事件
if (key.equals("kdec_lock") || key.equals("kdec_unlock")) {
DynamicObject creator = (DynamicObject) this.getModel().getValue("creator");
long currentUserId = UserServiceHelper.getCurrentUserId();
// 校验当前用户是否为创建人
if (creator.getLong("id") != currentUserId) {
this.getView().showTipNotification("当前用户不是创建人用户");
evt.setCancel(true);
}
}
}
super.beforeClick(evt);
}
click 事件
- 触发时机:
用户点击文本字段的按钮或者按钮控件时,触发此事件。 - 应用场景:
按钮点击时需要执行的业务,比如创建人用户点击锁定/解锁整个采购申请单。
java
@Override
public void registerListener(EventObject e) {
// 获取锁定和解锁按钮,并注册点击监听器
Button lock = this.getView().getControl("kdec_lock");
lock.addClickListener(this);
Button unlock = this.getView().getControl("kdec_unlock");
unlock.addClickListener(this);
super.registerListener(e);
}
@Override
public void click(EventObject evt) {
if (evt.getSource() instanceof Button) {
Button button = (Button) evt.getSource();
String key = button.getKey();
if (key.equals("kdec_lock")) {
// 锁住工具栏面板和内容区面板
this.getView().setEnable(false, new String[] {"titlepanelflex", "contentpanelflex"});
this.getView().setVisible(false, new String[] {"titlepanelflex", "contentpanelflex"});
// 记录锁定状态,并修改保存成功的提示
this.getModel().setValue("kdec_iflock", true);
OperateOption saveOp = OperateOption.create();
saveOp.setVariableValue(OperateOptionConst.SHOWMESSAGE, "false");
this.getView().invokeOperation("save", saveOp);
this.getView().showSuccessNotification("已锁住当前表单");
} else if (key.equals("kdec_unlock")) {
// 解锁工具栏面板和内容区面板
this.getView().setEnable(true, new String[] {"titlepanelflex", "contentpanelflex"});
this.getView().setVisible(true, new String[] {"titlepanelflex", "contentpanelflex"});
// 取消锁定状态
this.getModel().setValue("kdec_iflock", false);
OperateOption saveOp = OperateOption.create();
saveOp.setVariableValue(OperateOptionConst.SHOWMESSAGE, "false");
this.getView().invokeOperation("save", saveOp);
this.getView().showSuccessNotification("已解锁当前表单");
}
}
super.click(evt);
}
beforeDoOperation 事件
- 触发时机:
用户点击按钮、菜单,执行绑定的操作逻辑前,触发此事件; - 应用场景:
修改操作参数,操作前校验,如分录中的采购方式为自费时,采购单价不能小于0
java
@Override
public void beforeDoOperation(BeforeDoOperationEventArgs args) {
if (args.getSource() instanceof Submit) {
Submit opp = (Submit) args.getSource();
if (opp.getOperateKey().equals("submit")) {
// 获取采购申请单实体数据
DynamicObject dataEntity = this.getModel().getDataEntity(true);
// 获取采购信息单据体数据
DynamicObjectCollection dynamicObjectCollection =
dataEntity.getDynamicObjectCollection("kdec_reqentryentity");
StringBuilder strbd = new StringBuilder();
for (int i = 0; i < dynamicObjectCollection.size(); i++) {
// 各分录行数据
DynamicObject entryObj = dynamicObjectCollection.get(i);
BigDecimal price = entryObj.getBigDecimal("kdec_pricefield");
int reqWay = entryObj.getInt("kdec_buyway");
// 采购方式为自费时,采购单价不能小于0
if (reqWay == 1 && price.compareTo(BigDecimal.ZERO) < 0) {
strbd.append(i + 1).append("、");
}
}
if (strbd.length() > 0) {
strbd.deleteCharAt(strbd.length() - 1);
this.getView().showErrorNotification(
String.format("第%s行采购方式为自费时,采购单价不能小于0", strbd.toString())
);
// 取消提交操作
args.setCancel(true);
}
}
}
super.beforeDoOperation(args);
}
afterDoOperation 事件
- 触发时机:
用户点击按钮、菜单,执行完绑定的操作后,不论成功与否,均会触发此事件。 - 应用场景:
如提交后自动审核通过。
java
@Override
public void afterDoOperation(AfterDoOperationEventArgs afterDoOperationEventArgs) {
// 操作后触发,无事务保护,不管成功与否都会执行
if ("submit".equals(afterDoOperationEventArgs.getOperateKey()) &&
afterDoOperationEventArgs.getOperationResult() != null &&
afterDoOperationEventArgs.getOperationResult().isSuccess()) {
// 如果提交的结果是成功的话,直接审核通过
this.getView().invokeOperation("audit");
}
super.afterDoOperation(afterDoOperationEventArgs);
}
beforeF7Select 事件
- 触发时机:
用户点击基础资料字段的按钮,打开基础资料选择列表界面前,触发此事件 - 应用场景:
物料选择弹出的F7列表数据只保留编码前缀为Item的物料的数据
java
@Override
public void registerListener(EventObject e) {
// 注册监听基础资料字段的 F7 选择事件
BasedataEdit basedataEdit = this.getView().getControl("基础资料字段标识");
basedataEdit.addBeforeF7SelectListener(this);
super.registerListener(e);
}
@Override
// F7 列表弹出前事件,常用于 F7 过滤
public void beforeF7Select(BeforeF7SelectEvent beforeF7SelectEvent) {
String name = beforeF7SelectEvent.getProperty().getName();
// 对指定的基础资料字段进行过滤
if ("kdec_materiel".equals(name)) { // "kdec_materiel" 为基础资料字段标识
// 创建过滤器,只保留物料编码前缀为 "Item" 的数据
List<QFilter> qFilters = new ArrayList<>();
QFilter qFilter = new QFilter("number", QCP.like, "Item%");
qFilters.add(qFilter);
// 设置自定义过滤条件
beforeF7SelectEvent.setCustomQFilters(qFilters);
}
super.beforeF7Select(beforeF7SelectEvent);
}
propertyChanged 事件
- 触发时机:
文本、整数等简单类型字段需要开启字段的“即时触发值更新”,并且要鼠标失去焦点;如果是基础资料或者其他复杂类型字段,则更改数据时,即触发值更新。 - 应用场景:
监控某字段变更时,同步处理其他业务逻辑。如部门自动变更时,自动带出公司字段的值。
java
@Override
public void propertyChanged(PropertyChangedArgs e) {
// 当指定字段的值变化时触发,例如当部门字段值变更时,自动带出公司
String name = e.getProperty().getName();
// 判断是否为 "kdec_department" 字段的变化
if (name.equals("kdec_department")) {
// 获取变化后的部门值
ChangeData[] changeSet = e.getChangeSet();
DynamicObject department = (DynamicObject) changeSet[0].getNewValue();
// 根据部门获取公司信息
Map<String, Object> companyFromOrg = OrgUnitServiceHelper.getCompanyfromOrg(department.getPkValue());
// 将获取到的公司信息设置到 "kdec_company" 字段中
this.getModel().setValue("kdec_company", companyFromOrg.get("id"));
}
super.propertyChanged(e);
}
小结
1、按钮标签点击事件:(before)click事件
2、工具栏项点击事件:(before)itemclick点击事件
3、beforeDoOperation事件/afterDoOperation事件(按钮和菜单项绑定操作才会触发)
4、值更新事件触发前提条件?
答:文本、整数等简单类型字段需要开启字段的“即时触发值更新”,并且要鼠标失去焦点;如果是基础资料或者其他复杂类型字段,则更改数据时,即可触发值更新事件。
五、界面关闭事件
界面关闭事件总览
| 事件 | 触发时机 | 应用场景 |
|---|---|---|
beforeClosed |
界面关闭之前触发此事件 | 页面关闭前取消数据更新校验 |
destroy |
界面关闭后,释放资源时,触发此事件 | destory事件触发时,表单上下文环境可能已经被销毁,因此,不要在此事件中试图访问表单信息。 |
pageRelease |
界面关闭后,释放资源时,触发此事件 | 插件可以在此事件,释放插件创建的资源 |
beforeClosed 事件的用法
- 触发时机:
界面关闭之前触发此事件 - 应用场景:
页面关闭前取消数据更新校验或者取消页面关闭。
java
@Override
public void beforeClosed(BeforeClosedEvent e) {
// 设置为 false,退出时不提示数据改变(此属性只在单据表单插件上有效)。
e.setCheckDataChange(false);
// e.setCancel(true);
super.beforeClosed(e);
}
评论
0 条—
还没有评论,来说第一句