Панель инструментов ui.toolbar

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

Панелью управляет фасад Bitrix\UI\Toolbar\Facade\Toolbar из модуля ui, а разметку выводит компонент bitrix:ui.toolbar.

Используйте панель, когда странице нужны заголовок и действия в стандартном оформлении интерфейса Bitrix Framework. Кнопки для панели создают PHP-классы Bitrix\UI\Buttons.

Как работает панельКак работает панель

Сначала код страницы наполняет панель через фасад, затем компонент выводит готовую разметку.

Все панели страницы хранит менеджер Bitrix\UI\Toolbar\Manager. Панель по умолчанию имеет идентификатор default-toolbar — его же возвращает константа Toolbar::DEFAULT_ID. Фасад передает статические вызовы этой панели и создает ее при первом обращении.

Компонент откладывает отрисовку до конца сборки страницы. Поэтому фасад можно вызывать в любом месте кода после подключения пролога: в файле страницы, в классе или шаблоне компонента, который подключен ниже панели. Порядок вызовов влияет только на порядок кнопок внутри одной группы.

Страница задает заголовок и добавляет кнопку в правую группу.

<?php

use Bitrix\Main\Loader;
use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Buttons\Color;
use Bitrix\UI\Toolbar\Facade\Toolbar;

if (!Loader::includeModule('ui'))
{
    return;
}

Toolbar::setTitle('Заказы');

Toolbar::addButton(
    new Button([
        'text' => 'Создать заказ',
        'color' => Color::PRIMARY,
        'link' => '/orders/edit/0/',
    ])
);

Панель размещает элементы в фиксированном порядке слева направо: блок заголовка, кнопки после заголовка, фильтр вместе со своими кнопками, правые кнопки, произвольный HTML справа.

Настройки панели действуют в рамках одного запроса. Панель не хранит состояние между страницами, поэтому заголовок, кнопки и фильтр задавайте при каждой загрузке.

Настроить заголовокНастроить заголовок

Без явных настроек панель показывает заголовок страницы — тот, что задает метод $APPLICATION->setTitle().

Метод setTitle() фасада переопределяет заголовок только в панели. Заголовок вкладки браузера остается прежним.

Шаблон панели удаляет из заголовка HTML-теги, поэтому передавайте обычный текст.

Панель получает заголовок с ограничением ширины и переносом на несколько строк.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::setTitle('Заказы за квартал');
Toolbar::setTitleMinWidth(200);
Toolbar::setTitleMaxWidth(600);
Toolbar::enableMultiLineTitle();

Разрешить редактирование заголовкаРазрешить редактирование заголовка

Метод addEditableTitle() добавляет к заголовку кнопку редактирования. По клику заголовок превращается в поле ввода с кнопками сохранения и отмены.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::setTitle($report->getName());
Toolbar::addEditableTitle('Новый отчет');

Необязательный аргумент метода передает редактору заголовок по умолчанию.

Метод getDefaultEditableTitle() возвращает этот заголовок или null, если редактирование не включено.

Метод hasEditableTitle() возвращает true, когда редактирование заголовка включено.

Добавить кнопкиДобавить кнопки

Метод addButton() принимает объект Bitrix\UI\Buttons\Button или массив его параметров. Вторым аргументом метод принимает место в панели.

use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Buttons\Color;
use Bitrix\UI\Buttons\JsCode;
use Bitrix\UI\Toolbar\ButtonLocation;
use Bitrix\UI\Toolbar\Facade\Toolbar;

// объект кнопки
Toolbar::addButton(
    new Button([
        'text' => 'Создать',
        'color' => Color::PRIMARY,
        'onclick' => new JsCode('openCreateSlider();'),
    ]),
    ButtonLocation::AFTER_TITLE
);

// массив параметров, панель сама создаст объект Button
Toolbar::addButton([
    'text' => 'Настройки',
    'color' => Color::LIGHT_BORDER,
    'link' => '/orders/settings/',
]);

Места кнопок задают константы класса Bitrix\UI\Toolbar\ButtonLocation.

Задать иконку для свернутой кнопкиЗадать иконку для свернутой кнопки

Панель сравнивает свою ширину с шириной содержимого. Если кнопки не помещаются, панель сворачивает их до иконок, начиная с самой правой, и разворачивает обратно, когда окно становится шире.

Свернуть можно только кнопку с иконкой. Для кнопки без иконки задайте иконку свернутого состояния ключом toolbar-collapsed-icon в наборе dataset — панель подставит ее вместо текста.

use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Buttons\Icon;
use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::addButton(
    new Button([
        'text' => 'Импорт',
        'link' => '/orders/import/',
        'dataset' => [
            'toolbar-collapsed-icon' => Icon::DOWNLOAD,
        ],
    ])
);

Кнопке с цветом Color::PRIMARY ключ задавать не нужно: в свернутом состоянии панель сама ставит ей иконку добавления.

Изменить состав кнопокИзменить состав кнопок

Кнопки страницы часто добавляет чужой код: компонент списка, шаблон или обработчик события. Для таких случаев панель дает два метода.

Метод deleteButtons() принимает функцию-фильтр. Панель вызывает ее для каждой кнопки и передает саму кнопку и место, в котором она стоит. Если функция вернет true, панель удалит кнопку.

use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Toolbar\ButtonLocation;
use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::deleteButtons(
    static function (Button $button, string $location): bool
    {
        return $location === ButtonLocation::RIGHT && $button->getText() === 'Настройки';
    }
);

Метод shuffleButtons() меняет порядок кнопок. Он принимает функцию и место в панели. Функция получает массив кнопок этого места и должна вернуть новый массив, иначе метод выбросит ArgumentTypeException. Метод работает только для мест RIGHT и AFTER_FILTER.

use Bitrix\UI\Toolbar\ButtonLocation;
use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::shuffleButtons(
    static fn(array $buttons): array => array_reverse($buttons),
    ButtonLocation::RIGHT
);

Метод getButtons() возвращает все кнопки панели одним массивом в том же порядке, в каком панель их выводит.

Оформление кнопок в air-дизайнеОформление кнопок в air-дизайне

Если в шаблоне сайта определена константа AIR_SITE_TEMPLATE, панель сама переводит добавленные кнопки в air-оформление: включает air-стиль, отключает верхний регистр текста и подбирает стиль по переданному цвету.

Правым кнопкам без явного размера панель ставит Size::SMALL. Кнопке после заголовка со стилем AirButtonStyle::FILLED_SUCCESS без иконки — иконку добавления.

Метод hasAirDesign() возвращает true, если air-дизайн включен. Проверяйте режим, когда оформление кнопки зависит от шаблона сайта.

Добавить фильтрДобавить фильтр

Метод addFilter() подключает компонент bitrix:main.ui.filter с переданными параметрами и сохраняет его HTML в панели.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::addFilter([
    'FILTER_ID' => 'orders_filter',
    'GRID_ID' => 'orders_grid',
    'FILTER' => [
        ['id' => 'FIND', 'name' => 'Поиск'],
        ['id' => 'STATUS', 'name' => 'Статус', 'type' => 'list'],
    ],
    'ENABLE_LABEL' => true,
]);

Поля фильтра, пресеты и чтение выбранных значений описывает статья про фильтр main.ui.filter.

Панель выводит только один фильтр. Повторный вызов addFilter() заменяет предыдущую разметку.

В air-дизайне панель подключает фильтр с темой Theme::AIR и отключает автофокус в его настройках.

Метод setFilter() принимает готовый HTML фильтра. Используйте его, если фильтр уже отрисовал другой код.

Метод getFilter() возвращает текущую разметку фильтра или null, если фильтра в панели нет.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::setFilter($filterHtml);

Чтобы поставить кнопку рядом с фильтром, передайте место ButtonLocation::AFTER_FILTER.

Добавить свой HTMLДобавить свой HTML

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

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

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::addUnderTitleHtml('<span class="orders-subtitle">Обновлено ' . htmlspecialcharsbx($updateTime) . '</span>');
Toolbar::addRightCustomHtml($counterHtml, ['align' => 'right']);

Панель выводит переданную строку как есть. Экранируйте пользовательские данные, чтобы не получить XSS-уязвимость.

Каждый метод хранит одно значение: повторный вызов заменяет предыдущую разметку. Если в одном месте нужно несколько элементов, соберите их в одну строку.

Методы чтения возвращают null, если разметка не задана. Исключения — методы getRightCustomHtml() с пустой строкой и getRightCustomHtmlOptions() с пустым массивом.

Настроить стандартные элементыНастроить стандартные элементы

Кроме заголовка и кнопок панель выводит три собственных элемента: звезду избранного, кнопку копирования ссылки и кнопку фокус-режима.

Все три элемента находятся в блоке заголовка. Метод hideTitle() скрывает их вместе с заголовком.

Звезда избранногоЗвезда избранного

Звезда добавляет текущую страницу в левое меню Битрикс24. Панель показывает ее по умолчанию, но только когда заголовок не пустой.

Звездой управляют три метода:

• addFavoriteStar() — включает звезду избранного.

• deleteFavoriteStar() — убирает звезду со страницы.

• hasFavoriteStar() — возвращает true, если звезда включена.

Адрес страницы и название пункта меню задают параметры компонента или свойства страницы FavoriteUrl и FavoriteTitleTemplate.

Кнопка копирования ссылкиКнопка копирования ссылки

Метод setCopyLinkButton() добавляет рядом с заголовком кнопку, которая копирует ссылку на страницу в буфер обмена и показывает всплывающее подтверждение.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::setCopyLinkButton([
    'link' => 'https://portal.example.com/orders/detail/42/',
    'title' => 'Скопировать ссылку на заказ',
    'successfulCopyMessage' => 'Ссылка скопирована',
]);

Все ключи массива необязательны.

Метод setCopyLinkButton() без аргументов добавляет кнопку с текстами по умолчанию.

Чтобы убрать кнопку, передайте в метод null.

Метод getCopyLinkButton() возвращает текущие параметры кнопки или null, если кнопки в панели нет.

Кнопка фокус-режимаКнопка фокус-режима

Кнопка переключает шаблон сайта в полноэкранный режим и обратно.

Панель показывает кнопку, если в модуле ui включена опция toolbar_fullscreen_button. По умолчанию опция выключена, поэтому кнопки на странице нет.

Метод addFullscreenButton() показывает кнопку на текущей странице независимо от опции.

Метод removeFullscreenButton() убирает кнопку с текущей страницы, даже когда опция включена.

Метод hasFullscreenButton() возвращает итоговое состояние. Сначала он проверяет вызовы на странице, а если их не было — значение опции модуля.

Страница включает кнопку одним вызовом фасада.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::addFullscreenButton();

Отключить панельОтключить панель

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

• disable() — выключает панель. Компонент не выведет разметку, даже если шаблон сайта его подключает.

• enable() — включает панель обратно.

• isEnabled() — возвращает true, если панель включена.

Выключайте панель на страницах с собственной шапкой.

use Bitrix\UI\Toolbar\Facade\Toolbar;

Toolbar::disable();

Вывести панель на своей страницеВывести панель на своей странице

Шаблоны Битрикс24 уже подключают компонент, поэтому обычная страница только настраивает панель через фасад. Подключайте компонент сами, если пишете свой шаблон сайта, страницу административного раздела или вторую панель на странице.

<?php

$APPLICATION->IncludeComponent('bitrix:ui.toolbar', '', []);

Компонент принимает три параметра.

Для страниц административного раздела подключайте шаблон admin. Шаблон выводит ту же панель по умолчанию, а звезду избранного берет из административного раздела.

<?php

$APPLICATION->IncludeComponent('bitrix:ui.toolbar', 'admin', []);

Страницу в слайдере оборачивает компонент bitrix:ui.sidepanel.wrapper. Панель он выводит по умолчанию, поэтому внутри слайдера настраивайте ее так же, как на обычной странице.

На панель в слайдере влияют параметры компонента-обертки.

Когда компонент выводит панель, он убирает у нее кнопку фокус-режима.

Вывести несколько панелейВывести несколько панелей

Вторую панель создайте через менеджер и выведите компонентом с ее идентификатором. Фасад по-прежнему работает только с панелью по умолчанию, поэтому дополнительную панель настраивайте через объект.

<?php

use Bitrix\UI\Toolbar\ButtonLocation;
use Bitrix\UI\Toolbar\Manager;

$toolbar = Manager::getInstance()->createToolbar('orders_report_toolbar', []);
$toolbar->setTitle('Отчет по заказам');
$toolbar->addButton(
    [
        'text' => 'Выгрузить',
        'link' => '/orders/report/export/',
    ],
    ButtonLocation::RIGHT
);

$APPLICATION->IncludeComponent('bitrix:ui.toolbar', '', [
    'TOOLBAR_ID' => 'orders_report_toolbar',
]);

Менеджер панелей дает два метода:

• createToolbar($id, $options) — создает панель с заданным идентификатором. Идентификатор обязателен: с пустой строкой метод выбрасывает ArgumentException. Массив $options поддерживает ключ filter — с ним панель сразу подключит фильтр с этими параметрами.

• getToolbarById($id) — возвращает уже созданную панель или null, если панели с таким идентификатором нет.

Собрать панель для страницы со спискомСобрать панель для страницы со списком

Типовая страница списка собирает панель целиком.

<?php

use Bitrix\Main\Loader;
use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Buttons\Color;
use Bitrix\UI\Buttons\Icon;
use Bitrix\UI\Buttons\JsCode;
use Bitrix\UI\Toolbar\ButtonLocation;
use Bitrix\UI\Toolbar\Facade\Toolbar;

if (!Loader::includeModule('ui'))
{
    return;
}

Toolbar::setTitle('Заказы');

Toolbar::addButton(
    new Button([
        'text' => 'Создать заказ',
        'color' => Color::PRIMARY,
        'onclick' => new JsCode('BX.SidePanel.Instance.open("/orders/edit/0/");'),
    ]),
    ButtonLocation::AFTER_TITLE
);

Toolbar::addFilter([
    'FILTER_ID' => 'orders_filter',
    'GRID_ID' => 'orders_grid',
    'FILTER' => [
        ['id' => 'FIND', 'name' => 'Поиск'],
        ['id' => 'STATUS', 'name' => 'Статус', 'type' => 'list'],
    ],
]);

Toolbar::addButton(
    new Button([
        'text' => 'Экспорт',
        'color' => Color::LIGHT_BORDER,
        'link' => '/orders/export/',
        'dataset' => [
            'toolbar-collapsed-icon' => Icon::DOWNLOAD,
        ],
    ])
);

Toolbar::setCopyLinkButton();

Панель выведет заголовок «Заказы» со звездой избранного и кнопкой копирования ссылки, кнопку создания сразу после заголовка, фильтр по центру и кнопку экспорта справа. При нехватке ширины кнопка экспорта свернется до иконки.

Управлять панелью из JavaScriptУправлять панелью из JavaScript

Панель регистрирует себя в объекте BX.UI.ToolbarManager. Через него страница получает объект панели и работает с ее кнопками после загрузки.

const toolbar = BX.UI.ToolbarManager.getDefaultToolbar();
// или по идентификатору
const reportToolbar = BX.UI.ToolbarManager.get('orders_report_toolbar');

Если панели нет, оба метода возвращают null.

Создавайте панель в PHP, а в JavaScript получайте готовый объект. Метод create() с уже занятым идентификатором завершается ошибкой, потому что идентификатор панели уникален.

Чтобы получить кнопку в JavaScript, задайте ей уникальный идентификатор в PHP.

use Bitrix\UI\Buttons\Button;
use Bitrix\UI\Toolbar\Facade\Toolbar;

$button = new Button(['text' => 'Обновить']);
$button->setUniqId('orders-refresh');

Toolbar::addButton($button);

Скрипт страницы получает кнопку по идентификатору и переводит ее в состояние ожидания.

const toolbar = BX.UI.ToolbarManager.getDefaultToolbar();
const button = toolbar?.getButton('orders-refresh');

if (button)
{
    button.setWaiting(true);
}

Обработать редактирование заголовкаОбработать редактирование заголовка

Панель отправляет три события в пространстве имен BX.UI.Toolbar.

Кнопка отмены возвращает прежний заголовок и не вызывает finishEditing.

Обработчик отправляет новый заголовок на сервер после завершения редактирования.

const toolbar = BX.UI.ToolbarManager.getDefaultToolbar();

toolbar.subscribe('finishEditing', (event) => {
    const { updatedTitle } = event.getData();

    BX.ajax.runAction('mycompany:report.rename', {
        data: {
            id: reportId,
            title: updatedTitle,
        },
    });
});

Подписка на объекте панели работает с коротким именем события. Для глобальной подписки через BX.Event.EventEmitter.subscribe() используйте полное имя с пространством имен, например BX.UI.Toolbar:finishEditing.

Связанные материалыСвязанные материалы

• Кнопки ui.buttons — создание кнопок, оформление, состояния и меню.

• Фильтр main.ui.filter — параметры компонента, типы полей и связка с таблицей.

• Таблица main.ui.grid — список данных под панелью инструментов.

• Боковая панель main.sidepanel — открытие страниц в слайдере.