搜索选择器控件 - CUBA 框架开发者手册

3.5.2.1.39. 搜索选择器控件

SearchPickerField 组件用于根据输入的字符串搜索实体实例。用户可输入几个字符，然后按 Enter 键。如果找到了多个匹配项，则所有匹配项都将显示在下拉列表中。如果只有一个实例与搜索关键字匹配，则这个实例直接成为组件值。还可以通过单击 SearchPickerField 组件右侧的按钮来执行操作。

SearchPickerField 只能在使用遗留 API开发的界面中。当前 API 的类似功能通过SuggestionPickerField组件提供。

该组件的 XML 名称： searchPickerField

要使用 SearchPickerField 组件，需要创建 collectionDatasource 并指定一个包含相应搜索条件的查询。条件必须包含名为 custom$searchString 的参数。此参数将被填充为用户输入的搜索关键字。应将组件的 optionsDatasource 属性设置为带有搜索条件的数据源。例如：
```
<dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="colorsDs" class="com.company.sample.entity.Color" view="_local">
        <query>
            select c from sample$Color c
            where c.name like :(?i)custom$searchString
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <searchPickerField datasource="carDs" property="color" optionsDatasource="colorsDs"/>
</layout>
```
这时，组件会根据 Colour 实体的 name 属性中是否包含搜索关键字来查找 Colour 实体的实例。(?i) 前缀用于不区分大小写查找（请参阅不区分大小写查找）。选择的值将设置到 carDs 数据源中的 Car 实体的 colour 属性。

escapeValueForLike 属性设置为 true 时允许使用 like 子句搜索特殊符号： % 、 \ 和 _ 。要使用 escapeValueForLike = true，修改集合数据源的查询，为其添加转义符：
```
select c from ref$Colour c
where c.name like :(?i)custom$searchString or c.description like :(?i)custom$searchString escape '\'
```
escapeValueForLike 属性适用于除 HSQLDB 之外的所有数据库。

使用 minSearchStringLength 属性，设置要执行搜索应输入的最小字符数。

在界面控制器中，可以使用 SearchField.SearchNotifications 类给用户显示一些搜索提示，需要实现这个类的两个方法：

如果输入的字符数小于 minSearchStringLength 属性的值时调用的方法。
如果用户输入的字符没有返回任何结果时调用的方法。

下面是这两个方法的实现示例：

@Inject
private Notifications notifications;
@Inject
private SearchPickerField colorField;

@Subscribe
protected void onInit(InitEvent event) {
    colorField.setSearchNotifications(new SearchField.SearchNotifications() {
        @Override
        public void notFoundSuggestions(String filterString) {
            notifications.create()
                    .withCaption("No colors found for search string: " + filterString)
                    .withType(Notifications.NotificationType.TRAY)
                    .show();
        }

        @Override
        public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
            notifications.create()
                    .withCaption("Minimum length of search string is " + minSearchStringLength)
                    .withType(Notifications.NotificationType.TRAY)
                    .show();
        }
    });
}

SearchPickerField 实现了 LookupField 和 PickerField 接口。除了在 XML 中定义组件时添加的默认操作列表（对于 SearchPickerField，默认操作是 lookup 和 open 操作）不同，其它功能与 LookupField 和 PickerField 接口定义的功能相同。

searchPickerField 的属性: align - caption - captionAsHtml - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - css - datasource - description - descriptionAsHtml - editable - enable - escapeValueForLike - box.expandRatio - filterMode - height - icon - id - inputPrompt - metaClass - minSearchStringLength - newOptionAllowed - newOptionHandler - nullName - optionsDatasource - property - required - requiredMessage - stylename - tabIndex - visible - width
searchPickerField 的元素: actions - validator
searchPickerField 的预定义样式: huge - large
API: addValueChangeListener - setContextHelpIconClickHandler - setOptionCaptionProvider - setOptionImageProvider - setPopupWidth