3.5.2.1.39. 搜索选择器控件

在线示例

API 文档

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

gui searchPickerFieldOverlap

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

该组件的 XML 名称: searchPickerField

  • 要使用 SearchPickerField 组件,需要创建 collectionDatasource 并指定一个包含相应搜索条件的查询。条件必须包含名为 custom$searchString 的参数。此参数将被填充为用户输入的搜索关键字。应将组件的 optionsDatasource 属性设置为带有搜索条件的数据源。例如:

    1. <dsContext>
    2. <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    3. <collectionDatasource id="colorsDs" class="com.company.sample.entity.Color" view="_local">
    4. <query>
    5. select c from sample$Color c
    6. where c.name like :(?i)custom$searchString
    7. </query>
    8. </collectionDatasource>
    9. </dsContext>
    10. <layout>
    11. <searchPickerField datasource="carDs" property="color" optionsDatasource="colorsDs"/>
    12. </layout>

    这时,组件会根据 Colour 实体的 name 属性中是否包含搜索关键字来查找 Colour 实体的实例。(?i) 前缀用于不区分大小写查找(请参阅不区分大小写查找)。选择的值将设置到 carDs 数据源中的 Car 实体的 colour 属性。

    escapeValueForLike 属性设置为 true 时允许使用 like 子句搜索特殊符号: %\_ 。要使用 escapeValueForLike = true,修改集合数据源的查询,为其添加转义符:

    1. select c from ref$Colour c
    2. where c.name like :(?i)custom$searchString or c.description like :(?i)custom$searchString escape '\'

    escapeValueForLike 属性适用于除 HSQLDB 之外的所有数据库。

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

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

    • 如果输入的字符数小于 minSearchStringLength 属性的值时调用的方法。

    • 如果用户输入的字符没有返回任何结果时调用的方法。

  1. 下面是这两个方法的实现示例:
  2. ```
  3. @Inject
  4. private Notifications notifications;
  5. @Inject
  6. private SearchPickerField colorField;
  7. @Subscribe
  8. protected void onInit(InitEvent event) {
  9. colorField.setSearchNotifications(new SearchField.SearchNotifications() {
  10. @Override
  11. public void notFoundSuggestions(String filterString) {
  12. notifications.create()
  13. .withCaption("No colors found for search string: " + filterString)
  14. .withType(Notifications.NotificationType.TRAY)
  15. .show();
  16. }
  17. @Override
  18. public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
  19. notifications.create()
  20. .withCaption("Minimum length of search string is " + minSearchStringLength)
  21. .withType(Notifications.NotificationType.TRAY)
  22. .show();
  23. }
  24. });
  25. }
  26. ```
  • SearchPickerField 实现了 LookupFieldPickerField 接口。除了在 XML 中定义组件时添加的默认操作列表(对于 SearchPickerField,默认操作是 lookupopen 操作)不同,其它功能与 LookupFieldPickerField 接口定义的功能相同。

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