Фильтр 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. Если изменить идентификатор, ранее сохраненные пресеты и выбранные поля не применятся к новому фильтру.