金蝶苍穹-操作插件开发
AI 摘要salmon-ai
本文详细解析了金蝶苍穹操作插件的基础概念、表单操作与实体操作的区别,以及 `AbstractOperationServicePlugIn` 的常用事件触发
官方文档:操作插件
笔记来源:https://vip.kingdee.com/school/detail/182500359560939520?campId=606437478945497344&productLineId=29&lang=zh-CN
一、总体介绍
操作插件整体介绍
-
概念
- 系统预置了一批操作,可以绑定在界面菜单、按钮上,如保存\提交
- 用户点击按钮时,即自动执行这些操作,完成特定的功能,如保存\提交
- 元数据语言描述的一系列通用模型,以灵活配置的方式快速响应业务需求
-
分类
- 表单操作:仅对表单界面及界面上的数据进行处理,如“新建”、“关闭”操作
- 实体操作:会写数据入库,只能配置在单据、基础资料上,如“保存”、“提交”操作

操作插件常用事件详解
插件基类kd.bos.entity.plugin. AbstractOperationServicePlugIn
| 事件 | 触发时机 | 应用场景 |
|---|---|---|
onPreparePropertys |
在单据列表上执行单据操作时,系统先根据传入的单据内码加载单据数据包;在加载单据数据包之前触发此事件。 | 插件需要在此事件中添加需要用到的字段。 |
onAddValidators |
系统预置的操作校验器加载完毕,执行校验之前触发此事件。 | 可以添加自定义的操作校验器。 |
beforeExecuteOperationTransaction |
操作校验通过之后,开启事务之前触发此事件。 | 事务处理的前置逻辑。 |
beginOperationTransaction |
操作校验通过,开启了事务,准备把数据提交到数据库之前触发此事件。 | 开始事务处理前,可以进行一些数据准备或校验。 |
endOperationTransaction |
数据已经提交到数据库之后,事务未提交之前触发此事件。 | 可以在事务提交之前做最后的数据检查或处理。 |
rollbackOperation |
操作事务提交失败,事务回滚之后触发此事件。 | 在事务回滚后处理逻辑,比如日志记录或者资源释放。 |
afterExecuteOperationTransaction |
操作执行完毕,事务提交之后触发此事件。 | 事务提交成功后的业务处理逻辑。 |
setContext |
设置上下文。 | 用于为操作设置相关上下文信息。 |
initializeOperationResult |
初始化操作结果集。 | 在操作结果生成前做一些准备工作,可能涉及结果数据的初始化或调整。 |
onReturnOperation |
操作结束时触发此事件。操作服务执行完毕,准备返回操作结果之前触发此事件。无论操作是否成功,都会触发此事件。 | 允许插件基于操作结果进行后续处理,或修改操作结果提示,释放资源。 |
二、自定义校验器onAddValidators
- 触发时机:
构建好操作校验器之后,执行操作校验之前,触发此事件; - 应用场景:
添加自定义校验器,实现采购方式为自费时,单价不能为空。 - 常见问题:
批量提交时,校验失败的数据不影响校验采购的数据。
java
// 操作插件继承基类AbstractOperationServicePlugIn
public class MyOperationPlugin extends AbstractOperationServicePlugIn {
// 在插件中要get或者set使用的字段,需要在此事件中预添加(加载)
@Override
public void onPreparePropertys(PreparePropertysEventArgs e) {
// 加载“采购方式”字段
e.getFieldKeys().add("kdec_buyway");
// 加载“采购单价”字段
e.getFieldKeys().add("kdec_pricefield");
}
/**
* 执行操作校验前,触发此事件
* @remark
* 插件可以在此事件中调整预置的操作校验器;或者增加自定义操作校验器
*/
@Override
public void onAddValidators(AddValidatorsEventArgs e) {
// 添加自定义的校验器
e.addValidator(new ReqSubmitValidator());
}
}
自定义校验器
java
// 自定义操作校验器
private class ReqSubmitValidator extends AbstractValidator {
@Override
public void validate() {
// 遍历所有的扩展数据实体
for (ExtendedDataEntity extendedDataEntity : this.getDataEntities()) {
// 获取数据实体
DynamicObject dataEntity = extendedDataEntity.getDataEntity();
// 获取单据体中的分录行数据集合
DynamicObjectCollection entrys = dataEntity.getDynamicObjectCollection("kdec_reqentryentity");
StringBuilder strbd = new StringBuilder();
// 遍历每一行分录数据
for (int i = 0; i < entrys.size(); i++) {
// 获取当前分录行数据
DynamicObject entryObj = entrys.get(i);
BigDecimal price = entryObj.getBigDecimal("kdec_pricefield");
int reqWay = entryObj.getInt("kdec_buyway");
// 当采购方式为自费时,检查采购单价是否小于0
if (reqWay == 1 && price.compareTo(BigDecimal.ZERO) < 1) {
// 如果发现不符合条件的分录行,将其行号记录下来
strbd.append(i + 1);
strbd.append("、");
}
}
// 如果有任何一行不符合条件,则生成错误消息,终止提交操作
if (strbd.length() > 0) {
// 删除最后一个多余的逗号
strbd.deleteCharAt(strbd.length() - 1);
// 添加错误消息并终止操作
this.addErrorMessage(extendedDataEntity,
String.format("操作插件校验:第%s行采购方式为自费时,采购单价不能小于 0!", strbd.toString()));
}
}
}
}
三、beforeExecuteOperationTransaction事件
- 触发时机:
操作校验通过之后,开启事务之前,触发此事件; - 应用场景:
做二次校验:币别只能为人民币或取消操作。
java
@Override
public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
// 仅在执行 "submit" 操作时进行校验
if (e.getOperationKey().equals("submit")) {
// 用于存储符合条件的扩展数据实体
List<ExtendedDataEntity> passDataEntities = new ArrayList<>();
// 获取所有待校验的扩展数据实体
List<ExtendedDataEntity> validExtDataEntities = e.getValidExtDataEntities();
// 遍历所有扩展数据实体,检查币别是否为人民币(CNY)
for (ExtendedDataEntity extendedDataEntity : validExtDataEntities) {
// 获取单据实体
DynamicObject doj = extendedDataEntity.getDataEntity();
// 使用的字段必须先在 onPreparePropertys 中注册
if (doj.getDynamicObject("kdec_currencyfield").get("number").equals("CNY")) {
// 如果币别为人民币,添加到通过列表
passDataEntities.add(extendedDataEntity);
} else {
// 如果币别不为人民币,则生成错误信息
Object pkId = doj.getPkValue(); // 获取主键值
ErrorLevel errorLevel = ErrorLevel.Error; // 错误级别为严重错误
// 构建错误信息对象
ValidationErrorInfo errInfo = new ValidationErrorInfo(
"", // 表名
pkId, // 主键ID
1, // 行号
2, // 列号
"BeforeExecuteOperationTransactionSample", // 错误编号
"送货日期检查", // 错误名称
"beforeExecuteOperationTransaction:币别只能是人民币", // 错误描述
errorLevel // 错误级别
);
// 添加错误信息到操作结果中
this.operationResult.addErrorInfo(errInfo);
}
}
// 如果没有符合条件的实体,取消操作
if (passDataEntities.size() == 0) {
e.setCancel(true); // 取消提交操作
} else {
// 如果有符合条件的实体,更新有效数据实体
e.getValidExtDataEntities().clear();
e.getValidExtDataEntities().addAll(passDataEntities);
}
}
// 调用父类的事件处理逻辑
super.beforeExecuteOperationTransaction(e);
}
四、beginOperaionTransaction事件
- 触发时机:
操作校验通过,开启了事务,数据提交数据库之前。 - 应用场景:
保证数据的一致性,如a数据保存异常了,同步让b数据保存失败。 - 常见问题:
切勿通过e.setCancelOperation(true)取消操作,调用此方法不会回滚已更新的关联数据
java
@Override
public void beginOperationTransaction(BeginOperationTransactionArgs e) {
// 仅在执行 "submit" 操作时进行处理
if (e.getOperationKey().equals("submit")) {
// 获取待操作的数据实体数组
DynamicObject[] dataEntities = e.getDataEntities();
// 遍历数据实体
for (int index = 0; index < dataEntities.length; index++) {
// 当索引为1时,尝试获取字段"kdec_company"
// 如果字段没有在 onPreparePropertys 中注册,会抛异常
if (index == 1) {
dataEntities[1].get("kdec_company");
}
}
}
// 调用父类的事件处理逻辑
super.beginOperationTransaction(e);
}
五、endOperationTransaction事件
- 触发时机:
数据已经提交到数据库之后,事务未提交之前,触发此事件; - 应用场景:
同步记录日志,记录日志时,也要提交失败。 - 常见问题:
不允许更改数据库了
java
@Override
public void endOperationTransaction(EndOperationTransactionArgs e) {
// 检查操作是否为 "submit" 操作
if (e.getOperationKey().equals("submit")) {
// 获取提交后的数据实体
DynamicObject[] dataEntities = e.getDataEntities();
// 创建一个列表来存储日志信息
ArrayList<DynamicObject> logs = new ArrayList<>();
// 遍历所有数据实体,记录操作日志
for (int index = 0; index < dataEntities.length; index++) {
// 创建一个新的日志对象
DynamicObject kdecMylog = BusinessDataServiceHelper.newDynamicObject("kdec_mylog");
// 将单据编号(主键)设置到日志中
kdecMylog.set("billno", dataEntities[index].getPkValue());
// 将日志对象添加到列表中
logs.add(kdecMylog);
}
// 保存日志操作
OperationResult result = SaveServiceHelper.saveOperate(
"save",
"kdec_mylog",
logs.toArray(new DynamicObject[logs.size()]),
OperateOption.create()
);
// 如果保存日志失败,抛出异常,触发事务回滚
if (!result.isSuccess()) {
throw new KDException("记录日志失败");
}
}
// 调用父类的事件处理逻辑
super.endOperationTransaction(e);
}
六、rollbackOperation事件
- 触发时机:
操作事务提交失败,事务回滚之后触发此事件; - 应用场景:
事务事件begin/endOperationTransaction中抛出异常时,发送消息给某用户处理bug - 常见问题:
如果是一些网络问题,可以在回滚事件中再次执行操作。
java
@Override
public void rollbackOperation(RollbackOperationArgs e) {
// 获取触发事务回滚的实体数据
DynamicObject[] dataEntities = e.getDataEntities();
// 创建消息对象,设置消息类型为警告
MessageInfo messageInfo = new MessageInfo();
messageInfo.setType(MessageInfo.TYPE_WARNING);
// 获取当前用户ID并添加到接收者列表中
ArrayList<Long> receivers = new ArrayList<>();
receivers.add(UserServiceHelper.getCurrentUserId());
messageInfo.setUserIds(receivers);
// 设置消息发送者的相关信息
messageInfo.setSenderName("系统发送");
messageInfo.setSenderId(UserServiceHelper.getCurrentUserId());
// 设置相关业务实体、操作、标签等信息
messageInfo.setEntityNumber("kdec_reqbill"); // 实体编号
messageInfo.setOperation("submit"); // 操作类型
messageInfo.setTag("提交异常"); // 标签
// 设置公共账号及消息内容
messageInfo.setPubaccNumber("flowassist");
messageInfo.setContent("采购申请单提交异常");
// 发送消息通知到消息中心
MessageCenterServiceHelper.sendMessage(messageInfo);
// 调用父类的事件处理逻辑
super.rollbackOperation(e);
}
七、afterExecuteOperationTransaction事件
- 触发时机:
操作执行完毕,事务提交之后,触发此事件; - 应用场景:
该事件执行记录日志失败时,不会回滚提交逻辑。
java
@Override
public void afterExecuteOperationTransaction(AfterOperationArgs e) {
// 检查操作是否为提交操作
if (e.getOperationKey().equals("submit")) {
// 获取提交操作的数据实体
DynamicObject[] dataEntities = e.getDataEntities();
// 创建一个列表来存储日志记录
ArrayList<DynamicObject> logs = new ArrayList<>();
// 遍历数据实体并为每个实体生成日志
for (int index = 0; index < dataEntities.length; index++) {
// 生成新的日志对象,提交之后,同步记录采购申请单的操作记录
DynamicObject kdecMylog = BusinessDataServiceHelper.newDynamicObject("kdec_mylog");
// 设置日志的单据编号
kdecMylog.set("billno", dataEntities[index].getPkValue());
// 添加日志到列表中
logs.add(kdecMylog);
}
// 直接保存日志记录,不受事务保护
SaveServiceHelper.save(logs.toArray(new DynamicObject[logs.size()]));
}
// 调用父类的事件处理逻辑
super.afterExecuteOperationTransaction(e);
}
评论
0 条—
还没有评论,来说第一句