Перейти к содержимому
BXWiki

Админ-интерфейс 1С-Битрикс - гриды, фильтр, формы, панель

Интерфейсы административного раздела строят на классах старого ядра - D7-аналога для админки нет. Разберём современный слой работы со списком, обработку действий и элементы публичной панели управления.

Как это работает

Два семейства табличных интерфейсов, и их путают. Первое - админ-гриды внутри административного раздела: они строятся на глобальных классах, где базовый более старый, а его наследник даёт современный вид списка. Именно наследник - текущий способ делать админ-список. Второе семейство - грид публичной части на D7-классах с отдельной панелью фильтра и своими JS-расширениями; это другая тема.

Один скрипт списка обслуживает разные запросы: обычный показ страницы, обновление без перезагрузки, inline-редактирование, выгрузку в таблицу, форму настроек. Раньше режим определяли ручным разбором параметров запроса, начиная с версии 21.600.0 у классов списка есть методы-предикаты для каждого режима.

Действия над строками бывают двух видов. Inline-редактирование обрабатывается цепочкой из трёх шагов, причём средний шаг - преобразование файлов - пропускать нельзя. Групповые операции дают массив выбранных идентификаторов, идентификатор действия и признак «применить ко всем».

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

Примеры

1. Режимы списка

$lAdmin = new CAdminUiList('my_module_items');


if ($lAdmin->isExportMode()) {
    // выгрузка: не рисуем интерфейс, только данные
}


if ($lAdmin->isConfigMode()) {
    // форма настроек списка
}


if ($lAdmin->isActionMode()) {
    // обработка действий
}

Раньше это выглядело как разбор параметра запроса вручную; теперь есть предикаты на каждый режим и константы с их значениями. Обратите внимание: часть режимов прерывает выполнение скрипта, поэтому порядок проверок важен.

2. Inline-редактирование

if ($lAdmin->EditAction()) {
    $lAdmin->convertFilesToEditFields();      // без этого шага файлы потеряются


    foreach ($lAdmin->getEditFields() as $id => $fields) {
        $result = ItemTable::update($id, $fields);


        if (!$result->isSuccess()) {
            $lAdmin->AddUpdateError(implode(', ', $result->getErrorMessages()), $id);
        }
    }
}

Средний шаг - самая частая причина ошибки «загруженные файлы исчезают при быстрой правке».

3. Групповые действия

if (($ids = $lAdmin->GroupAction()) && !empty($ids)) {
    $actionId = $lAdmin->getAction();


    if ($actionId === null) {
        return;      // без проверки switch сработает по пустому действию
    }


    if ($lAdmin->isGroupActionToAll()) {
        $ids = $this->getAllIds();
    }


    foreach ($ids as $id) {
        switch ($actionId) {
            case 'delete':
                ItemTable::delete($id);
                break;
            case 'activate':
                ItemTable::update($id, ['ACTIVE' => 'Y']);
                break;
        }
    }
}

Метод группового действия объявлен как возвращающий логическое значение, но фактически отдаёт массив идентификаторов - результат нужно присваивать и проверять как массив.

4. Кнопки публичной панели

$APPLICATION->AddPanelButton([
    'ID' => 'my_module_settings',
    'TEXT' => 'Настройки модуля',
    'ICON' => 'bx-panel-settings-icon',
    'HREF' => '/bitrix/admin/settings.php?lang=ru&mid=my.module',
]);
// иконки правки включаемой области - только в режиме редактирования
if ($APPLICATION->GetShowIncludeAreas()) {
    $this->AddIncludeAreaIcons([
        [
            'ID' => 'area_' . $areaId,
            'TITLE' => 'Изменить блок',
            'ACTION' => 'jsUtils.Redirect([], "' . CUtil::JSEscape($editUrl) . '")',
        ],
    ]);
}

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

Справочник API

APIНазначениеОсобенности
CAdminUiListсовременный админ-списокнаследник базового класса, D7-аналога нет
CAdminListбазовый класс спискастарше, встречается в легаси
getCurrentMode() и предикаты режимовопределение режима запросастраница, список, действие, выгрузка, настройки
EditAction()начало обработки быстрой правки
convertFilesToEditFields()подготовка файловобязательный шаг перед чтением полей
getEditFields()изменённые поля по строкам
GroupAction()выбранные строкифактически возвращает массив идентификаторов
getAction()идентификатор действияможет быть пустым - проверяйте
isGroupActionToAll()признак «ко всем записям»
AddUpdateError()ошибка по строкепоказывается в интерфейсе списка
CAdminTabControlформа редактирования на вкладках
AddPanelButton() / AddPanelButtonMenu()кнопки публичной панелиуникальные идентификаторы
AddIncludeAreaIcons()иконки правки в шаблоне компонентавнутри проверки режима правки
SetEditArea() / GetEditAreaID()привязка контекстного меню строкивызывается в эпилоге компонента
Bitrix\Main\Grid, UI\Filter\OptionsD7-грид публичной частиотдельное семейство, не для админки

Частые ошибки

Файлы исчезают при быстрой правке. Пропущен шаг преобразования файлов перед чтением изменённых полей.

Групповое действие срабатывает по пустому идентификатору. Значение действия не проверено на пустоту.

Результат группового действия считают логическим. Метод фактически возвращает массив идентификаторов.

Иконки правки выводятся вне режима редактирования. Нет проверки режима.

Контекстное меню строки не привязывается. Идентификатор области в разметке и в вызове различаются, либо привязка сделана не в эпилоге компонента.

Пытаются использовать D7-грид в админке. Это другое семейство интерфейсов - для административного раздела используют классы списка старого ядра.

Частые вопросы

Есть ли D7-замена для админ-списков?

Для административного раздела - нет. Современный способ там - наследник базового класса списка из старого ядра, и это нормальная практика, а не легаси по недосмотру. D7-грид существует, но он предназначен для публичной части: у него своя панель фильтра и свои JS-расширения.

Как обработать разные режимы одного скрипта списка?

Через методы-предикаты, появившиеся в версии 21.600.0: они отвечают, идёт ли обычный показ страницы, обновление списка, обработка действия, выгрузка или показ формы настроек. Раньше режим разбирали вручную по параметрам запроса, но этот способ хрупкий. Учтите, что некоторые режимы прерывают выполнение скрипта, поэтому порядок проверок имеет значение.

Почему при inline-редактировании пропадают файлы?

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

Как добавить свою кнопку в панель администратора?

Методом добавления кнопки панели с уникальным идентификатором - в нём указывают текст, иконку и адрес. Для выпадающего списка есть отдельный метод меню кнопки. Не путайте это с иконками правки включаемых областей в шаблонах компонентов: те выводятся только в режиме редактирования и требуют явной проверки.

Связанные темы

Первоисточники