OneCode3.0插件开发指南：注解驱动的UI功能扩展框架

前言：OneCode插件技术体系与优势

OneCode插件体系是基于Java注解驱动的扩展性框架，允许二次开发用户通过标准化的注解配置与业务逻辑实现，无缝扩展UI设计器功能。该技术体系具备三大核心优势：

技术功能特点

注解驱动开发 ：通过@EsbBeanAnnotation与@FParams注解完成插件注册与参数声明，无需XML配置
类型安全设计：强类型参数注入与返回值约束，编译期即可捕获类型错误
微内核架构：插件与核心引擎松耦合，支持热部署与独立升级
UI组件深度集成：直接操作UI组件属性（可见性、禁用状态、数据权限等）
业务流程嵌入 ：支持流程条件判断、活动权限控制等业务逻辑扩展

开发效率优势

零配置集成：注解自动扫描与注册，无需手动配置插件路径
标准化接口：统一的参数注入与结果返回模式，降低学习成本
即插即用：编译打包后放入指定目录即可生效
丰富的基础组件 ：内置8大类20+常用插件，覆盖大部分UI扩展场景

一、插件体系结构

1.1 整体架构

OneCode插件系统采用三层架构设计：

swift 复制代码

┌─────────────────────────────────────────┐
│            UI设计器前端层               │ ← 插件功能可视化配置
├─────────────────────────────────────────┤
│           插件运行时引擎层              │ ← 注解解析、参数注入、生命周期管理
├─────────────────────────────────────────┤
│           业务逻辑实现层                │ ← 用户开发的插件类（Java实现）
└─────────────────────────────────────────┘

1.2 包结构组织

插件开发包com.ds.esd.fun采用功能模块化组织：

bash 复制代码

com.ds.esd.fun
├── bar/           # 工具栏相关插件
├── bpm/           # 流程相关插件
├── component/     # 通用组件插件
├── condition/     # 条件判断插件
├── form/          # 表单相关插件
├── grid/          # 表格相关插件
├── item/          # 列表项插件
└── tab/           # 标签页插件

1.3 插件关系结构

less 复制代码

┌─────────────────────────────────────────────────────────────┐
│                     核心注解体系                            │
│  ┌──────────────────┐        ┌──────────────────────────┐  │
│  │ @EsbBeanAnnotation │       │       @FParams           │  │
│  └──────────┬───────┘        └──────────────┬───────────┘  │
└─────────────┼───────────────────────────────┼──────────────┘
              │                               │
┌─────────────▼───────────────┐ ┌─────────────▼───────────────┐
│      功能插件分类           │ │        参数类型体系         │
│ ┌─────────┐ ┌─────────────┐ │ │ ┌─────────┐ ┌─────────────┐ │
│ │组件控制  │ │流程条件判断 │ │ │ │ESDCOM   │ │GRIDCOM      │ │
│ ├─────────┤ ├─────────────┤ │ │ ├─────────┤ ├─────────────┤ │
│ │表格操作  │ │权限管理     │ │ │ │CURRFORMCOM│ │CURRBAR     │ │
│ └─────────┘ └─────────────┘ │ │ └─────────┘ └─────────────┘ │
└─────────────────────────────┘ └─────────────────────────────┘

二、核心注解与参数枚举

2.1 核心注解详解

@EsbBeanAnnotation

插件注册核心注解，用于将Java类标记为OneCode插件：

java 复制代码

@EsbBeanAnnotation(
    type = FormulaType.ESDCOM,  // 插件类型
    name = "隐藏组件"           // 插件显示名称
)

@FParams

参数注入注解，用于声明插件所需的输入参数：

java 复制代码

public HiddenCom(@FParams(type = FormulaParams.ESDCOM) List<Component> comIds) {
    // 构造函数实现
}

2.2 FormulaType枚举完整说明

枚举值	说明	应用场景
ESDCOM	组件操作类型	UI组件显示/隐藏/禁用等控制
GridRight	表格权限类型	表格行/列权限控制
BarRight	工具栏权限类型	工具栏按钮控制
ItemRight	列表项权限类型	下拉列表/单选框选项控制
TabRight	标签页权限类型	标签页显示/隐藏控制
FormRight	表单权限类型	表单组件权限控制
ExpressionCon	表达式条件类型	条件判断逻辑
WorkFlowCon	工作流条件类型	流程节点权限控制
UIRight	UI组件权限类型	UI组件高级控制
PageCon	页面条件类型	页面级条件判断

2.3 FormulaParams枚举完整说明

枚举值	说明	对应参数类型
ESDCOM	UI组件参数	List
GRIDCOM	表格组件参数	List
CURRBAR	当前工具栏参数	List
CURRFORMCOM	当前表单组件参数	List
CURRITEM	当前列表项参数	List
CURRTAB	当前标签页参数	List/List
EXPRESSION	表达式字符串参数	String/Object
ACTIVITYDEF	流程活动定义参数	List
CURRUICOM	当前UI组件参数	List

三、插件分类与功能详解

3.1 组件控制类插件

用于控制UI组件的可见性、禁用状态等基础属性。

3.1.1 隐藏组件 (HiddenCom)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.ESDCOM, name = "隐藏组件")
public class HiddenCom {
    public HiddenCom(@FParams(type = FormulaParams.ESDCOM) List<Component> comIds) {
        for (Component component : comIds) {
            if (component.getProperties() instanceof AbsUIProperties) {
                AbsUIProperties absUIProperties = (AbsUIProperties) component.getProperties();
                absUIProperties.setDisplay("none");  // 设置组件不可见
            }
        }
    }
}

功能：通过设置组件样式display:none隐藏指定UI组件适用场景：根据业务条件动态隐藏不需要的表单元素

3.1.2 隐藏UI组件 (HiddenUICom)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.UIRight, name = "隐藏组件")
public class HiddenUICom {
    public HiddenUICom(@FParams(type = FormulaParams.CURRUICOM) List<Component> comIds) {
        for (Component component : comIds) {
            if (component.getProperties() instanceof AbsUIProperties) {
                AbsUIProperties absUIProperties = (AbsUIProperties) component.getProperties();
                absUIProperties.setDisplay("none");
            }
        }
    }
}

功能：隐藏当前上下文的UI组件区别：与HiddenCom相比，参数类型为CURRUICOM，专注于当前上下文组件

3.2 表格操作类插件

专注于表格组件的权限控制与交互限制。

3.2.1 隐藏操作按钮 (HiddenRowBar)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.GridRight, name = "隐藏操作按钮")
public class HiddenRowBar {
    public HiddenRowBar(@FParams(type = FormulaParams.GRIDCOM) List<UIItem> tabids) {
        for (UIItem tabListItem : tabids) {
            tabListItem.setHidden(true);  // 隐藏表格操作按钮
        }
    }
}

功能：隐藏表格行操作按钮适用场景：根据数据状态控制操作权限（如已审核数据隐藏编辑按钮）

3.2.2 隐藏列选项 (HiddenHeader)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.GridRight, name = "隐藏列选项")
public class HiddenHeader {
    public HiddenHeader(@FParams(type = FormulaParams.GRIDCOM) List<UIItem> tabids) {
        for (UIItem tabListItem : tabids) {
            tabListItem.setHidden(true);
        }
    }
}

功能：隐藏表格列头选项适用场景：根据用户权限隐藏敏感列（如身份证号、联系方式等）

3.3 工具栏控制插件

控制工具栏按钮的显示与禁用状态。

3.3.1 禁用按钮 (DisabledBarItem)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.BarRight, name = "禁用按钮")
public class DisabledBarItem {
    public DisabledBarItem(@FParams(type = FormulaParams.CURRBAR) List<UIItem> barItems) {
        for (UIItem barItem : barItems) {
            barItem.setDisabled(true);  // 禁用工具栏按钮
        }
    }
}

功能：禁用指定的工具栏按钮适用场景：权限控制、业务状态限制（如未保存时禁用提交按钮）

3.3.2 隐藏按钮 (HiddenBarItem)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.BarRight, name = "隐藏按钮")
public class HiddenBarItem {
    public HiddenBarItem(@FParams(type = FormulaParams.CURRBAR) List<UIItem> barItems) {
        for (UIItem barItem : barItems) {
            barItem.setHidden(true);
        }
    }
}

功能：隐藏工具栏按钮区别：与禁用按钮的区别在于完全隐藏而非仅置灰，适用于基于角色的功能显示控制

3.4 列表项控制插件

控制列表选项的可用性。

3.4.1 禁用选择项 (DisabledItem)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.ItemRight, name = "禁用选择项")
public class DisabledItem {
    public DisabledItem(@FParams(type = FormulaParams.CURRITEM) List<UIItem> tabids) {
        for (UIItem tabListItem : tabids) {
            tabListItem.setDisabled(true);  // 禁用列表项
        }
    }
}

功能：禁用下拉列表或单选框中的指定选项适用场景：动态选项过滤、权限控制

3.5 标签页控制插件

控制标签页的显示与禁用状态。

3.5.1 隐藏标签页 (HiddenTab)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.TabRight)
public class HiddenTab {
    public HiddenTab(@FParams(type = FormulaParams.CURRTAB) List<UIItem> tabItems) {
        for (UIItem uiItem : tabItems) {
            uiItem.setHidden(true);  // 隐藏标签页
        }
    }
}

功能：隐藏指定的标签页适用场景：根据用户角色或业务场景显示不同标签页内容

3.5.2 禁用TAB菜单 (DisabledTab)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.TabRight, name = "禁用TAB菜单")
public class DisabledTab {
    public DisabledTab(@FParams(type = FormulaParams.CURRTAB) List<TabListItem> tabids) {
        for (TabListItem tabListItem : tabids) {
            tabListItem.setDisabled(true);
        }
    }
}

功能：禁用标签页切换区别：与隐藏标签页的区别在于标签仍可见但不可点击，适用于需要提示用户存在但无权限访问的场景

3.6 表单控制插件

专注于表单组件的特殊属性控制。

3.6.1 设置只读 (ReadOnlyCom)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.FormRight, name = "设置只读")
public class ReadOnlyCom {
    public ReadOnlyCom(@FParams(type = FormulaParams.CURRFORMCOM) List<Component> formComs) {
        for (Component component : formComs) {
            if (component.getProperties() instanceof DataProperties) {
                DataProperties dataProperties = (DataProperties) component.getProperties();
                dataProperties.setReadonly(true);  // 设置为只读
            }
        }
    }
}

功能：将表单组件设置为只读状态适用场景：查看详情页面、已提交数据的编辑限制

3.7 条件判断插件

提供业务逻辑条件判断能力。

3.7.1 条件表达式 (FunConditionCon)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.ExpressionCon, name = "条件表达式")
public class FunConditionCon extends AbstractFunction {
    public Boolean perform(@FParams(type = FormulaParams.EXPRESSION) Object obj, ModuleComponent module) {
        if (obj == null || !Boolean.valueOf(obj.toString())) {
            return false;
        }
        return true;  // 返回表达式计算结果
    }
}

功能：计算表达式结果并返回布尔值适用场景：复杂条件判断、权限控制逻辑

3.7.2 页面条件 (PageConditionCon)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.PageCon, name = "页面条件")
public class PageConditionCon extends AbstractFunction {
    public Boolean perform(@FParams(type = FormulaParams.EXPRESSION)String expression, ModuleComponent module) {
        return EsbFactory.par(expression, JDSActionContext.getActionContext().getContext(), module, Boolean.class);
    }
}

功能：计算页面级表达式结果区别：专注于页面级别的条件判断，可访问页面上下文数据

3.8 流程控制插件

与工作流引擎集成，控制流程节点权限。

3.8.1 指定活动条件 (BPMConditionCon)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.WorkFlowCon, name = "指定活动条件")
public class BPMConditionCon extends AbstractFunction {
    public Boolean perform(@FParams(type = FormulaParams.ACTIVITYDEF) List<ActivityDef> activityDefs, ModuleComponent module) {
        ActivityInst activityInst = EsbFactory.par("$currActivityInst", ActivityInst.class);
        if (activityInst != null && activityDefs != null) {
            try {
                return activityDefs.contains(activityInst.getActivityDef());
            } catch (BPMException e) {
                e.printStackTrace();
            }
        }
        return true;  // 判断当前活动是否在指定列表中
    }
}

功能：判断当前流程活动是否在指定活动列表中适用场景：流程节点权限控制、动态流程路由

3.8.2 流程条件 (WorkFlowCondition)

java 复制代码

@EsbBeanAnnotation(type = FormulaType.WorkFlowCon, name = "流程条件")
public class WorkFlowCondition extends AbstractFunction {
    public Boolean perform(@FParams(type = FormulaParams.EXPRESSION) String expression, ModuleComponent module) {
        return EsbFactory.par(expression, JDSActionContext.getActionContext().getContext(), module, Boolean.class);
    }
}

功能：计算流程表达式并返回结果适用场景：复杂流程条件判断、动态分支

四、插件开发指南

4.1 开发环境准备

JDK 1.8+ 开发环境
OneCode SDK 3.0+ 依赖包
Maven/Gradle 构建工具
IDE (IntelliJ IDEA 推荐)

4.2 开发步骤详解

步骤1：创建Maven项目

xml 复制代码

<!-- pom.xml 核心依赖 -->
<dependencies>
    <dependency>
        <groupId>com.onecode</groupId>
        <artifactId>onecode-esd</artifactId>
        <version>1.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>com.ds.esb</groupId>
        <artifactId>esb-core</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

步骤2：创建插件类并添加注解

java 复制代码

package com.ds.esd.fun.custom;

import com.ds.esb.config.EsbBeanAnnotation;
import com.ds.esb.config.formula.FormulaType;

@EsbBeanAnnotation(type = FormulaType.ESDCOM, name = "自定义显示控制")
public class CustomDisplayControl {
    // 实现代码
}

步骤3：定义构造函数与参数注入

java 复制代码

import com.ds.esb.config.formula.FParams;
import com.ds.esb.config.formula.FormulaParams;
import com.ds.esd.tool.ui.component.Component;
import java.util.List;

public class CustomDisplayControl {
    // 注入UI组件参数
    public CustomDisplayControl(@FParams(type = FormulaParams.ESDCOM) List<Component> components) {
        // 业务逻辑实现
    }
}

步骤4：实现业务逻辑

java 复制代码

public class CustomDisplayControl {
    public CustomDisplayControl(@FParams(type = FormulaParams.ESDCOM) List<Component> components) {
        for (Component component : components) {
            // 根据组件名称设置不同样式
            if ("statusField".equals(component.getName())) {
                setStatusStyle(component);
            }
        }
    }
    
    private void setStatusStyle(Component component) {
        // 设置组件样式逻辑
        String status = component.getValue().toString();
        if ("approved".equals(status)) {
            component.getProperties().setStyle("color: green;");
        } else if ("rejected".equals(status)) {
            component.getProperties().setStyle("color: red;");
        } else {
            component.getProperties().setStyle("color: black;");
        }
    }
}

步骤5：打包部署

使用Maven打包：mvn clean package
将生成的JAR文件复制到OneCode插件目录：{onecode_home}/plugins/
重启OneCode设计器，插件自动加载

4.3 开发示例：自定义状态标签插件

完整代码实现

java 复制代码

package com.ds.esd.fun.custom;

import com.ds.esb.config.EsbBeanAnnotation;
import com.ds.esb.config.formula.FParams;
import com.ds.esb.config.formula.FormulaParams;
import com.ds.esb.config.formula.FormulaType;
import com.ds.esd.tool.ui.component.Component;
import com.ds.esd.tool.ui.component.container.AbsUIProperties;
import java.util.List;

@EsbBeanAnnotation(type = FormulaType.ESDCOM, name = "状态标签样式控制")
public class StatusLabelControl {
    // 注入需要控制的组件列表
    public StatusLabelControl(@FParams(type = FormulaParams.ESDCOM) List<Component> components) {
        for (Component component : components) {
            applyStatusStyle(component);
        }
    }
    
    /**
     * 根据状态值应用不同样式
     */
    private void applyStatusStyle(Component component) {
        if (!(component.getProperties() instanceof AbsUIProperties)) {
            return;
        }
        
        AbsUIProperties properties = (AbsUIProperties) component.getProperties();
        String status = String.valueOf(component.getValue()).toLowerCase();
        String style = getStyleByStatus(status);
        
        // 设置组件样式
        properties.setStyle(style);
        // 设置提示信息
        properties.setTooltip("状态: " + status);
    }
    
    /**
     * 根据状态获取样式
     */
    private String getStyleByStatus(String status) {
        switch (status) {
            case "draft":
                return "background-color: #f0f0f0; color: #666; padding: 2px 8px; border-radius: 12px;";
            case "pending":
                return "background-color: #fff3cd; color: #856404; padding: 2px 8px; border-radius: 12px;";
            case "approved":
                return "background-color: #d4edda; color: #155724; padding: 2px 8px; border-radius: 12px;";
            case "rejected":
                return "background-color: #f8d7da; color: #721c24; padding: 2px 8px; border-radius: 12px;";
            default:
                return "background-color: #e9ecef; color: #383d41; padding: 2px 8px; border-radius: 12px;";
        }
    }
}

使用说明

插件类型：FormulaType.ESDCOM（组件操作类型）
参数类型：FormulaParams.ESDCOM（UI组件列表）
功能描述：根据组件值（状态）自动应用不同样式，实现标签化展示
应用场景：流程状态、审批状态等需要视觉区分的场景

五、插件应用最佳实践

5.1 权限控制组合

scss 复制代码

// 组合使用禁用和隐藏插件实现复杂权限控制
HiddenBarItem("editBtn") + DisabledBarItem("viewBtn")

5.2 动态表单控制

scss 复制代码

// 根据角色显示不同表单元素
if (currentUser.hasRole("admin")) {
    ReadOnlyCom("normalField")
} else {
    HiddenCom("adminField")
}

5.3 流程节点控制

scss 复制代码

// 流程条件与组件控制结合
if (BPMConditionCon("activity1,activity2")) {
    HiddenCom("approveBtn")
} else {
    ReadOnlyCom("commentField")
}

六、总结

OneCode自定义扩展函数采用注解驱动开发模式，通过简单的Java类定义即可实现丰富的业务功能。本文详细介绍了com.ds.esd.fun包下的全部20个插件，涵盖组件控制、表格操作、工具栏控制、标签页控制、表单控制、条件判断和流程控制七大类别。

开发者可根据实际需求，参考现有插件结构快速开发新的扩展函数，实现UI控制、权限管理、流程判断等多样化需求。插件体系的设计遵循开闭原则，既提供了丰富的内置功能，又保留了灵活的扩展能力，是OneCode平台低代码开发理念的重要体现。