3.5.2.1.44. 建议选择器字段

在线示例

API 文档

SuggestionPickerField 组件用于根据用户输入的字符串搜索实体实例。它与 SearchPickerField 的不同之处在于它在用户输入每个字符时自动刷新选项列表,不需要按 Enter 键。 选项列表是根据应用程序开发人员定义的逻辑在后端加载。

SuggestionPickerField 也是一种PickerField,在右侧可以有操作按钮。

gui suggestionPickerField 1

该组件的 XML 名称: suggestionPickerField

SuggestionPickerField 用于选择并引用实体属性,因此通常设置它的 dataContainerproperty 属性:

  1. <data>
  2. <instance id="orderDc"
  3. class="com.company.sales.entity.Order"
  4. view="order-with-customer">
  5. <loader id="orderDl"/>
  6. </instance>
  7. </data>
  8. <layout>
  9. <suggestionPickerField id="suggestionPickerField"
  10. captionProperty="name"
  11. dataContainer="orderDc"
  12. property="customer"/>
  13. </layout>

suggestionPickerField 的属性:

  • asyncSearchDelayMs - 设置最后一次按键到执行异步搜索之前需要延迟的时间。
  • metaClass - 设置链接到组件的 MetaClass ,如果在不绑定数据组件的情况下使用该组件,比如,没有设置 dataContainerproperty
  • minSearchStringLength - 设置执行建议搜索需要的最小字符串长度。
  • popupWidth - 设置建议选项弹出框的宽度。

    可选项:

    • auto - 弹出框的宽度等于建议选项的最大长度,即自动宽度,

    • parent - 弹出框的宽度等于主组件的宽度,

    • 绝对(比如 "170px")或相对(比如 "50%")值。

  • suggestionsLimit - 设置显示的建议选项的最大数量。

suggestionPickerField 和其对应的弹出框的外观可以使用stylename属性进行定制。弹出框应该与主组件拥有相同的样式名:比如,如果主组件有自定义的样式名 “my-awesome-stylename”,对应的弹出框应该有样式名 “c-suggestionfield-popup my-awesome-stylename”

suggestionPickerField 的元素:

  • actions - 可选元素,用于描述与组件相关的各种操作,除了自定义的操作,suggestionPickerField 支持下列标准 PickerField 操作picker_lookuppicker_clearpicker_open

SuggestionPickerField 的基本用法

一般情况下,给组件设置 SearchExecutor 就可以了。SearchExecutor 是一个包含单个方法的功能接口:List<E extends Entity> search(String searchString, Map<String, Object> searchParams):

  1. suggestionPickerField.setSearchExecutor((searchString, searchParams) -> {
  2. return Arrays.asList(entity1, entity2, ...);
  3. });

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

searchString 参数可用于使用用户输入的字符串过滤候选值。也可以使用 escapeForLike() 方法来搜索包含特殊符号的值:

  1. suggestionPickerField.setSearchExecutor((searchString, searchParams) -> {
  2. searchString = QueryUtils.escapeForLike(searchString);
  3. return dataManager.loadList(LoadContext.create(Customer.class).setQuery(
  4. LoadContext.createQuery("select c from sample_Customer c where c.name like :name order by c.name escape '\\'")
  5. .setParameter("name", "%" + searchString + "%")));
  6. });

ParametrizedSearchExecutor 的用法

在前面的例子中,searchParams 是一个空的字典。要定义参数,应该使用 ParametrizedSearchExecutor

  1. suggestionPickerField.setSearchExecutor(new SuggestionField.ParametrizedSearchExecutor<Customer>(){
  2. @Override
  3. public Map<String, Object> getParams() {
  4. return ParamsMap.of(...);
  5. }
  6. @Override
  7. public List<Customer> search(String searchString, Map<String, Object> searchParams) {
  8. return executeSearch(searchString, searchParams);
  9. }
  10. });

EnterActionHandler 和 ArrowDownActionHandler 的用法

使用该组件的另一种方法是设置 EnterActionHandlerArrowDownActionHandler。在建议弹出框隐藏的情况下,户按下 EnterArrow Down 键时会触发这些监听器。它们也是具有单一方法和单个参数 - currentSearchString 的功能接口。可以设置自己的操作处理器并使用 SuggestionField.showSuggestions() 方法,该方法接收一个实体列表参数用于显示建议选项。

  1. suggestionPickerField.setArrowDownActionHandler(currentSearchString -> {
  2. List<Customer> suggestions = findSuggestions();
  3. suggestionPickerField.showSuggestions(suggestions);
  4. });
  5. suggestionPickerField.setEnterActionHandler(currentSearchString -> {
  6. List<Customer> suggestions = getDefaultSuggestions();
  7. suggestionPickerField.showSuggestions(suggestions);
  8. });

suggestionPickerField 的属性

align - asyncSearchDelayMs - caption - captionAsHtml - captionProperty - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datasource - description - descriptionAsHtml - editable - enable - box.expandRatio - height - icon - id - inputPrompt - metaClass - minSearchStringLength - popupWidth - property - required - requiredMessage - responsive - rowspan - stylename - suggestionsLimit - tabIndex - visible - width

suggestionPickerField 的元素

actions - query - validator

suggestionPickerField 的预定义样式

huge - large - small - tiny

API

addValueChangeListener - setContextHelpIconClickHandler - setOptionCaptionProvider - setOptionIconProvider - setOptionsStyleProvider