SuggestionPickerField - Платформа CUBA. Руководство по разработке приложений

3.5.2.1.43. SuggestionPickerField

Компонент SuggestionPickerField предназначен для поиска экземпляров сущности по строке, вводимой пользователем. Он отличается от SearchPickerField тем, что обновляет список опций при каждом вводе символа пользователем без необходимости нажимать Enter. Список опций загружается асинхронно в соответствии с логикой, задаваемой разработчиком на стороне сервера.

SuggestionPickerField является также PickerField и может содержать действия, отображаемые кнопками справа.

XML-имя компонента: suggestionPickerField.

Компонент реализован для блока Web Client.

SuggestionPickerField используется для выбора значений ссылочных атрибутов, поэтому для компонента обычно указываются атрибуты dataContainer и property:

<data>
    <instance id="orderDc"
              class="com.company.sales.entity.Order"
              view="order-with-customer">
        <loader id="orderDl"/>
    </instance>
</data>
<layout>
<suggestionPickerField id="suggestionPickerField"
                       captionProperty="name"
                       dataContainer="orderDc"
                       property="customer"/>
</layout>

Атрибуты suggestionPickerField:

asyncSearchDelayMs - устанавливает задержку между последним нажатием клавиши и асинхронным поиском.

metaClass - указывает ссылку на интерфейс метаданных компонента в случае, если компонент используется без непосредственной привязки к данным, то есть без указания dataContainer и property.

minSearchStringLength - устанавливает минимальную длину строки для начала поиска.

popupWidth - устанавливает ширину всплывающей подсказки.

Возможные значения:
- auto - ширина поля подсказки равна максимальной ширине текста подсказки,
- parent - ширина поля подсказки равна ширине основного компонента,
- абсолютное (например, "170px") или относительное (например, "50%") значение.

suggestionsLimit - устанавливает ограничение количества выводимых подсказок.

Внешний вид поля suggestionPickerField и его всплывающей подсказки со списком опций можно настроить с помощью атрибута stylename. Значение stylename для подсказки должно иметь то же имя, что и стиль основного компонента: к примеру, если компонент имеет стиль "my-awesome-stylename", для его подсказки можно создать стиль "c-suggestionfield-popup my-awesome-stylename".

Элементы suggestionPickerField:

actions - необязательный элемент для описания действий, связанных с компонентом. Кроме описания произвольных действий, поддерживаются следующие стандартные действия PickerField: picker_lookup, picker_clear, picker_open.

Простой пример использования SuggestionPickerField

Как правило, для компонента достаточно установить SearchExecutor. SearchExecutor - это функциональный интерфейс, содержащий один метод: List<E extends Entity> search(String searchString, Map<String, Object> searchParams):

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

Метод search() выполняется в фоновом потоке, поэтому он не может обращаться к визуальным компонентам или источникам данных, связанным с визуальными компонентами. Можно использовать DataManager или напрямую вызывать сервисы среднего слоя, или обрабатывать и возвращать данные, предварительно загруженные в экран.

Параметр searchString может быть использован для фильтрации кандидатов по строке, введенной пользователем. Чтобы искать по значениям, содержащим специальные символы, используйте метод escapeForLike():

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

Использование ParametrizedSearchExecutor

В примерах выше параметр searchParams является пустым. Для поиска с параметрами используется ParametrizedSearchExecutor:

suggestionPickerField.setSearchExecutor(new SuggestionField.ParametrizedSearchExecutor<Customer>(){
    @Override
    public Map<String, Object> getParams() {
        return ParamsMap.of(...);
    }

    @Override
    public List<Customer> search(String searchString, Map<String, Object> searchParams) {
        return executeSearch(searchString, searchParams);
    }
});

Использование EnterActionHandler и ArrowDownActionHandler

Компонент также может быть использован с обработчиками событий EnterActionHandler и ArrowDownActionHandler. Эти листнеры срабатывают, когда пользователь нажимает клавиши Enter или Arrow Down при скрытом всплывающем окне для подсказок. Они также представляют собой функциональные интерфейсы с единственным методом с одним параметром - currentSearchString. Вы можете настроить и свои обработчики событий и использовать метод showSuggestions() интерфейса SuggestionField, который принимает список сущностей, для отображения подсказок:

suggestionPickerField.setArrowDownActionHandler(currentSearchString -> {
    List<Customer> suggestions = findSuggestions();
    suggestionPickerField.showSuggestions(suggestions);
});

suggestionPickerField.setEnterActionHandler(currentSearchString -> {
    List<Customer> suggestions = getDefaultSuggestions();
    suggestionPickerField.showSuggestions(suggestions);
});

Атрибуты 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