下拉框 - CUBA 框架开发者手册

3.5.2.1.25. 下拉框

该控件支持从下拉列表中选择值。下拉列表提供基于用户的输入对数据进行过滤的功能，也支持分页显示数据。

该组件的 XML 名称是： lookupField

使用 LookupField 下拉框最简单的例子是从实体属性中选择枚举值。比如，Role 角色实体中有 type 属性，为枚举类型。用户可以通过 LookupField 下拉框控件编辑该属性：
```
<data>
    <instance id="roleDc"
              class="com.haulmont.cuba.security.entity.Role"
              view="_local">
        <loader/>
    </instance>
</data>
<layout expand="editActions" spacing="true">
    <lookupField dataContainer="roleDc" property="type"/>
</layout>
```
在上面的例子中，使用 roleDc 数据容器选择 Role 实体数据。lookupField 下拉框组件中，数据容器的连接通过 dataContainer 属性定义，实体属性的名称定义在 property 属性中。此时，这个属性为枚举类型，控件的下拉列表中会显示所有枚举值的本地化名称。

类似的，LookupField 下拉框也可以用来选择实体实例。选项容器属性可以用来创建一系列选项：

<data>
    <instance id="carDc" class="com.haulmont.sample.core.entity.Car" view="carEdit">
        <loader/>
    </instance>
    <collection id="colorsDc" class="com.haulmont.sample.core.entity.Color" view="_minimal">
        <loader id="colorsDl">
            <query>
                <![CDATA[select e from sample_Color e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <lookupField dataContainer="carDc" property="color" optionsContainer="colorsDc"/>
</layout>

这种时候，colorsDc 数据容器中的 Color 实体的实例名称会显示在下拉列表中，被选择的值会被设置到 carDc 数据容器中 Car 实体的 color 属性中。

captionProperty定义显示到下拉框的实体属性值，而非实例名称，这样可以设置下拉列表的文字值。

使用 setOptionCaptionProvider() 方法可以为 LookupField 组件显示的字符串选项名定义标题：
```
lookupField.setOptionCaptionProvider((item) -> item.getLocalizedName());
```
选项列表还可以通过 setOptionsList()，setOptionsMap() 和 setOptionsEnum() 设置，也可以在 XML 描述中通过 optionsContainer 属性设置。
- setOptionsList() - 通过代码指定选项列表。首先在 XML 描述中声明组件：
  
  <lookupField id="numberOfSeatsField" dataContainer="modelDc" property="numberOfSeats"/>
  
  然后将组件注入界面控制器，在 onInit() 方法中设置选项列表：
  
  @Inject protected LookupField<Integer> numberOfSeatsField; @Subscribe public void onInit(InitEvent event) { List<Integer> list = new ArrayList<>(); list.add(2); list.add(4); list.add(5); list.add(7); numberOfSeatsField.setOptionsList(list); }
  
  组件的下拉列表中会显示 2, 4, 5 和 7。被选择的值会设置到 modelDc 数据容器中的 numberOfSeats 属性上。
- setOptionsMap() 可以提供选项 map。比如为 XML 描述中声明的 numberOfSeatsField 组件指定选项 map（在 onInit() 方法中）:
  
  @Inject protected LookupField<Integer> numberOfSeatsField; @Subscribe public void onInit(InitEvent event) { Map<String, Integer> map = new LinkedHashMap<>(); map.put("two", 2); map.put("four", 4); map.put("five", 5); map.put("seven", 7); numberOfSeatsField.setOptionsMap(map); }
  
  组件下拉框会显示 two，four，five，seven 文本。但是组件的值则是与文本对应的数字值。数字值会被设置到 modelDc 数据容器中的 numberOfSeats 属性上。
- setOptionsEnum() 需要枚举类做为参数。下拉列表会显示枚举值的本地化名称，组件的值则为枚举值。

setPopupWidth() 可以设置下拉列表的宽度，宽度用字符串格式传递给该方法。使用相对单位（比如，"50%"）可以设置下拉列表的宽度是针对于 LookupField 本身的相对值。默认情况下，该宽度设置为 null，下拉列表的宽度为了适应显示内容的宽度而可以大于组件的宽度。通过设置该值为 "100%"，可以使得下拉列表的宽度等于 LookupField 的宽度。

通过 setOptionStyleProvider() 可以为组件显示的不同的选项设置分别的 style name：

lookupField.setOptionStyleProvider(entity -> {
    User user = (User) entity;
    switch (user.getGroup().getName()) {
        case "Company":
            return "company";
        case "Premium":
            return "premium";
        default:
            return "company";
    }
});

下拉列表中的组件可以在左边设置对应的图标。在界面控制器中使用 setOptionIconProvider() 方法设置：

lookupField.setOptionIconProvider(entity -> {
    if (entity.getType() == LegalStatus.LEGAL)
        return "icons/icon-office.png";
    return "icons/icon-user.png";
});

如果使用 SVG 图标, 显式设置图标大小以避免图标覆盖。

<svg version="1.1"
     id="Capa_1"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xml:space="preserve"

     style="enable-background:new 0 0 55 55;"
     viewBox="0 0 55 55"

     height="25px"
     width="25px">

setOptionImageProvider() 方法可以定义 LookupField 组件显示的选项图片。该方法设置一个接收资源类型参数的函数。

@Inject
private LookupField<Customer> lookupField;
@Inject
private Image imageResource;

@Subscribe
private void onInit(InitEvent event) {
   lookupField.setOptionImageProvider(e ->
      imageResource.createResource(ThemeResource.class).setPath("icons/radio.svg"));
}

如果 LookupField 下拉框组件非required，并且对应的实体属性也非必须，下拉选项会包含一个空行。如果选择了空行，组件值为 null. 使用 nullName 属性设置在“空行”上显示的文本。以下为一个示例：
```
<lookupField dataContainer="carDc" property="colour" optionsContainer="colorsDs" nullName="(none)"/>
```
这样，下拉框中的“空行”上会显示 (none) 文本。如果用户选择了该行，对应的实体属性值会设置为 null。

如果在代码中通过 setOptionsList() 设置了选项, 可以用 setNullOption() 方法设置空行文本，这样，如果用户选择了该行，组件值则为 null。
LookupField 过滤器：
filterMode 属性设置基于用户输入的过滤模式：

NO − 不过滤。

STARTS_WITH − 选项文本以用户输入开头。

CONTAINS − 选项文本包含用户输入（默认模式）。

setFilterPredicate() 方法用来设置过滤方法，该方法判断元素是否跟查找文字匹配。比如：

BiFunction<String, String, Boolean> predicate = String::contains; lookupField.setFilterPredicate((itemCaption, searchString) -> predicate.apply(itemCaption.toLowerCase(), searchString));

FilterPredicate 的 test 方法可以用来客户化过滤逻辑，比如处理方言/特殊字符：

lookupField.setFilterPredicate((itemCaption, searchString) -> StringUtils.replaceChars(itemCaption, "ÉÈËÏÎ", "EEEII") .toLowerCase() .contains(searchString));

LookupField 组件在没有合适选项的时候可以处理用户的输入，通过 setNewOptionHandler() 来处理，示例：
```
@Inject
private Metadata metadata;
@Inject
private LookupField<Color> colorField;
@Inject
private CollectionContainer<Color> colorsDc;

@Subscribe
protected void onInit(InitEvent event) {
    colorField.setNewOptionHandler(caption -> {
        Color color = metadata.create(Color.class);
        color.setName(caption);
        colorsDc.getMutableItems()
                .add(color);
        colorField.setValue(color);
    });
}
```
当用户输入不匹配任何选项的值并且按下回车键时，会触发调用新选项处理器。这时，上述代码会创建一个新的 Color 实例，name 属性值为用户输入，并且这个实例会加到下拉选项数据容器中，做为该控件当前被选中值。

除了使用 setNewOptionHandler() 方法来处理用户输入，还可以在 XML 描述中通过 newOptionHandler 属性来指定控制器处理的方法。这个方法需要两个参数，一个是 LookupField 类型，指向组件实例，另一个是 String 类型，指向用户输入。newOptionAllowed 属性也可以用来开启是否允许输入新值。

nullOptionVisible XML 属性设置是否在下拉列表显示空值。可以配置 LookupField 下拉框非 required但是不提供空值选项。

textInputAllowed 属性可以禁止过滤器功能及键盘输入。对短列表来说很方便。默认值为 true。

pageLength 属性重新设置下拉列表中一页选项的个数，默认值在cuba.gui.lookupFieldPageLength应用程序属性中定义。
在基于 Halo 主题的 Web 客户端，可以自定义样式，通过 XML stylename 属性或在界面控制器中通过代码设置：
<lookupField id="lookupField" stylename="borderless"/>
通过代码设置时，从 HaloTheme 类中选择 LOOKUPFIELD_ 开头的常量样式：
lookupField.setStyleName(HaloTheme.LOOKUPFIELD_BORDERLESS);
LookupField 下拉框样式有:
- align-center - 文本居中对齐。
- align-right - 文本靠右对齐。
- borderless - 文本不要边框和背景。

LookupField 下拉框属性列表: align - caption - captionAsHtml - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - filterMode - height - htmlSanitizerEnabled - icon - id - inputPrompt - newOptionAllowed - newOptionHandler - nullName - nullOptionVisible - optionsContainer - optionsEnum - pageLength - property - required - requiredMessage - stylename - tabIndex - textInputAllowed - visible - width
LookupField 下拉框元素: validator
LookupField 下拉框样式: align-right - align-center - borderless - huge - large - small - tiny
API: addValueChangeListener - commit - discard - isModified - setContextHelpIconClickHandler - setFilterPredicate - setOptionCaptionProvider - setOptionImageProvider - setOptionsEnum - setOptionsList - setOptionsMap - setOptionsStyleProvider - setPopupWidth