OneCode3.0 @ComboInput组件注解开发使用手册

原创

OneCode

发布于 2025-07-23 14:07:06

1690

OneCode3.0 ComboInput 开发使用手册

1. 引言

在 OneCode3.0 开发框架中，ComboInput 是一类强大的复合输入组件，它结合了输入框和下拉选择器的特性，能够满足各种复杂的业务需求。本手册将详细介绍 ComboInput 组件的核心注解、使用方法和最佳实践，帮助开发者快速掌握并应用这一组件。

2. ComboInput 组件概述

ComboInputComponent 是 OneCode 框架中的复合输入框组件，继承自 FieldComponent<ComboInputProperties, FieldEventEnum>，用于在 UI 界面中提供复合输入功能。该组件支持多种配置选项，能够满足不同的业务需求。

核心特性

支持多种类型的复合输入（下拉框、文件选择器、日期选择器等）
提供丰富的配置属性
支持数据绑定和懒加载
支持多选和单选模式
支持自定义样式和行为

3. OneCode3.0 新特性

OneCode3.0 最大的改进包括：

将原有注解中的数据属性抽象为独立的数据集合注解 @CustomListAnnotation
对注解进行更细致的拆分，ComboBoxAnnotation 作为容器配置只保持容器属性，原有字段属性以 @ComboInputAnnotation 定义，而 caption 等通用字段则由 @CustomAnnotation 定义

新旧版本对比

旧版本：数据属性、字段属性和通用属性分散在各个组件注解中，难以复用和统一管理
新版本：通过 @CustomListAnnotation 统一管理数据集合，通过 @ComboInputAnnotation 管理字段属性，通过 @CustomAnnotation 管理通用字段，提高了代码的复用性和可维护性

注解拆分详情

3.1 ComboBoxAnnotation

@ComboBoxAnnotation 现在只保留容器相关的属性，专注于下拉框的容器配置：

public @interface ComboBoxAnnotation {
    String listKey() default "";
    String dropImageClass() default "";
    int dropListWidth() default 0;
    int dropListHeight() default 0;
}

3.2 ComboInputAnnotation

@ComboInputAnnotation 负责定义字段相关的属性：

public @interface ComboInputAnnotation {
    String expression() default "";
    String imageBgSize() default "";
    String imageClass() default "";
    String iconFontCode() default "";
    String unit() default "";
    String units() default "";
    String tips() default "";
    String commandBtn() default "";
    String labelCaption() default "";
    @NotNull
    ComboInputType inputType() default ComboInputType.input;
    boolean inputReadonly() default false;
}

3.3 CustomAnnotation

@CustomAnnotation 包含通用的字段属性，如 caption、id 等：

public @interface CustomAnnotation {
    String id() default "";
    String caption() default "";
    String[] enums() default {};
    Class<? extends Enum> enumClass() default Enum.class;
    @NotNull
    boolean uid() default false;
    ComboInputType inputType() default ComboInputType.none;
    @NotNull
    boolean pid() default false;
    boolean captionField() default false;
    boolean readonly() default false;
    boolean disabled() default false;
    String target() default "";
    @NotNull
    boolean hidden() default false;
    int index() default 0;
    String tips() default "";
    String imageClass() default "";
    IconColorEnum iconColor() default IconColorEnum.NONE;
    ItemColorEnum itemColor() default ItemColorEnum.NONE;
    FontColorEnum fontColor() default FontColorEnum.NONE;
}

3.4 OneCode 3.0 版本升级建议

重构现有代码：将旧版本中分散在各个注解中的属性，按照新的注解分类进行重构
使用数据集合：充分利用 @CustomListAnnotation 来统一管理数据集合，提高代码复用性
明确注解职责：
- 容器属性使用 @ComboBoxAnnotation
- 字段属性使用 @ComboInputAnnotation
- 通用属性使用 @CustomAnnotation
更新依赖：确保项目依赖的 OneCode 库是 3.0 版本
测试兼容性：在升级后，彻底测试代码的兼容性，确保功能正常
参考示例：查看新版本的示例代码，了解如何正确使用新的注解

通过这些改进，您的代码将更加清晰、可维护，并且能够充分利用 OneCode 3.0 的新特性

4. 核心注解分类

根据功能和适用场景的不同，ComboInput 相关的注解可以分为以下几类：

4.1 通用属性类

CustomAnnotation：配置组件的通用属性，如 id、caption 等

4.2 容器属性类

ComboBoxAnnotation：配置下拉框组件的容器属性
ComboHelpAnnotation：配置帮助下拉框组件的容器属性

4.3 字段属性类

ComboInputAnnotation：配置下拉框组件的字段属性
ComboFileAnnotation：配置文件选择器组件的字段属性
ComboImageAnnotation：配置图片下拉框组件的字段属性
ComboDateAnnotation：配置日期选择器组件的字段属性

4.4 数据获取类

ComboGetterAnnotation：配置获取器下拉框组件

4.5 数据集合类

CustomListAnnotation：配置数据集合

5. 常用注解详解

5.1 ComboBoxAnnotation

@CustomClass(clazz = CustomComboBoxComponent.class,
        viewType = CustomViewType.COMBOBOX,
        inputType = ComboInputType.combobox,
        componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboxFieldBean.class)
public @interface ComboBoxAnnotation {
    String listKey() default "";
    String dropImageClass() default "";
    int dropListWidth() default 0;
    int dropListHeight() default 0;
}

字段解释：

listKey：下拉列表数据的键名
dropImageClass：下拉图标样式类
dropListWidth：下拉列表宽度
dropListHeight：下拉列表高度

适用场景：用于配置下拉框组件的容器属性，如列表宽度、高度和图标样式等。

5.2 ComboInputAnnotation

@CustomClass(clazz = CustomComboInputComponent.class,
        viewType = CustomViewType.COMBOBOX,
        inputType = {ComboInputType.input},
        componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboInputFieldBean.class)
public @interface ComboInputAnnotation {
    String expression() default "";
    String imageBgSize() default "";
    String imageClass() default "";
    String iconFontCode() default "";
    String unit() default "";
    String units() default "";
    String tips() default "";
    String commandBtn() default "";
    String labelCaption() default "";
    @NotNull
    ComboInputType inputType() default ComboInputType.input;
    boolean inputReadonly() default false;
}

字段解释：

expression：表达式
imageBgSize：图片背景大小
imageClass：图片样式类
iconFontCode：图标字体代码
unit：单位
units：单位列表
tips：提示信息
commandBtn：命令按钮
labelCaption：标签标题
inputType：输入类型
inputReadonly：是否只读

适用场景：用于配置下拉框组件的字段属性，如输入类型、提示信息和只读状态等。

5.3 CustomAnnotation

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = CustomFieldBean.class)
public @interface CustomAnnotation {
    String id() default "";
    String caption() default "";
    String[] enums() default {};
    Class<? extends Enum> enumClass() default Enum.class;
    @NotNull
    boolean uid() default false;
    ComboInputType inputType() default ComboInputType.none;
    @NotNull
    boolean pid() default false;
    boolean captionField() default false;
    boolean readonly() default false;
    boolean disabled() default false;
    String target() default "";
    @NotNull
    boolean hidden() default false;
    int index() default 0;
    String tips() default "";
    String imageClass() default "";
    IconColorEnum iconColor() default IconColorEnum.NONE;
    ItemColorEnum itemColor() default ItemColorEnum.NONE;
    FontColorEnum fontColor() default FontColorEnum.NONE;
}

字段解释：

id：组件的唯一标识符
caption：组件的标题
enums：枚举值数组
enumClass：枚举类
uid：是否为唯一标识符
inputType：输入类型
pid：是否为父标识符
captionField：是否为标题字段
readonly：是否只读
disabled：是否禁用
target：目标
hidden：是否隐藏
index：索引
tips：提示信息
imageClass：图片样式类
iconColor：图标颜色
itemColor：项目颜色
fontColor：字体颜色

适用场景：用于配置组件的通用属性，如ID、标题、是否只读和隐藏状态等。

适用场景：用于配置下拉框组件，支持多选、懒加载和数据绑定等属性设置，特别适合创建下拉选择器。

5.2 ComboFileannotation

@CustomClass(clazz = CustomComboInputComponent.class, viewType = CustomViewType.COMBOBOX, inputType = {ComboInputType.file}, componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboFileFieldBean.class)
public @interface ComboFileAnnotation {
    String fileAccept() default "";
    boolean fileMultiple() default true;
}

字段解释：

id：组件的唯一标识符
caption：组件的标题
iconFontCode：图标字体代码
width：组件的宽度，默认为 18.0em
accept：接受的文件类型，默认为 */*
multiple：是否支持多选，默认为 false
maxSize：最大文件大小，默认为 10485760 (10MB)
url：文件上传的URL
params：请求参数
fileNameField：文件名字段，默认为 fileName
fileUrlField：文件URL字段，默认为 fileUrl

适用场景：用于配置文件选择器组件，支持文件类型、大小限制和多选等属性设置，特别适合创建文件上传界面。

5.3 ComboDateAnnotation

@CustomClass(clazz = CustomComboInputComponent.class, viewType = CustomViewType.COMBOBOX, inputType = {ComboInputType.date, ComboInputType.datetime, ComboInputType.time}, componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboDateFieldBean.class)
public @interface ComboDateAnnotation {
    String dateEditorTpl() default "";
}

字段解释：

dateEditorTpl：日期编辑器模板字符串

适用场景：用于配置日期选择器组件，支持日期格式、范围和时间显示等属性设置，特别适合创建日期选择界面。

5.4 ComboImageAnnotation

@CustomClass(clazz = CustomComboInputComponent.class, viewType = CustomViewType.COMBOBOX, inputType = {ComboInputType.image}, componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboImageFieldBean.class)
public @interface ComboImageAnnotation {
    String image() default "";
    ImagePos imagePos() default ImagePos.center;
}

字段解释：

image：默认图片路径
imagePos：图片位置，枚举值包括 left、center、right

适用场景：用于配置图片下拉框组件，支持默认图片和位置设置，适合创建带图片的选择界面。

5.5 ComboHelpAnnotation

@CustomClass(clazz = CustomComboListComponent.class, viewType = CustomViewType.COMBOBOX,
        inputType = ComboInputType.helpinput,
         componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboHelpFieldBean.class)
public @interface ComboHelpAnnotation {
    String listKey() default "";
    String dropImageClass() default "";
    int dropListWidth() default 0;
    int dropListHeight() default 0;
    ComboInputType inputType() default ComboInputType.helpinput;
}

字段解释：

listKey：帮助列表数据的键名
dropImageClass：下拉图标样式类
dropListWidth：下拉列表宽度
dropListHeight：下拉列表高度
inputType：输入类型，默认为帮助输入类型

适用场景：用于配置帮助下拉框组件，支持列表数据键名、图标样式和尺寸设置，适合创建带帮助信息的下拉选择界面。

5.6 ComboGetterAnnotation

@CustomClass(clazz = CustomComboListComponent.class, viewType = CustomViewType.COMBOBOX,
        inputType = ComboInputType.helpinput,
         componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboHelpFieldBean.class)
public @interface ComboHelpAnnotation {
    String listKey() default "";
    String dropImageClass() default "";
    int dropListWidth() default 0;
    int dropListHeight() default 0;
    ComboInputType inputType() default ComboInputType.helpinput;
}

字段解释：

listKey：帮助列表数据的键名
dropImageClass：下拉图标样式类
dropListWidth：下拉列表宽度
dropListHeight：下拉列表高度
inputType：输入类型，默认为帮助输入类型

适用场景：用于配置帮助下拉框组件，支持列表数据键名、图标样式和尺寸设置，适合创建带帮助信息的下拉选择界面。

5.7 ComboGetterAnnotation

@CustomClass(clazz = CustomComboPopComponent.class, viewType = CustomViewType.COMBOBOX,
        inputType = ComboInputType.getter, componentType = ComponentType.ComboInput)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = ComboGetterFieldBean.class)
public @interface ComboGetterAnnotation {
    String parentID() default "";
    boolean cachePopWnd() default true;
    @NotNull
    String width() default "18.0em";
    @NotNull
    String height() default "5.0em";
    String src() default "";
    boolean dynLoad() default false;
    ComboInputType inputType() default ComboInputType.getter;
    Class bindClass() default Void.class;
}

字段解释：

parentID：父组件ID
cachePopWnd：是否缓存弹出窗口，默认为true
width：组件宽度，默认为18.0em
height：组件高度，默认为5.0em
src：数据源URL
dynLoad：是否动态加载，默认为false
inputType：输入类型，默认为ComboInputType.getter
bindClass：绑定的类，默认为Void.class

适用场景：用于配置获取器下拉框组件，支持父组件ID、缓存、尺寸和数据源设置，适合创建需要动态获取数据的下拉选择界面。

5.8 CustomListAnnotation

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.FIELD})
@BeanClass(clazz = CustomListBean.class)
public @interface CustomListAnnotation {
    String id() default "";

    Class bindClass() default Void.class;

    Class<? extends Enum> enumClass() default Enum.class;

    @NotNull
    boolean dynLoad() default true;

    String filter() default "";

    String[] enums() default {};

    String itemsExpression() default "";
}

字段解释：

id：数据集合的唯一标识符
bindClass：绑定的类，默认为Void.class
enumClass：枚举类，默认为Enum.class
dynLoad：是否动态加载，默认为true
filter：过滤条件
enums：枚举值数组
itemsExpression：项目表达式

适用场景：用于配置数据集合，支持动态加载、过滤和枚举值设置，适合创建可复用的数据集合，为各种组件提供数据支持。

使用示例：

// 定义一个数据集合
@CustomListAnnotation(
    id = "userList",
    bindClass = User.class,
    dynLoad = true,
    filter = "status=1"
)
public List<User> getUserList() {
    // 实现数据获取逻辑
    return userService.findAll();
}

// 在组件中使用数据集合
@ComboBoxAnnotation(
    id = "userComboBox",
    caption = "用户选择",
    dataPath = "userList",
    textField = "username",
    idField = "id"
)
public String userId;

通过 @CustomListAnnotation，我们可以将数据集合的定义与组件的定义分离，提高代码的复用性和可维护性。同一个数据集合可以被多个组件引用，避免了数据逻辑的重复实现。

bindClass：绑定类，默认为Void.class

适用场景：用于配置获取器下拉框组件，支持父组件关联、弹窗缓存和动态加载设置，适合创建需要关联数据获取的下拉选择界面。

6. 使用示例

6.1 基本使用示例

// 下拉框示例 - 结合多个注解
@CustomAnnotation(
    id = "userTypeComboBox",
    caption = "用户类型"
)
@ComboBoxAnnotation(
    listKey = "userTypesList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String userType;

// 日期选择器示例
@CustomAnnotation(
    id = "birthday",
    caption = "出生日期"
)
@ComboDateAnnotation(
    dateEditorTpl = "yyyy-MM-dd"
)
private Date birthday;

// 文件选择器示例
@CustomAnnotation(
    id = "avatar",
    caption = "头像上传"
)
@ComboFileAnnotation(
    fileAccept = "image/*",
    fileMultiple = false
)
private String avatar;

// 数据集合示例
@CustomListAnnotation(
    id = "userTypeList",
    bindClass = UserType.class,
    dynLoad = true,
    filter = "status=1"
)
public List<UserType> getUserTypes() {
    // 实现数据获取逻辑
    return userTypeService.findAll();
}

6.2 高级使用示例

// 带懒加载的下拉框
@CustomAnnotation(
    id = "departmentComboBox",
    caption = "部门选择"
)
@ComboBoxAnnotation(
    listKey = "departmentList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String departmentId;

// 支持多选的图片下拉框
@CustomAnnotation(
    id = "tagSelector",
    caption = "标签选择"
)
@ComboImageAnnotation(
    image = "/images/tag-default.png",
    imagePos = ImagePos.left
)
private List<String> tagIds;

// 关联数据集合的帮助输入框
@CustomAnnotation(
    id = "productHelpInput",
    caption = "产品帮助"
)
@ComboHelpAnnotation(
    listKey = "productList",
    dropListWidth = 400
)
private String productId;

// 高级数据集合示例
@CustomListAnnotation(
    id = "departmentList",
    bindClass = Department.class,
    dynLoad = true,
    filter = "status=1 and parentId=:parentId",
    itemsExpression = "${item.name} (${item.code})"
)
public List<Department> getDepartmentList(String parentId) {
    // 实现带参数的数据获取逻辑
    return departmentService.findByParentId(parentId);
}

6. 最佳实践

合理选择注解类型：根据业务需求选择合适的 ComboInput 注解类型，特别是区分 @CustomAnnotation、@ComboBoxAnnotation 和 @ComboInputAnnotation 的使用场景
设置唯一标识符：确保每个组件的 id 是唯一的
优化数据加载：对于大数据量的情况，使用 @CustomListAnnotation 的 dynLoad 属性实现动态加载
明确注解职责：遵循 OneCode 3.0 的注解拆分原则，容器属性使用 @ComboBoxAnnotation，字段属性使用 @ComboInputAnnotation，通用属性使用 @CustomAnnotation
设置适当的默认值：为常用属性设置适当的默认值，减少代码量
使用数据绑定：充分利用 dataPath、textField 和 idField 等属性实现数据绑定
善用数据集合：对于可复用的数据，使用 @CustomListAnnotation 定义独立的数据集合
动态过滤：使用 filter 属性实现数据的动态过滤
表达式增强：利用 itemsExpression 属性增强数据的显示格式
避免重复数据逻辑：同一个数据集合可以被多个组件引用，避免重复实现数据获取逻辑

7. 常见问题解答

7.1 如何实现 ComboInput 组件的数据源动态加载？

可以通过以下两种方式实现数据源的动态加载：

对于 ComboBoxAnnotation，设置 listKey 属性指向一个动态加载的数据集合。

@CustomAnnotation(
    id = "dynamicComboBox",
    caption = "动态下拉框"
)
@ComboBoxAnnotation(
    listKey = "dynamicDataList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String dynamicValue;

使用 @CustomListAnnotation 定义一个动态加载的数据集合，并在组件中引用它。

@CustomListAnnotation(
    id = "dynamicDataList",
    bindClass = DynamicData.class,
    dynLoad = true
)
public List<DynamicData> getDynamicDataList() {
    // 实现动态数据获取逻辑
    return dynamicDataService.findAll();
}

@CustomAnnotation(
    id = "dynamicComboBox",
    caption = "动态下拉框"
)
@ComboBoxAnnotation(
    listKey = "dynamicDataList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String dynamicValue;

7.2 如何在多个组件间共享同一个数据集合？

使用 @CustomListAnnotation 可以轻松实现数据集合的共享。只需要定义一个数据集合，然后在多个组件中通过 listKey 属性引用它即可。

// 定义共享的数据集合
@CustomListAnnotation(
    id = "sharedList",
    bindClass = SharedData.class,
    dynLoad = true
)
public List<SharedData> getSharedList() {
    return sharedDataService.findAll();
}

// 组件1引用数据集合
@CustomAnnotation(
    id = "combo1",
    caption = "组件1"
)
@ComboBoxAnnotation(
    listKey = "sharedList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String value1;

// 组件2引用同一个数据集合
@CustomAnnotation(
    id = "combo2",
    caption = "组件2"
)
@ComboBoxAnnotation(
    listKey = "sharedList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String value2;

7.3 如何为数据集合设置过滤条件？

可以使用 @CustomListAnnotation 的 filter 属性来设置过滤条件。过滤条件可以包含参数，参数值可以从上下文中获取。

@CustomListAnnotation(
    id = "filteredList",
    bindClass = FilteredData.class,
    dynLoad = true,
    filter = "status=1 and category=:category"
)
public List<FilteredData> getFilteredList(String category) {
    return filteredDataService.findByCategory(category);
}

7.4 如何自定义数据集合中项目的显示格式？

可以使用 @CustomListAnnotation 的 itemsExpression 属性来自定义项目的显示格式。表达式中可以引用项目的属性。

@CustomListAnnotation(
    id = "formattedList",
    bindClass = FormattedData.class,
    dynLoad = true,
    itemsExpression = "${item.name} - ${item.description}"
)
public List<FormattedData> getFormattedList() {
    return formattedDataService.findAll();
}

7.5 如何设置 ComboInput 组件的默认值？

可以在对应的字段上设置默认值，框架会自动将其绑定到组件上。

@CustomAnnotation(
    id = "defaultValueComboBox",
    caption = "带默认值的下拉框"
)
@ComboBoxAnnotation(
    listKey = "dataList"
)
@ComboInputAnnotation(
    inputType = ComboInputType.combobox
)
private String defaultValue = "1";

7.6 如何实现 ComboInput 组件的多选功能？

可以在 @ComboInputAnnotation 中设置 inputType 为支持多选的类型，并结合 @CustomAnnotation 的相关属性来实现。

7.7 如何自定义 ComboInput 组件的样式？

可以通过设置 @ComboInputAnnotation 的 imageClass、iconFontCode 等属性来自定义组件的样式，也可以通过 CSS 来进一步定制。

7.8 如何处理 ComboInput 组件的事件？

可以通过监听 FieldEventEnum 中的事件来处理 ComboInput 组件的各种事件，如选择事件、变化事件等。

8. 总结

OneCode3.0 的 ComboInput 组件是一类强大的复合输入组件，它通过丰富的注解配置，能够满足各种复杂的业务需求。本手册介绍了 ComboInput 组件的核心注解、使用方法和最佳实践，希望能够帮助开发者快速掌握并应用这一组件。在实际开发中，建议根据具体的业务需求，合理选择和配置 ComboInput 组件，以提高开发效率和用户体验。

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

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

人工智能

低代码

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

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

人工智能

低代码