金蝶苍穹-操作插件开发

2024-08-20后端6 分钟599 次阅读
AI 摘要salmon-ai

本文详细解析了金蝶苍穹操作插件的基础概念、表单操作与实体操作的区别,以及 `AbstractOperationServicePlugIn` 的常用事件触发

官方文档:操作插件
笔记来源:https://vip.kingdee.com/school/detail/182500359560939520?campId=606437478945497344&productLineId=29&lang=zh-CN

一、总体介绍

操作插件整体介绍

  • 概念

    • 系统预置了一批操作,可以绑定在界面菜单、按钮上,如保存\提交
    • 用户点击按钮时,即自动执行这些操作,完成特定的功能,如保存\提交
    • 元数据语言描述的一系列通用模型,以灵活配置的方式快速响应业务需求
  • 分类

    • 表单操作:仅对表单界面及界面上的数据进行处理,如“新建”、“关闭”操作
    • 实体操作:会写数据入库,只能配置在单据、基础资料上,如“保存”、“提交”操作
image.png

操作插件常用事件详解

插件基类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 条
登录 之后才能评论
—
还没有评论,来说第一句