建议字段 - CUBA 框架开发者手册

3.5.2.1.42. 建议字段

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()));

search() 方法在后台线程中执行，因此它无法访问可视化组件或可视化组件使用的数据源。可直接调用 DataManager 或中间件服务；或处理并返回预先加载到界面的数据。

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