OneCode 3.0 @APIEventAnnotation 注解速查手册

原创

OneCode

修改于 2025-07-21 19:29:14

1320

一、注解概述与基本信息

1.1 注解定义与核心功能

@APIEventAnnotation 是 OneCode 3.0 框架中用于声明 API 事件的核心注解，主要用于将前端 UI 事件与后端 API 服务进行绑定，实现 "事件驱动、数据绑定、响应处理" 的全链路交互机制。该注解通过元数据配置替代传统的命令式编程，大幅减少了前端 JavaScript 代码量，提高了开发效率和代码可维护性。

该注解的完整定义如下：

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface APIEventAnnotation {
    // 配置属性...
}

该注解主要应用于 Controller 类的方法上，用于定义该方法处理的 API 事件。

1.2 注解元数据信息

元数据项	值	说明
作用目标	方法	只能应用于 Controller 类的方法
生命周期	运行时保留	注解信息在运行时可用
继承性	不继承	子类不会继承父类的注解配置
核心功能	事件绑定、数据映射、请求配置、响应处理	实现前后端交互的全链路管理

二、属性详解与使用示例

2.1 基础配置属性

1. queryAsync

类型：boolean
默认值：true
说明：设置是否异步执行 API 请求
适用场景：
- 需要保持 UI 响应性的场景（如表单提交、数据加载）
- 非阻塞式操作（大多数情况推荐使用异步）
- 当需要同步执行多个 API 请求时设置为 false

示例代码：

@APIEventAnnotation(
    queryAsync = false, // 同步执行请求
    // 其他配置...
)
public ResultModel handleSyncRequest() {
    // 业务逻辑
}

2. autoRun

类型：boolean
默认值：false
说明：设置是否在页面加载完成后自动执行 API 请求
适用场景：
- 页面初始化时需要加载数据的场景
- 不需要用户触发即可执行的初始化操作
- 避免重复编写页面加载后的初始化代码

示例代码：

@APIEventAnnotation(
    autoRun = true, // 页面加载后自动执行
    // 其他配置...
)
public ResultModel loadInitialData() {
    // 加载初始数据的业务逻辑
}

3. autoDisplay

类型：boolean
默认值：false
说明：设置是否自动显示 API 调用结果
适用场景：
- 简单数据展示场景（如单一值、简短文本）
- 不需要复杂处理的 API 响应结果
- 减少手动编写结果展示代码的工作量

示例代码：

@APIEventAnnotation(
    autoDisplay = true, // 自动显示结果
    // 其他配置...
)
public ResultModel showSimpleResult() {
    // 返回简单结果的业务逻辑
}

4. isAllform

类型：boolean
默认值：false
说明：设置是否将表单所有字段作为请求参数
适用场景：
- 表单提交场景（特别是包含多个字段的表单）
- 需要提交表单全部数据的情况
- 减少逐个配置表单字段的工作量

示例代码：

@APIEventAnnotation(
    isAllform = true, // 提交表单所有字段
    // 其他配置...
)
public ResultModel submitFullFormData() {
    // 处理表单全部数据的业务逻辑
}

5. index

类型：int
默认值：-1
说明：设置 API 事件的执行顺序（数值越小优先级越高）
适用场景：
- 多个 API 事件需要按特定顺序执行的场景
- 需要控制事件执行顺序的复杂业务流程
- 确保某些关键操作在其他操作之前或之后执行

示例代码：

@APIEventAnnotation(
    index = 10, // 执行顺序为第10位
    // 其他配置...
)
public ResultModel executeWithPriority() {
    // 具有特定执行顺序的业务逻辑
}

2.2 事件绑定属性

6. bindMenu

类型：CustomMenuItem[]
默认值：{}
说明：绑定菜单项事件
适用场景：
- 菜单驱动的业务操作（如文件菜单中的 "保存"、"打开" 等）
- 需要将菜单操作与特定 API 事件关联的场景
- 实现菜单驱动的复杂业务流程

示例代码：

@APIEventAnnotation(
    bindMenu = {
        CustomMenuItem.SAVE, // 绑定"保存"菜单项
        CustomMenuItem.EXPORT // 绑定"导出"菜单项
    },
    // 其他配置...
)
public ResultModel handleMenuEvents() {
    // 处理菜单事件的业务逻辑
}

7. bindAction

类型：CustomAction[]
默认值：{}
说明：绑定自定义动作事件
适用场景：
- 自定义按钮或操作触发的事件
- 需要执行特定动作的业务场景
- 实现自定义操作的灵活处理

示例代码：

@APIEventAnnotation(
    bindAction = {
        CustomAction.PREVIEW, // 绑定"预览"动作
        CustomAction.EDIT // 绑定"编辑"动作
    },
    // 其他配置...
)
public ResultModel handleCustomActions() {
    // 处理自定义动作的业务逻辑
}

8. enumClass

类型：Class<? extends Enum>
默认值：Enum.class
说明：指定事件枚举类
适用场景：
- 自定义事件枚举类型
- 需要使用特定枚举类的场景
- 实现自定义事件类型的扩展

示例代码：

@APIEventAnnotation(
    enumClass = CustomEventType.class, // 指定自定义事件枚举类
    // 其他配置...
)
public ResultModel handleCustomEvents() {
    // 处理自定义事件的业务逻辑
}

9. bindFieldEvent

类型：CustomFieldEvent[]
默认值：{}
说明：绑定表单字段事件
适用场景：
- 表单字段值变化触发的事件（如输入框内容变化）
- 需要实时验证或处理字段值的场景
- 实现表单字段级别的精细化控制

示例代码：

@APIEventAnnotation(
    bindFieldEvent = {
        CustomFieldEvent.CHANGE, // 绑定"变化"事件
        CustomFieldEvent.BLUR // 绑定"失去焦点"事件
    },
    // 其他配置...
)
public ResultModel handleFieldEvents() {
    // 处理表单字段事件的业务逻辑
}

10. bindGalleryEvent

类型：CustomGalleryEvent[]
默认值：{}
说明：绑定图片画廊事件
适用场景：
- 图片画廊操作触发的事件（如选择图片、查看详情）
- 需要处理图片相关操作的场景
- 实现图片画廊的自定义交互

示例代码：

@APIEventAnnotation(
    bindGalleryEvent = {
        CustomGalleryEvent.SELECT_ITEM, // 绑定"选择项目"事件
        CustomGalleryEvent.VIEW_DETAIL // 绑定"查看详情"事件
    },
    // 其他配置...
)
public ResultModel handleGalleryEvents() {
    // 处理图片画廊事件的业务逻辑
}

11. bindTitleBlockEvent

类型：CustomTitleBlockEvent[]
默认值：{}
说明：绑定标题块事件
适用场景：
- 标题块操作触发的事件（如全屏、折叠）
- 需要处理标题块相关操作的场景
- 实现标题块的自定义交互

示例代码：

@APIEventAnnotation(
    bindTitleBlockEvent = {
        CustomTitleBlockEvent.FULLSCREEN, // 绑定"全屏"事件
        CustomTitleBlockEvent.COLLAPSE // 绑定"折叠"事件
    },
    // 其他配置...
)
public ResultModel handleTitleBlockEvents() {
    // 处理标题块事件的业务逻辑
}

12. bindContentBlockEvent

类型：CustomContentBlockEvent[]
默认值：{}
说明：绑定内容块事件
适用场景：
- 内容块操作触发的事件（如刷新、加载更多）
- 需要处理内容块相关操作的场景
- 实现内容块的自定义交互

示例代码：

@APIEventAnnotation(
    bindContentBlockEvent = {
        CustomContentBlockEvent.REFRESH, // 绑定"刷新"事件
        CustomContentBlockEvent.LOAD_MORE // 绑定"加载更多"事件
    },
    // 其他配置...
)
public ResultModel handleContentBlockEvents() {
    // 处理内容块事件的业务逻辑
}

13. bindGridEvent

类型：CustomGridEvent[]
默认值：{}
说明：绑定表格事件
适用场景：
- 表格操作触发的事件（如加载、刷新、导出）
- 需要处理表格相关操作的场景
- 实现表格的自定义交互

示例代码：

@APIEventAnnotation(    bindGridEvent = {        CustomGridEvent.LOAD, // 绑定"加载"事件        CustomGridEvent.REFRESH, // 绑定"刷新"事件        CustomGridEvent.EXPORT // 绑定"导出"事件    },    // 其他配置...)public ResultModel handleGridEvents() {    // 处理表格事件的业务逻辑}

14. bindMGridEvent

类型：CustomMGridEvent[]
默认值：{}
说明：绑定复杂表格事件
适用场景：
- 复杂表格操作触发的事件（如合并单元格、分组行）
- 需要处理复杂表格相关操作的场景
- 实现复杂表格的自定义交互

示例代码：

@APIEventAnnotation(
    bindMGridEvent = {
        CustomMGridEvent.MERGE_CELL, // 绑定"合并单元格"事件
        CustomMGridEvent.GROUP_ROW // 绑定"分组行"事件
    },
    // 其他配置...
)
public ResultModel handleMGridEvents() {
    // 处理复杂表格事件的业务逻辑
}

15. bindTreeEvent

类型：CustomTreeEvent[]
默认值：{}
说明：绑定树形组件事件
适用场景：
- 树形组件操作触发的事件（如展开、选中、检查）
- 需要处理树形结构相关操作的场景
- 实现树形组件的自定义交互

示例代码：

@APIEventAnnotation(
    bindTreeEvent = {
        CustomTreeEvent.EXPAND, // 绑定"展开"事件
        CustomTreeEvent.SELECT, // 绑定"选择"事件
        CustomTreeEvent.CHECK // 绑定"检查"事件
    },
    // 其他配置...
)
public ResultModel handleTreeEvents() {
    // 处理树形组件事件的业务逻辑
}

16. bindFormEvent

类型：CustomFormEvent[]
默认值：{}
说明：绑定表单事件
适用场景：
- 表单操作触发的事件（如保存、重置、搜索）
- 需要处理表单相关操作的场景
- 实现表单的自定义交互

示例代码：

@APIEventAnnotation(
    bindFormEvent = {
        CustomFormEvent.SAVE, // 绑定"保存"事件
        CustomFormEvent.RESET, // 绑定"重置"事件
        CustomFormEvent.SEARCH // 绑定"搜索"事件
    },
    // 其他配置...
)
public ResultModel handleFormEvents() {
    // 处理表单事件的业务逻辑
}

17. bindMFormEvent

类型：CustomMFormEvent[]
默认值：{}
说明：绑定多表表单事件
适用场景：
- 多表表单操作触发的事件（如添加行、删除行）
- 需要处理多表表单相关操作的场景
- 实现多表表单的自定义交互

示例代码：

@APIEventAnnotation(
    bindMFormEvent = {
        CustomMFormEvent.ADD_ROW, // 绑定"添加行"事件
        CustomMFormEvent.DELETE_ROW // 绑定"删除行"事件
    },
    // 其他配置...
)
public ResultModel handleMFormEvents() {
    // 处理多表表单事件的业务逻辑
}

18. bindTabsEvent

类型：CustomTabsEvent[]
默认值：{}
说明：绑定标签页事件
适用场景：
- 标签页操作触发的事件（如切换、关闭）
- 需要处理标签页相关操作的场景
- 实现标签页的自定义交互

示例代码：

@APIEventAnnotation(
    bindTabsEvent = {
        CustomTabsEvent.SWITCH, // 绑定"切换"事件
        CustomTabsEvent.CLOSE // 绑定"关闭"事件
    },
    // 其他配置...
)
public ResultModel handleTabsEvents() {
    // 处理标签页事件的业务逻辑
}

19. bindHotKeyEvent

类型：CustomHotKeyEvent[]
默认值：{}
说明：绑定快捷键事件
适用场景：
- 快捷键操作触发的事件（如 Ctrl+S、ESC）
- 需要处理快捷键相关操作的场景
- 实现全局快捷键的自定义交互

示例代码：

@APIEventAnnotation(
    bindHotKeyEvent = {
        CustomHotKeyEvent.CTRL_S, // 绑定"Ctrl+S"快捷键
        CustomHotKeyEvent.ESC // 绑定"ESC"键
    },
    // 其他配置...
)
public ResultModel handleHotKeyEvents() {
    // 处理快捷键事件的业务逻辑
}

2.3 数据映射属性

20. requestDataSource

类型：RequestPathAnnotation[]
默认值：{}
说明：配置请求数据源
适用场景：
- 需要从特定数据源获取请求参数的场景
- 实现表单数据、组件数据到请求参数的映射
- 减少手动编写数据提取代码的工作量

示例代码：

@APIEventAnnotation(
    requestDataSource = {
        @RequestPathAnnotation(type = "form", name = "userForm", path = "id"), // 从表单获取ID
        @RequestPathAnnotation(type = "component", name = "deptTree", path = "selectedId") // 从组件获取选中ID
    },
    // 其他配置...
)
public ResultModel handleDataSources() {
    // 处理数据源的业务逻辑
}

21. responseDataTarget

类型：ResponsePathAnnotation[]
默认值：{}
说明：配置响应数据目标
适用场景：
- 需要将响应数据映射到特定目标的场景
- 实现响应数据到表单、组件的自动填充
- 减少手动编写数据填充代码的工作量

示例代码：

@APIEventAnnotation(
    responseDataTarget = {
        @ResponsePathAnnotation(type = "form", name = "userForm", path = "lastUpdateTime") // 将响应数据映射到表单的lastUpdateTime字段
    },
    // 其他配置...
)
public ResultModel handleResponseTargets() {
    // 处理响应目标的业务逻辑
}

22. responseCallback

类型：CallBackPathAnnotation[]
默认值：{}
说明：配置回调路径
适用场景：
- 需要在 API 调用完成后执行回调的场景
- 实现复杂的回调逻辑（如更新多个组件状态）
- 减少手动编写回调代码的工作量

示例代码：

@APIEventAnnotation(
    responseCallback = {
        @CallBackPathAnnotation(name = "updateStatus", params = {"{{response.status}}") // 回调函数，参数为响应中的status
    },
    // 其他配置...
)
public ResultModel handleCallbacks() {
    // 处理回调的业务逻辑
}

23. customRequestData

类型：RequestPathEnum[]
默认值：{}
说明：配置常用请求数据
适用场景：
- 需要使用常用请求数据的场景
- 实现预定义的请求数据映射（如表单 ID、全局用户信息）
- 减少重复配置的工作量

示例代码：

@APIEventAnnotation(
    customRequestData = {
        RequestPathEnum.FORM_ID, // 表单ID
        RequestPathEnum.GLOBAL_USER_INFO // 全局用户信息
    },
    // 其他配置...
)
public ResultModel handleCustomRequests() {
    // 处理自定义请求数据的业务逻辑
}

24. customResponseData

类型：ResponsePathEnum[]
默认值：{}
说明：配置常用响应数据
适用场景：
- 需要使用常用响应数据的场景
- 实现预定义的响应数据映射（如表单重置、消息提示）
- 减少重复配置的工作量

示例代码：

@APIEventAnnotation(
    customResponseData = {
        ResponsePathEnum.FORM_RESET, // 表单重置
        ResponsePathEnum.MESSAGE_TIP // 消息提示
    },
    // 其他配置...
)
public ResultModel handleCustomResponses() {
    // 处理自定义响应数据的业务逻辑
}

25. customResponseCallback

类型：CallBackPathEnum[]
默认值：{}
说明：配置常用回调路径
适用场景：
- 需要使用常用回调路径的场景
- 实现预定义的回调路径映射
- 减少重复配置的工作量

示例代码：

@APIEventAnnotation(
    customResponseCallback = {
        CallBackPathEnum.UPDATE_STATUS // 更新状态回调
    },
    // 其他配置...
)
public ResultModel handleCustomCallbacks() {
    // 处理自定义回调的业务逻辑
}

2.4 生命周期回调属性

26. beforeData

类型：CustomBeforData[]
默认值：{}
说明：数据准备前的回调
适用场景：
- 需要在准备请求数据前执行的操作
- 实现数据预处理逻辑（如数据校验、格式转换）
- 确保请求数据符合要求

示例代码：

@APIEventAnnotation(
    beforeData = {
        CustomBeforData.MESSAGE // 数据准备前的提示
    },
    // 其他配置...
)
public ResultModel handleBeforeData() {
    // 处理数据准备前逻辑的业务逻辑
}

27. beforeDataAction

类型：CustomAction[]
默认值：{}
说明：数据准备前的动作
适用场景：
- 需要在数据准备前执行特定动作的场景
- 实现复杂的数据准备逻辑（如多个步骤的预处理）
- 减少重复编写预处理代码的工作量

示例代码：

@APIEventAnnotation(
    beforeDataAction = {
        @CustomAction(name = "validateForm") // 表单验证动作
    },
    // 其他配置...
)
public ResultModel handleBeforeDataActions() {
    // 处理数据准备前动作的业务逻辑
}@APIEventAnnotation(
    beforeInvoke = {
        @CustomBeforInvoke(message = "正在发送请求...") // 请求发送前的提示
    },
    // 其他配置...
)
public ResultModel handleBeforeInvoke() {
    // 处理请求发送前逻辑的业务逻辑
}

28. beforeInvoke

类型：CustomBeforInvoke[]
默认值：{}
说明：请求发送前的回调
适用场景：
- 需要在发送请求前执行的操作
- 实现请求前的最后检查（如权限验证）
- 确保请求符合要求

示例代码：

@APIEventAnnotation(
    beforeInvoke = {
      CustomBeforInvoke.MESSAGE // 请求发送前的提示
    },
    // 其他配置...
)
public ResultModel handleBeforeInvoke() {
    // 处理请求发送前逻辑的业务逻辑
}

29. beforeInvokeAction

类型：CustomAction[]
默认值：{}
说明：请求发送前的动作
适用场景：
- 需要在请求发送前执行特定动作的场景
- 实现复杂的请求前逻辑（如显示加载动画）
- 减少重复编写请求前代码的工作量

示例代码：

@APIEventAnnotation(
    beforeInvokeAction = {
      CustomBeforInvoke.BUSY // 增加遮罩
    },
    // 其他配置...
)
public ResultModel handleBeforeInvokeActions() {
    // 处理请求发送前动作的业务逻辑
}

30. callback

类型：CustomCallBack[]
默认值：{}
说明：响应处理后的回调
适用场景：
- 需要在响应处理后执行的操作
- 实现响应后的通用处理逻辑（如关闭对话框）
- 减少重复编写响应处理代码的工作量

示例代码：

@APIEventAnnotation(
    callback = {
        @CustomCallBack(message = "响应处理完成") // 响应处理后的提示
    },
    // 其他配置...
)
public ResultModel handleCallbacks() {
    // 处理响应回调的业务逻辑
}

31. callbackAction

类型：CustomAction[]
默认值：{}
说明：响应处理后的动作
适用场景：
- 需要在响应处理后执行特定动作的场景
- 实现复杂的响应后逻辑（如刷新表格、重置表单）
- 减少重复编写响应后代码的工作量

示例代码：

@APIEventAnnotation(
    callbackAction = {
        @CustomAction(name = "refreshGrid"), // 刷新表格动作
        @CustomAction(name = "resetForm") // 重置表单动作
    },
    // 其他配置...
)
public ResultModel handleCallbackActions() {
    // 处理响应后动作的业务逻辑
}

32. afterInvok

类型：CustomCallBack[]
默认值：{}
说明：请求完成后的回调
适用场景：
- 需要在请求完成后执行的操作
- 实现请求完成后的最终处理（如释放资源）
- 确保无论成功与否都执行的逻辑

示例代码：

@APIEventAnnotation(
    afterInvok = {
        CustomCallBack.FREE // 解除遮罩
    },
    // 其他配置...
)
public ResultModel handleAfterInvok() {
    // 处理请求完成后逻辑的业务逻辑
}

33. afterInvokAction

类型：CustomAction[]
默认值：{}
说明：请求完成后的动作
适用场景：
- 需要在请求完成后执行特定动作的场景
- 实现复杂的请求完成后逻辑（如清理临时数据）
- 减少重复编写请求完成后代码的工作量

示例代码：

@APIEventAnnotation(
    afterInvokAction = {
        @CustomAction(name = "cleanup") // 清理动作
    },
    // 其他配置...
)
public ResultModel handleAfterInvokActions() {
    // 处理请求完成后动作的业务逻辑
}

34. onError

类型：CustomOnError[]
默认值：{}
说明：请求出错时的回调
适用场景：
- 需要处理请求错误的场景
- 实现错误处理逻辑（如显示错误信息）
- 确保错误情况得到妥善处理

示例代码：

@APIEventAnnotation(
    onError = {
        CustomOnError.MESSAGE// 请求出错时的提示
    },
    // 其他配置...
)
public ResultModel handleOnError() {
    // 处理请求错误逻辑的业务逻辑
}

35. onErrorAction

类型：CustomAction[]
默认值：{}
说明：请求出错时的动作
适用场景：
- 需要在请求出错时执行特定动作的场景
- 实现复杂的错误处理逻辑（如隐藏加载动画、显示错误信息）
- 减少重复编写错误处理代码的工作量

示例代码：

@APIEventAnnotation(
    onErrorAction = {
        @CustomAction(name = "hideLoading"), // 隐藏加载动画动作
        @CustomAction(name = "showError") // 显示错误信息动作
    },
    // 其他配置...
)
public ResultModel handleOnErrorActions() {
    // 处理请求出错动作的业务逻辑
}

36. onData

类型：CustomOnData[]
默认值：{}
说明：接收到数据时的回调
适用场景：
- 需要在接收到数据时执行的操作
- 实现数据处理逻辑（如数据转换、过滤）
- 确保数据在处理前符合要求

示例代码：

@APIEventAnnotation(
    onData = {
       CustomOnData.RELOAD// 接收到数据时的提示
    },
    // 其他配置...
)
public ResultModel handleOnData() {
    // 处理接收到数据逻辑的业务逻辑
}

37. onDataAction

类型：CustomAction[]
默认值：{}
说明：接收到数据时的动作
适用场景：
- 需要在接收到数据时执行特定动作的场景
- 实现复杂的数据处理逻辑（如数据格式化、存储）
- 减少重复编写数据处理代码的工作量

示例代码：

@APIEventAnnotation(
    onDataAction = {
        @CustomAction(name = "processData") // 处理数据动作
    },
    // 其他配置...
)
public ResultModel handleOnDataActions() {
    // 处理接收到数据动作的业务逻辑
}

38. onExecuteSuccess

类型：CustomOnExecueSuccess[]
默认值：{}
说明：请求执行成功时的回调
适用场景：
- 需要处理请求成功的场景
- 实现成功处理逻辑（如显示成功信息）
- 确保成功情况得到妥善处理

示例代码：

@APIEventAnnotation(
    onExecuteSuccess = {
      CustomOnExecueSuccess.MSG// 请求成功时的提示
    },
    // 其他配置...
)
public ResultModel handleOnExecuteSuccess() {
    // 处理请求成功逻辑的业务逻辑
}

39. onExecuteSuccessAction

类型：CustomAction[]
默认值：{}
说明：请求执行成功时的动作
适用场景：
- 需要在请求成功时执行特定动作的场景
- 实现复杂的成功处理逻辑（如刷新页面、跳转页面）
- 减少重复编写成功处理代码的工作量

示例代码：

@APIEventAnnotation(
    onExecuteSuccessAction = {
        @CustomAction(name = "refreshPage"), // 刷新页面动作
        @CustomAction(name = "redirectToSuccessPage") // 跳转到成功页面动作
    },
    // 其他配置...
)
public ResultModel handleOnExecuteSuccessActions() {
    // 处理请求成功动作的业务逻辑
}

40. onExecuteError

类型：CustomOnExecueError[]
默认值：{}
说明：请求执行失败时的回调
适用场景：
- 需要处理请求失败的场景
- 实现失败处理逻辑（如显示失败原因）
- 确保失败情况得到妥善处理

示例代码：

@APIEventAnnotation(
    onExecuteError = {
       CustomOnExecueError.FREE // 解除遮罩
    },
    // 其他配置...
)
public ResultModel handleOnExecuteError() {
    // 处理请求失败逻辑的业务逻辑
}

41. onExecuteErrorAction

类型：CustomAction[]
默认值：{}
说明：请求执行失败时的动作
适用场景：
- 需要在请求失败时执行特定动作的场景
- 实现复杂的失败处理逻辑（如记录错误日志、重试请求）
- 减少重复编写失败处理代码的工作量

示例代码：

@APIEventAnnotation(
    onExecuteError = {
        @CustomAction(name = "reloadPage", method = "call", type = ActionTypeEnum.other, target = "callback", args = {"{SPA.reloadPage()}"}),
    },
    // 其他配置...
)
public ResultModel handleOnExecuteError() {
    // 处理请求失败逻辑的业务逻辑
}

三、核心事件枚举详解

3.1 表单相关事件

表单事件（CustomFormEvent）

事件名称	描述	触发时机
SAVE	保存事件	用户点击保存按钮或执行保存操作时触发
RESET	重置事件	用户点击重置按钮或执行重置操作时触发
SEARCH	搜索事件	用户点击搜索按钮或执行搜索操作时触发
CANCEL	取消事件	用户点击取消按钮或执行取消操作时触发
SUBMIT	提交事件	用户提交表单时触发
VALIDATE	验证事件	表单验证时触发

示例代码：

@APIEventAnnotation(
    bindFormEvent = {
        CustomFormEvent.SAVE, // 绑定保存事件
        CustomFormEvent.SEARCH // 绑定搜索事件
    },
    // 其他配置...
)
public ResultModel handleFormEvents() {
    // 处理表单事件的业务逻辑
}

多表表单事件（CustomMFormEvent）

事件名称	描述	触发时机
ADD_ROW	添加行事件	用户点击添加行按钮或执行添加行操作时触发
DELETE_ROW	删除行事件	用户点击删除行按钮或执行删除行操作时触发
EDIT_ROW	编辑行事件	用户点击编辑行按钮或执行编辑行操作时触发
BATCH_PROCESS	批量处理事件	用户执行批量处理操作时触发

示例代码：

@APIEventAnnotation(
    bindMFormEvent = {
        CustomMFormEvent.ADD_ROW, // 绑定添加行事件
        CustomMFormEvent.DELETE_ROW // 绑定删除行事件
    },
    // 其他配置...
)
public ResultModel handleMFormEvents() {
    // 处理多表表单事件的业务逻辑
}

字段事件（CustomFieldEvent）

事件名称	描述	触发时机
CHANGE	变化事件	字段值发生变化时触发
BLUR	失去焦点事件	字段失去焦点时触发
FOCUS	获得焦点事件	字段获得焦点时触发
VALIDATE	验证事件	字段验证时触发

示例代码：

@APIEventAnnotation(
    bindFieldEvent = {
        CustomFieldEvent.CHANGE, // 绑定变化事件
        CustomFieldEvent.BLUR // 绑定失去焦点事件
    },
    // 其他配置...
)
public ResultModel handleFieldEvents() {
    // 处理字段事件的业务逻辑
}

3.2 数据展示相关事件

表格事件（CustomGridEvent）

事件名称	描述	触发时机
LOAD	加载事件	表格加载数据时触发
REFRESH	刷新事件	表格刷新数据时触发
EXPORT	导出事件	用户点击导出按钮或执行导出操作时触发
SELECT	选择事件	用户选择表格行时触发
DESELECT	取消选择事件	用户取消选择表格行时触发
PAGE_CHANGE	分页变化事件	表格分页变化时触发

示例代码：

@APIEventAnnotation(
    bindGridEvent = {
        CustomGridEvent.LOAD, // 绑定加载事件
        CustomGridEvent.REFRESH // 绑定刷新事件
    },
    // 其他配置...
)
public ResultModel handleGridEvents() {
    // 处理表格事件的业务逻辑
}

复杂表格事件（CustomMGridEvent）

事件名称	描述	触发时机
MERGE_CELL	合并单元格事件	合并表格单元格时触发
GROUP_ROW	分组行事件	分组表格行时触发
UNGROUP_ROW	取消分组行事件	取消分组表格行时触发
SORT	排序事件	表格排序时触发
FILTER	过滤事件	表格过滤时触发

示例代码：

@APIEventAnnotation(
    bindTreeEvent = {
        CustomTreeEvent.EXPAND, // 绑定展开事件
        CustomTreeEvent.SELECT // 绑定选择事件
    },
    // 其他配置...
)
public ResultModel handleTreeEvents() {
    // 处理树形组件事件的业务逻辑
}

树形组件事件（CustomTreeEvent）

事件名称	描述	触发时机
EXPAND	展开事件	树形节点展开时触发
COLLAPSE	折叠事件	树形节点折叠时触发
SELECT	选择事件	用户选择树形节点时触发
DESELECT	取消选择事件	用户取消选择树形节点时触发
CHECK	选中事件	用户选中树形节点时触发
UNCHECK	取消选中事件	用户取消选中树形节点时触发

示例代码：

@APIEventAnnotation(
    bindTreeEvent = {
        CustomTreeEvent.EXPAND, // 绑定展开事件
        CustomTreeEvent.SELECT // 绑定选择事件
    },
    // 其他配置...
)
public ResultModel handleTreeEvents() {
    // 处理树形组件事件的业务逻辑
}

标签页事件（CustomTabsEvent）

事件名称	描述	触发时机
SWITCH	切换事件	标签页切换时触发
CLOSE	关闭事件	标签页关闭时触发
ADD	添加事件	添加新标签页时触发
REMOVE	删除事件	删除标签页时触发

示例代码：

@APIEventAnnotation(
    bindTabsEvent = {
        CustomTabsEvent.SWITCH, // 绑定切换事件
        CustomTabsEvent.CLOSE // 绑定关闭事件
    },
    // 其他配置...
)
public ResultModel handleTabsEvents() {
    // 处理标签页事件的业务逻辑
}

3.3 其他常用事件

快捷键事件（CustomHotKeyEvent）

事件名称	描述	触发时机
CTRL_S	Ctrl+S 事件	用户按下 Ctrl+S 组合键时触发
CTRL_O	Ctrl+O 事件	用户按下 Ctrl+O 组合键时触发
CTRL_P	Ctrl+P 事件	用户按下 Ctrl+P 组合键时触发
ESC	ESC 事件	用户按下 ESC 键时触发
ENTER	Enter 事件	用户按下 Enter 键时触发

示例代码：

@APIEventAnnotation(
    bindHotKeyEvent = {
        CustomHotKeyEvent.CTRL_S, // 绑定Ctrl+S事件
        CustomHotKeyEvent.ESC // 绑定ESC事件
    },
    // 其他配置...
)
public ResultModel handleHotKeyEvents() {
    // 处理快捷键事件的业务逻辑
}

标题块事件（CustomTitleBlockEvent）

事件名称	描述	触发时机
FULLSCREEN	全屏事件	用户点击全屏按钮或执行全屏操作时触发
COLLAPSE	折叠事件	用户点击折叠按钮或执行折叠操作时触发
EXPAND	展开事件	用户点击展开按钮或执行展开操作时触发
CLOSE	关闭事件	用户点击关闭按钮或执行关闭操作时触发

示例代码：

@APIEventAnnotation(
    bindTitleBlockEvent = {
        CustomTitleBlockEvent.FULLSCREEN, // 绑定全屏事件
        CustomTitleBlockEvent.COLLAPSE // 绑定折叠事件
    },
    // 其他配置...
)
public ResultModel handleTitleBlockEvents() {
    // 处理标题块事件的业务逻辑
}

内容块事件（CustomContentBlockEvent）

事件名称	描述	触发时机
REFRESH	刷新事件	用户点击刷新按钮或执行刷新操作时触发
LOAD_MORE	加载更多事件	用户点击加载更多按钮或执行加载更多操作时触发
COLLAPSE	折叠事件	用户点击折叠按钮或执行折叠操作时触发
EXPAND	展开事件	用户点击展开按钮或执行展开操作时触发

示例代码：

@APIEventAnnotation(
    bindContentBlockEvent = {
        CustomContentBlockEvent.REFRESH, // 绑定刷新事件
        CustomContentBlockEvent.LOAD_MORE // 绑定加载更多事件
    },
    // 其他配置...
)
public ResultModel handleContentBlockEvents() {
    // 处理内容块事件的业务逻辑
}

四、完整使用示例

4.1 表单提交场景示例

@Controller
@RequestMapping("/api/user")
public class UserController {

    @PostMapping("/save")
    @ResponseBody
    @APIEventAnnotation(
        // 事件绑定
        bindFormEvent = CustomFormEvent.SAVE, // 绑定表单保存事件
        bindHotKeyEvent = CustomHotKeyEvent.CTRL_S, // 绑定Ctrl+S快捷键

        // 请求数据源
        requestDataSource = {
            @RequestPathAnnotation(type = "form", name = "userForm", path = "id"), // 从表单获取ID
            @RequestPathAnnotation(type = "form", name = "userForm", path = "name"), // 从表单获取姓名
            @RequestPathAnnotation(type = "form", name = "userForm", path = "email") // 从表单获取邮箱
        },

        // 响应数据目标
        responseDataTarget = {
            @ResponsePathAnnotation(type = "form", name = "userForm", path = "lastUpdateTime") // 将响应数据映射到表单的lastUpdateTime字段
        },

        // 生命周期回调
        beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示
        onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示
        onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示
    )
    public ResultModel<User> saveUser(@RequestBody User user) {
        // 业务逻辑实现
        User savedUser = userService.save(user);
        return ResultModel.success(savedUser);
    }
}

4.2 数据加载与分页场景示例

@Controller
@RequestMapping("/api/data")
public class DataController {

    @GetMapping("/list")
    @ResponseBody
    @APIEventAnnotation(
        // 事件绑定
        bindGridEvent = CustomGridEvent.LOAD, // 绑定表格加载事件
        autoRun = true, // 页面加载后自动执行

        // 请求数据源
        requestDataSource = {
            @RequestPathAnnotation(type = "component", name = "pageSize", path = "value"), // 从组件获取分页大小
            @RequestPathAnnotation(type = "component", name = "currentPage", path = "value") // 从组件获取当前页码
        },

        // 响应数据目标
        responseDataTarget = {
            @ResponsePathAnnotation(type = "grid", name = "dataGrid", path = "data") // 将响应数据映射到表格的数据字段
        },

        // 生命周期回调
       beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示
        onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示
        onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示    )
    public ResultModel<Page<Data>> loadData(@RequestParam Integer pageSize, @RequestParam Integer currentPage) {
        // 业务逻辑实现
        Page<Data> dataPage = dataService.findPage(pageSize, currentPage);
        return ResultModel.success(dataPage);
    }
}

4.3 树形组件操作场景示例

@Controller
@RequestMapping("/api/tree")
public class TreeController {

    @GetMapping("/nodes")
    @ResponseBody
    @APIEventAnnotation(
        // 事件绑定
        bindTreeEvent = CustomTreeEvent.EXPAND, // 绑定树形节点展开事件

        // 请求数据源
        requestDataSource = {
            @RequestPathAnnotation(type = "tree", name = "treeComponent", path = "selectedId") // 从树形组件获取选中节点ID
        },

        // 响应数据目标
        responseDataTarget = {
            @ResponsePathAnnotation(type = "tree", name = "treeComponent", path = "children") // 将响应数据映射到树形组件的子节点字段
        },

        // 生命周期回调
      beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示
        onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示
        onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示    )
    )
    public ResultModel<List<TreeNode>> loadTreeNodes(@RequestParam String parentId) {
        // 业务逻辑实现
        List<TreeNode> nodes = treeService.findChildren(parentId);
        return ResultModel.success(nodes);
    }
}

五、最佳实践与注意事项

5.1 事件绑定最佳实践

单一职责原则：每个 API 事件注解应专注于处理单一类型的事件或功能，避免绑定过多不相关的事件
合理选择事件类型：根据业务场景选择最合适的事件类型（如表单事件、表格事件等），避免使用通用事件代替特定事件
事件优先级设置：对于需要按特定顺序执行的多个 API 事件，通过index属性设置合理的执行顺序
事件解耦：避免在一个 API 事件中处理过多的业务逻辑，应将复杂业务逻辑分解为多个独立的 API 事件
事件命名规范：遵循统一的事件命名规范，提高代码可读性和可维护性

5.2 数据映射最佳实践

精简数据映射：只映射必要的数据字段，避免映射过多无关数据
数据验证前置：在数据映射前进行必要的验证，确保数据的有效性和完整性
数据转换处理：对于需要转换的数据（如日期格式转换），使用beforeData或onData回调进行处理
统一数据格式：保持前后端数据格式的一致性，减少数据转换的复杂度
敏感数据处理：对于敏感数据（如密码），应进行适当的加密或脱敏处理

5.3 生命周期回调最佳实践

清晰的回调逻辑：每个回调函数应具有明确的职责，避免逻辑混乱
错误处理全面：在onExecuteError和onError回调中处理所有可能的错误情况
资源清理：在afterInvok或afterInvokAction中释放所有占用的资源
用户反馈：在适当的回调中提供友好的用户反馈（如提示信息、加载状态）
避免阻塞操作：在回调函数中避免执行耗时的阻塞操作，以免影响用户体验

5.4 使用注意事项

注解作用域：@APIEventAnnotation 只能应用于 Controller 类的方法上，不能应用于类或其他类型的方法
事件重复绑定：避免在同一个方法上重复绑定相同的事件，否则可能导致不可预期的行为
数据映射冲突：注意避免数据映射路径冲突，确保每个数据字段有唯一的映射路径
异步执行注意事项：当queryAsync设置为true时，需注意异步执行可能带来的线程安全问题
异常处理：在 API 方法中必须处理所有可能抛出的异常，确保返回统一的 ResultModel 格式

5.5 常用动作枚举类

以下是一些常用的动作枚举类及其说明：

ActionTypeEnum

描述：基本动作类型枚举
核心值：
- SAVE: 保存操作
- DELETE: 删除操作
- UPDATE: 更新操作
- QUERY: 查询操作
- EXPORT: 导出操作

ButtonActionEnum

描述：按钮动作枚举
核心值：
- SUBMIT: 提交按钮
- CANCEL: 取消按钮
- RESET: 重置按钮
- CONFIRM: 确认按钮
- CLOSE: 关闭按钮

MenuActionEnum

描述：菜单动作枚举
核心值：
- NEW: 新建菜单
- OPEN: 打开菜单
- SAVE: 保存菜单
- DELETE: 删除菜单
- EXPORT: 导出菜单
- IMPORT: 导入菜单

TreeActionEnum

描述：树形组件动作枚举
核心值：
- EXPAND_ALL: 全部展开
- COLLAPSE_ALL: 全部折叠
- ADD_NODE: 添加节点
- DELETE_NODE: 删除节点
- EDIT_NODE: 编辑节点
- MOVE_NODE: 移动节点

这些动作枚举类可以与@APIEventAnnotation结合使用，实现更丰富的事件处理逻辑。例如：

@APIEventAnnotation(
    bindFormEvent = CustomFormEvent.SUBMIT,
    requestDataSource = "approvalDataSource",
    onExecuteSuccessAction = {
        @CustomAction(
            actionType = ActionTypeEnum.SAVE,
            params = {"status", "approved"}
        )
    }
)
public class ApprovalSubmitEvent {
    // 事件处理逻辑
}

六、子注解详解

6.1 RequestPathAnnotation

描述：请求路径注解，定义从前端组件到 API 参数的数据映射
属性：
- type: 组件类型（如 "form", "grid", "tree"）
- name: 组件名称
- path: 数据路径
- paramName: 参数名称（可选，默认使用 path）
- converter: 转换器类名（可选）
示例：@RequestPathAnnotation( type = "form", name = "mainForm", path = "id", converter = "EncryptConverter" )

6.2 ResponsePathAnnotation

描述：响应路径注解，定义从 API 响应到前端组件的数据映射
属性：
- type: 组件类型
- name: 组件名称
- path: 数据路径
- updateStrategy: 更新策略（如 UpdateStrategy.INCREMENT 增量更新）
示例：@ResponsePathAnnotation( type = "grid", name = "userGrid", path = "rows", updateStrategy = UpdateStrategy.INCREMENT )

6.3 AIGCAnnotation

描述：AI 增强注解，配置 AI 辅助处理的相关参数
属性：
- prompt: AI 提示语
- model: AI 模型名称
- cacheable: 是否缓存结果
- temperature: 生成温度
示例：@AIGCAnnotation( prompt = "优化查询参数: {{requestParams}}", model = "gpt-4", cacheable = true )

6.4 CustomAction

描述：自定义动作注解，定义要执行的动作
属性：
- name: 动作名称
- params: 动作参数
- async: 是否异步执行
示例：@CustomAction( name = "refreshGrid", params = {"{{response.data.gridId}}"}, async = true )

七、总结

@APIEventAnnotation 是 OneCode 3.0 框架中实现前后端交互的核心注解，通过该注解可以轻松实现事件绑定、数据映射和请求生命周期管理等功能。本手册详细介绍了 @APIEventAnnotation 的所有属性、核心事件枚举以及使用示例，希望能帮助开发者更高效地使用 OneCode 3.0 框架进行企业级应用开发。

通过合理使用 @APIEventAnnotation，开发者可以将传统开发中大量的样板代码和配置工作简化为简洁的注解声明，从而更专注于业务逻辑的实现，提高开发效率和代码质量。在实际开发中，应根据具体业务场景选择合适的属性和事件，遵循最佳实践，以充分发挥 OneCode 3.0 框架的强大功能。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

低代码

人工智能

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

低代码

人工智能