本文档详细介绍了OneCode3.0框架中的ComboInput组件，这是一种强大的复合输入组件，结合了输入框和下拉选择器的功能。文章深入阐述了其核心注解，包括通用属性、容器属性、字段属性以及数据获取和集合类注解，并提供了新旧版本对比及注解拆分详情。通过一系列使用示例和最佳实践，帮助开发者理解如何有效地利用ComboInput组件来满足复杂的业务需求，提升开发效率和用户体验。同时，还解答了关于数据源动态加载、数据集合共享、过滤条件设置和显示格式自定义等常见问题。

✨ **OneCode3.0 引入新的注解体系以优化 ComboInput 组件**：新版本将数据属性抽象为 @CustomListAnnotation，并精细拆分注解，如 @ComboBoxAnnotation 负责容器配置，@ComboInputAnnotation 管理字段属性，@CustomAnnotation 处理通用字段。这种设计提高了代码的复用性和可维护性，解决了旧版本中属性分散难以管理的问题。

🗂️ **ComboInput 组件支持多种复合输入类型并提供丰富配置**：该组件能满足下拉框、文件选择器、日期选择器等多种复合输入需求，并提供丰富的配置属性，如数据绑定、懒加载、多选/单选模式以及自定义样式和行为，使其能够灵活适应不同的业务场景。

🔧 **核心注解分类清晰，功能明确**：注解被分为通用属性类（如 @CustomAnnotation）、容器属性类（如 @ComboBoxAnnotation, @ComboHelpAnnotation）、字段属性类（如 @ComboInputAnnotation, @ComboFileAnnotation, @ComboImageAnnotation, @ComboDateAnnotation）、数据获取类（@ComboGetterAnnotation）和数据集合类（@CustomListAnnotation），开发者可根据需求精确选择和配置。

💡 **提供了详尽的使用示例和最佳实践指导**：文章通过基本和高级使用示例，展示了如何结合使用不同注解来创建下拉框、日期选择器、文件选择器等，并给出了关于合理选择注解、设置唯一标识符、优化数据加载、明确注解职责、善用数据集合等方面的实践建议。

❓ **解答了 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.0emaccept：接受的文件类型，默认为 */*multiple：是否支持多选，默认为 falsemaxSize：最大文件大小，默认为 10485760 (10MB)url：文件上传的URLparams：请求参数fileNameField：文件名字段，默认为 fileNamefileUrlField：文件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```java@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：父组件IDcachePopWnd：是否缓存弹出窗口，默认为truewidth：组件宽度，默认为18.0emheight：组件高度，默认为5.0emsrc：数据源URLdynLoad：是否动态加载，默认为falseinputType：输入类型，默认为ComboInputType.getterbindClass：绑定的类，默认为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.classenumClass：枚举类，默认为Enum.classdynLoad：是否动态加载，默认为truefilter：过滤条件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 组件，以提高开发效率和用户体验。