Работа с фильтрами в Admiral
Время прочтения — 9 минут
Содержание
При разработке админ-панелей часто возникает необходимость в удобной фильтрации данных в таблицах. Для этого используются фильтры – элементы интерфейса, которые позволяют быстро находить нужную информацию по заданным критериям. Грамотно настроенные фильтры упрощают работу с большим объёмом данных и делают взаимодействие с системой более эффективным.
Визуально оценить работу фильтров можно по ссылке: https://admiral.dev.family/quick-filters.
Типы фильтров
Admiral предоставляет два удобных способа фильтрации данных:
- Быстрые фильтры, размещённые непосредственно над таблицей;
- Расширенные фильтры, доступные по нажатию на кнопку.
Быстрые фильтры позволяют моментально применять наиболее часто используемые параметры без открытия дополнительного меню, а при необходимости более точной настройки доступны полноценные фильтры в сайдбаре.
Обычные фильтры в Admiral
Фильтры в Admiral позволяют пользователю вручную отфильтровать записи в таблице по нужным полям. Они доступны через кнопку «Filter» в верхней панели и отображаются в виде выезжающей панели сбоку (drawer), которая содержит форму с полями фильтрации. Это основной способ фильтрации, особенно когда количество параметров велико или требуется сложная логика.
Как работают фильтры
Фильтры настраиваются в секции filter внутри createCRUD. Вы передаёте набор полей в проп fields, и Admiral сам отрисует соответствующую форму. При изменении значений и применении фильтра таблица автоматически обновится с учётом новых параметров.
Пример подключения обычных фильтров:
filter: {
topToolbarButtonText: 'Filter',
fields: (
<>
<TextInput
name="search"
label="Search"
type="search"
placeholder="Введите имя или email"
/>
<SelectInput
name="group"
label="Группа"
placeholder="Выберите группу"
mode="multiple"
>
<SelectInput.Option value="admin">Администраторы</SelectInput.Option>
<SelectInput.Option value="project_manager">Проектные менеджеры</SelectInput.Option>
</SelectInput>
<SelectInput
name="role"
label="Роль"
placeholder="Выберите роль"
allowClear
>
<SelectInput.Option value="accountant">Бухгалтер</SelectInput.Option>
<SelectInput.Option value="recruiter">Рекрутер</SelectInput.Option>
</SelectInput>
<BooleanInput name="active" label="Активный пользователь" />
<DatePickerInput
name="registered_at"
label="Дата регистрации"
placeholder="Выберите дату"
allowClear
/>
</>
),
},
В этом примере фильтры будут доступны по нажатию на кнопку «Filter». Они появятся в сайдбаре и позволят пользователю фильтровать данные по имени, email, группам, ролям, активности и дате регистрации.
Быстрые фильтры в Admiral
quickFilters – это специальный ключ в объекте filter, который позволяет выбрать, какие фильтры будут отображаться непосредственно над таблицей, без открытия панели фильтров.
Он принимает массив строк, каждая из которых соответствует name одного из уже описанных полей фильтрации.
Пример:
filter: {
// поля фильтра описаны выше
quickFilters: ['search', 'group', 'role', 'active'],
}
В этом примере фильтры search, group, role и active будут отображены в виде инпутов сразу над таблицей. Остальные фильтры (если есть) останутся доступны только по нажатию на кнопку "Filter".
Такой подход позволяет выделить наиболее часто используемые параметры фильтрации и сделать интерфейс удобнее для пользователей.
Как Admiral отправляет фильтры на бэкенд
Admiral формирует HTTP-запросы к API с параметрами пагинации (page, perPage) и фильтрации, которые упаковываются в объект filter.
Пример реального запроса:
https://admiral.dev.family/api/users?page=1&perPage=10&filter[search]=User 10&filter[active]=true
Такой запрос отправляется, если мы хотим отобразить всех активных пользователей, у которых в имени есть “User 10” . В ответ на такой запрос, бэкэнд должен отфильтровать данные и вернуть новый список items для вывода в таблицу.
Получение options
Для работы некоторых fields в фильтрах, таких как SelectInput, необходим список options. Чтобы получить их, Admiral отправляет запросы на бэкэнд по пути {basePath}/filters. В ответ бэкэнд должен вернуть список опций.
На примере наших фильтров это будет выглядеть так:
{
"options": {
"group": [
{
"label": "Administration",
"value": "admin"
},
{
"label": "Project managers",
"value": "project_manager"
}
],
"role": [
{
"label": "Accountant",
"value": "accountant"
},
{
"label": "HR Officer",
"value": "recruiter"
}
]
}
}
