3.5.2.1.41. 建议字段

在线示例

API 文档

SuggestionField 组件用于根据用户输入的字符串搜索一些值。它与 SuggestionPickerField 的不同之处在于它可以使用任何类型的选项：例如，实体、字符串或枚举值，并且没有操作按钮。选项列表是根据应用程序开发人员定义的逻辑在后端加载。

该组件的 XML 名称： suggestionField

suggestionField 的属性:

• asyncSearchDelayMs - 设置最后一次按键操作和执行异步搜索之前需要的延迟。

• minSearchStringLength - 设置执行建议搜索需要的最小字符串长度。

• popupWidth - 设置建议选项弹出框的宽度。

可选项：

• auto - 弹出框的宽度等于建议选项的最大长度，即自适应，

• parent - 弹出框的宽度等于主组件的宽度，

• 绝对（比如 "170px"）或相对（比如 "50%"）值。

• suggestionsLimit - 设置可显示的建议选项的最大数量。

suggestionField 的元素：

• query - 用于定义获取建议值的可选元素。query 元素有以下属性：

• entityClass（必须） - 实体类的完全限定名。

• view - 可选属性，指定用于加载查询实体的视图。

• escapeValueForLike - 允许搜索关键字中包含特殊符号：% 、 \ 等。默认值为 false。

• searchStringFormat - 搜索字符串格式，一个 Groovy 字符串，可以使用任何有效的 Groovy 字符串表达式。

<suggestionField id="suggestionField"
                 captionProperty="login">
    <query entityClass="com.haulmont.cuba.security.entity.User"
           escapeValueForLike="true"
           view="user.edit"
           searchStringFormat="%$searchString%">
        select e from sec$User e where e.login like :searchString escape '\'
    </query>
</suggestionField>

如果未定义查询，则必须使用 SearchExecutor 提供选项列表，以编程方式分配（见下文）。

大部分情况下，给组件设置 SearchExecutor 就足够了。SearchExecutor 是一个包含单个方法的功能接口：List<E> search(String searchString，Map <String,Object> searchParams)：

suggestionField.setSearchExecutor((searchString, searchParams) -> {
    return Arrays.asList(entity1, entity2, ...);
});

SearchExecutor 可以返回任何类型的选项，例如实体、字符串或枚举值。

• 实体：

customersDs.refresh();
List<Customer> customers = new ArrayList<>(customersDs.getItems());
suggestionField.setSearchExecutor((searchString, searchParams) ->
        customers.stream()
                .filter(customer -> StringUtils.containsIgnoreCase(customer.getName(), searchString))
                .collect(Collectors.toList()));

• 字符串：

List<String> strings = Arrays.asList("Red", "Green", "Blue", "Cyan", "Magenta", "Yellow");
stringSuggestionField.setSearchExecutor((searchString, searchParams) ->
        strings.stream()
                .filter(str -> StringUtils.containsIgnoreCase(str, searchString))
                .collect(Collectors.toList()));

• 枚举：

List<SendingStatus> enums = Arrays.asList(SendingStatus.values());
enumSuggestionField.setSearchExecutor((searchString, searchParams) ->
        enums.stream()
                .map(sendingStatus -> messages.getMessage(sendingStatus))
                .filter(str -> StringUtils.containsIgnoreCase(str, searchString))
                .collect(Collectors.toList()));

• OptionWrapper 用于需要将任何类型的值与其字串表示分离的情况下：

List<OptionWrapper> wrappers = Arrays.asList(
        new OptionWrapper("One", 1),
        new OptionWrapper("Two", 2),
        new OptionWrapper("Three", 3);
suggestionField.setSearchExecutor((searchString, searchParams) ->
        wrappers.stream()
                .filter(optionWrapper -> StringUtils.containsIgnoreCase(optionWrapper.getCaption(), searchString))
                .collect(Collectors.toList()));

searchString 参数可用于使用用户输入的字符串过滤候选值。也可以使用 escapeForLike() 方法来搜索包含特殊符号的值：

suggestionField.setSearchExecutor((searchString, searchParams) -> {
    searchString = QueryUtils.escapeForLike(searchString);
    return dataManager.loadList(LoadContext.create(Customer.class).setQuery(
            LoadContext.createQuery("select c from sample$Customer c where c.name like :name order by c.name escape '\\'")
                .setParameter("name", "%" + searchString + "%")));
});

• OptionsStyleProvider 允许为 suggestionField 的建议选项中的每一项指定单独的样式名。

suggestionField.setOptionsStyleProvider((field, item) -> {
    User user = (User) item;
    switch (user.getGroup().getName()) {
        case "Company":
            return "company";
        case "Premium":
            return "premium";
        default:
            return "company";
    }
});

suggestionField 的属性

align - asyncSearchDelayMs - caption - captionAsHtml - captionProperty - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datasource - description - descriptionAsHtml - editable - enable - box.expandRatio - height - icon - id - inputPrompt - minSearchStringLength - popupWidth - property - required - requiredMessage - responsive - rowspan - stylename - suggestionsLimit - tabIndex - visible - width

suggestionField 的元素

query

query 元素的属性

entityClass - escapeValueForLike - searchStringFormat - view

suggestionField 预定义样式

huge - large - small - tiny

API

addValueChangeListener - setContextHelpIconClickHandler - setOptionsStyleProvider