3.5.2.1.39. 搜索选择器控件

API 文档

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

该组件的 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