3.5.2.1.39. 搜索选择器控件

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

gui searchPickerFieldOverlap

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 实现了 LookupFieldPickerField 接口。除了在 XML 中定义组件时添加的默认操作列表(对于 SearchPickerField,默认操作是 lookupopen 操作)不同,其它功能与 LookupFieldPickerField 接口定义的功能相同。