Фильтр main.ui.filter

main.ui.filter выводит строку поиска и набор полей фильтрации. Используйте компонент на страницах со списками, отчетами и таблицами, где пользователь должен выбрать условия, сохранить пресет и применить фильтр к данным.

Компонент отвечает только за интерфейс фильтра и сохранение пользовательских настроек. Серверный код страницы получает выбранные значения через Bitrix\Main\UI\Filter\Options или через слой Bitrix\Main\Filter\Filter, а затем сам применяет условия к ORM-запросу, массиву данных или другому источнику.

Если фильтр работает вместе с таблицей main.ui.grid, передайте один и тот же идентификатор в FILTER_ID и GRID_ID. Тогда фильтр сможет обновлять связанный грид после применения условий.

Вывести фильтр

Передайте в компонент идентификатор фильтра и массив полей. Минимальное поле содержит id и name; если type не указан, поле работает как строковое.

<?php

$filterId = 'orders_filter';

$APPLICATION->IncludeComponent(
    'bitrix:main.ui.filter',
    '',
    [
        'FILTER_ID' => $filterId,
        'FILTER' => [
            [
                'id' => 'FIND',
                'name' => 'Поиск',
            ],
            [
                'id' => 'STATUS',
                'name' => 'Статус',
                'type' => 'list',
                'items' => [
                    '' => 'Любой',
                    'new' => 'Новый',
                    'done' => 'Выполнен',
                ],
            ],
            [
                'id' => 'DATE_CREATE',
                'name' => 'Дата создания',
                'type' => 'date',
            ],
        ],
        'ENABLE_LABEL' => true,
    ]
);

Основные параметры вызова:

Параметр Тип Описание
FILTER_ID string Обязательный идентификатор фильтра. Используйте уникальное значение для каждой страницы или логического списка, потому что по нему сохраняются пользовательские настройки
GRID_ID string Идентификатор грида. Передавайте его, если фильтр должен обновлять таблицу main.ui.grid
FILTER array Обязательный массив полей фильтра. Компонент преобразует поля в данные для интерфейса
FILTER_PRESETS array Массив пресетов фильтра
ENABLE_LABEL bool true включает подписи полей

Настроить поведение

Компонент поддерживает настройки интерфейса, которые влияют на внешний вид и сценарий работы.

Параметр Тип Значение Описание
DISABLE_SEARCH bool true Отключает строку поиска
ENABLE_LIVE_SEARCH bool true Применяет фильтр по мере ввода
ENABLE_FIELDS_SEARCH string 'Y' Включает поиск по названиям полей в настройках фильтра
ENABLE_LABEL bool true Показывает подписи полей
RESET_TO_DEFAULT_MODE bool true Возвращает фильтр к начальному состоянию при сбросе
VALUE_REQUIRED_MODE bool true Включает режим, в котором фильтр может требовать значение
COMPACT_STATE bool true Включает компактное состояние фильтра
HEADERS_SECTIONS array Непустой массив Группирует поля по секциям. Поле привязывается к секции через sectionId
RENDER_FILTER_INTO_VIEW string Идентификатор области Встраивает фильтр в указанную область
RENDER_FILTER_INTO_VIEW_SORT int Число сортировки Задает сортировку фильтра внутри области
MESSAGES array Массив текстов Заменяет пользовательские тексты интерфейса. Компонент использует только ключи, которые начинаются с MAIN_UI_FILTER__
LIMITS array Массив с TITLE, DESCRIPTION и BUTTONS Показывает ограничение. Если задан заголовок ограничения, компонент отключает строку поиска
RESTRICTED_FIELDS array Непустой массив Задает список ограниченных полей

Получить значения

После отправки формы получите значения фильтра на сервере и примените их к выборке.

<?php

use Bitrix\Main\UI\Filter\Options;

$filterId = 'orders_filter';
$filterFields = [
    ['id' => 'FIND', 'name' => 'Поиск'],
    ['id' => 'STATUS', 'name' => 'Статус', 'type' => 'list'],
    ['id' => 'DATE_CREATE', 'name' => 'Дата создания', 'type' => 'date'],
];

$filterOptions = new Options($filterId);
$filter = $filterOptions->getFilter($filterFields);

if (!empty($filter['STATUS']))
{
    $ormFilter['=STATUS'] = $filter['STATUS'];
}

if (!empty($filter['DATE_CREATE_from']))
{
    $ormFilter['>=DATE_CREATE'] = $filter['DATE_CREATE_from'];
}

if (!empty($filter['DATE_CREATE_to']))
{
    $ormFilter['<=DATE_CREATE'] = $filter['DATE_CREATE_to'];
}

if (!empty($filter['FIND']))
{
    $ormFilter['%TITLE'] = $filter['FIND'];
}

Метод Options::getFilter() возвращает значения, которые пользователь выбрал в интерфейсе. Для полей с диапазоном компонент добавляет служебные ключи, например _from, _to, _datesel и _numsel. Используйте только те ключи, которые нужны вашему запросу.

Метод getValue() класса Bitrix\Main\Filter\Filter удаляет служебные поля интерфейса и вызывает подготовку значений у провайдера. Используйте его, если страница уже построена на серверном слое Bitrix\Main\Filter\Filter. Для объекта фильтра нужен провайдер данных, поэтому не создавайте его только ради чтения значений из обычного компонента.

Что возвращает фильтр:

Тип поля Ключи в результате Когда использовать
string ID_поля Для точного значения или поиска по строке
textarea ID_поля Для многострочного значения
list ID_поля Для выбранного значения списка. При множественном выборе значение обрабатывайте как набор выбранных вариантов
number ID_поля, ID_поля_from, ID_поля_to, ID_поля_numsel Для точного числа или диапазона
date ID_поля_from, ID_поля_to, ID_поля_datesel Для выбранного периода или ручного диапазона дат
custom_date ID_поля_days, ID_поля_months, ID_поля_years Для произвольного выбора дней, месяцев и лет
entity_selector ID_поля Для идентификатора выбранного объекта. Если включен addEntityIdToResult, значение содержит тип объекта и идентификатор элемента

Связать с гридом

Для связки с таблицей main.ui.grid используйте один идентификатор для фильтра и таблицы. Фильтр только возвращает выбранные значения; серверный код сам преобразует их в условия выборки и строки грида.

В примере $orders — массив записей. В рабочем коде замените его выборкой из своего источника данных с учетом $ormFilter.

<?php

use Bitrix\Main\UI\Filter\Options;

$gridId = 'orders_grid';
$filterFields = [
    ['id' => 'FIND', 'name' => 'Поиск'],
    ['id' => 'STATUS', 'name' => 'Статус', 'type' => 'list'],
];

$filterOptions = new Options($gridId);
$filter = $filterOptions->getFilter($filterFields);
$ormFilter = [];

if (!empty($filter['STATUS']))
{
    $ormFilter['=STATUS'] = $filter['STATUS'];
}

if (!empty($filter['FIND']))
{
    $ormFilter['%TITLE'] = $filter['FIND'];
}

$orders = [
    [
        'ID' => 1,
        'TITLE' => 'Заказ на доставку',
        'STATUS' => 'Новый',
    ],
];

$rows = [];
foreach ($orders as $order)
{
    $rows[] = [
        'id' => $order['ID'],
        'data' => [
            'ID' => $order['ID'],
            'TITLE' => $order['TITLE'],
            'STATUS' => $order['STATUS'],
        ],
    ];
}

$APPLICATION->IncludeComponent(
    'bitrix:main.ui.filter',
    '',
    [
        'FILTER_ID' => $gridId,
        'GRID_ID' => $gridId,
        'FILTER' => $filterFields,
    ]
);

$APPLICATION->IncludeComponent(
    'bitrix:main.ui.grid',
    '',
    [
        'GRID_ID' => $gridId,
        'COLUMNS' => [
            ['id' => 'ID', 'name' => 'ID', 'default' => true],
            ['id' => 'TITLE', 'name' => 'Название', 'default' => true],
            ['id' => 'STATUS', 'name' => 'Статус', 'default' => true],
        ],
        'ROWS' => $rows,
    ]
);

Описать поля

Основные ключи поля:

Ключ Тип Описание
id string Обязательный идентификатор поля. По нему значение возвращается в массиве фильтра
name string Обязательная подпись поля в интерфейсе
type string Тип поля. Если ключ не указан, используется строковое поле. Передавайте значение в нижнем регистре
default bool true показывает поле в фильтре по умолчанию
items array Варианты для списков. Для поля list передайте массив, где ключ станет значением фильтра, а значение массива — подписью в интерфейсе
params array Дополнительные параметры поля. Для списков в нем задают множественный выбор
exclude array Список подтипов даты, которые нужно убрать из выбора
sectionId string Идентификатор секции, если поля сгруппированы через HEADERS_SECTIONS

Строка и текст

Тип string подходит для короткого значения или поиска по части текста.

<?php

$field = [
    'id' => 'TITLE',
    'name' => 'Название',
    'type' => 'string',
    'default' => true,
];

Тип textarea используйте для многострочного значения. Оба типа возвращают значение по ключу поля.

Список

Тип list показывает выпадающий список. В items передайте массив вариантов, где ключ станет значением фильтра, а значение массива — подписью в интерфейсе.

<?php

$field = [
    'id' => 'STATUS',
    'name' => 'Статус',
    'type' => 'list',
    'items' => [
        '' => 'Любой',
        'new' => 'Новый',
        'done' => 'Выполнен',
    ],
];

Для множественного выбора передайте ключ multiple со значением 'Y' в массиве params.

<?php

$field = [
    'id' => 'STATUS',
    'name' => 'Статус',
    'type' => 'list',
    'params' => [
        'multiple' => 'Y',
    ],
    'items' => [
        'new' => 'Новый',
        'progress' => 'В работе',
        'done' => 'Выполнен',
    ],
];

Число

Тип number поддерживает точное значение и диапазон. При выборе диапазона фильтр возвращает ключи с постфиксами _from и _to.

<?php

$field = [
    'id' => 'PRICE',
    'name' => 'Сумма',
    'type' => 'number',
];

Дата

Тип date показывает готовые варианты периода и ручной ввод диапазона. Подтипы даты определены в Bitrix\Main\UI\Filter\DateType.

<?php

use Bitrix\Main\UI\Filter\DateType;

$field = [
    'id' => 'DATE_CREATE',
    'name' => 'Дата создания',
    'type' => 'date',
    'exclude' => [
        DateType::LAST_60_DAYS,
        DateType::LAST_90_DAYS,
    ],
];

Если нужно выбирать время вместе с датой, передайте time.

<?php

$field = [
    'id' => 'DATE_CREATE',
    'name' => 'Дата создания',
    'type' => 'date',
    'time' => true,
];

Тип custom_date используется для произвольного выбора дней, месяцев и лет. Компонент возвращает значения с постфиксами _days, _months и _years.

Выбор объектов

Тип entity_selector подключает интерфейс выбора объектов через ui.entity-selector. Передайте настройки диалога в params.dialogOptions.

<?php

$field = [
    'id' => 'RESPONSIBLE_ID',
    'name' => 'Ответственный',
    'type' => 'entity_selector',
    'params' => [
        'multiple' => 'Y',
        'dialogOptions' => [
            'context' => 'orders_filter',
            'entities' => [
                [
                    'id' => 'user',
                ],
            ],
        ],
    ],
];

Если в одном поле доступны объекты разных типов, передайте ключ addEntityIdToResult со значением 'Y' в массиве params. Тогда значение сохранит идентификатор типа объекта и идентификатор выбранного элемента.

Без этого параметра фильтр возвращает идентификатор выбранного элемента.

Тип dest_selector подходит для выбора пользователей, подразделений и других адресатов через прежний селектор. Используйте его в существующих интерфейсах, где уже настроены параметры этого селектора.

Используйте тип custom_entity, если поле обрабатывает выбор своим JavaScript-кодом и само подставляет подпись выбранного значения. Если новый интерфейс может работать через ui.entity-selector, выбирайте entity_selector.

Добавить пресеты

Пресет задает сохраненный набор значений фильтра. Передайте массив FILTER_PRESETS, где ключ — идентификатор пресета.

<?php

$presets = [
    'active_orders' => [
        'name' => 'Активные заказы',
        'default' => true,
        'fields' => [
            'STATUS' => 'new',
            'DATE_CREATE_datesel' => 'CURRENT_MONTH',
        ],
    ],
];

Основные ключи пресета:

Ключ Тип Описание
name string Обязательное название в меню пресетов
default bool true делает пресет выбранным по умолчанию
fields array Обязательные значения полей. Ключи должны совпадать с id полей или служебными ключами диапазонов
disallow_for_all bool Запрещает применять пресет для всех пользователей, если сценарий поддерживает общие пресеты

Пользовательские настройки фильтра сохраняются по FILTER_ID. Если изменить идентификатор, ранее сохраненные пресеты и выбранные поля не применятся к новому фильтру.

Предыдущая
Всплывающие окна и меню main.popup
Следующая
Таблица main.ui.grid