Разработка кастомных параметров компонентов 1С-Битрикс

Разработка кастомных параметров компонентов 1С-Битрикс

Компонент, который работает только с жёстко вшитыми в код настройками — это не компонент, это скрипт. Кастомные параметры (.parameters.php) делают компонент настраиваемым через визуальный редактор Битрикс без редактирования кода. Для сложных проектов с командой из разработчиков и менеджеров содержимого — это критичная часть архитектуры.

Зачем нужны кастомные параметры

Стандартный вызов компонента с жёсткими параметрами:

$APPLICATION->IncludeComponent('custom:product.slider', '', [
    'IBLOCK_ID' => 5,
    'COUNT'     => 8,
    'SHOW_PRICE' => 'Y',
]);

Это работает, но при изменении требований разработчик должен лезть в шаблон страницы. С .parameters.php менеджер сам меняет настройки через интерфейс «Свойства компонента».

Типы параметров и когда что использовать

В Битрикс поддерживаются следующие типы (TYPE в массиве параметра):

Полноценный .parameters.php

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();

use Bitrix\Main\Loader;

// Подготовка данных для параметров типа LIST
$arIblockList = ['' => '-- Выберите инфоблок --'];
if (Loader::includeModule('iblock')) {
    $res = CIBlock::GetList(['SORT' => 'ASC'], ['ACTIVE' => 'Y', 'SITE_ID' => SITE_ID]);
    while ($ib = $res->Fetch()) {
        $arIblockList[$ib['ID']] = '[' . $ib['ID'] . '] ' . $ib['NAME'];
    }
}

$arSortOptions = [
    'SORT_ASC'         => 'По порядку (возрастание)',
    'SORT_DESC'        => 'По порядку (убывание)',
    'DATE_ACTIVE_FROM_DESC' => 'По дате (новые)',
    'NAME_ASC'         => 'По названию (А-Я)',
    'RAND'             => 'Случайный порядок',
];

$arLayoutOptions = [
    'grid'   => 'Сетка',
    'list'   => 'Список',
    'slider' => 'Слайдер',
];

$arComponentParameters = [
    'GROUPS' => [
        'DATA'      => ['NAME' => 'Источник данных', 'SORT' => 10],
        'FILTER'    => ['NAME' => 'Фильтрация',      'SORT' => 20],
        'DISPLAY'   => ['NAME' => 'Отображение',     'SORT' => 30],
        'SEO'       => ['NAME' => 'SEO и заголовки', 'SORT' => 40],
        'CACHE'     => ['NAME' => 'Кеширование',     'SORT' => 50],
    ],
    'PARAMETERS' => [
        // === Группа DATA ===
        'IBLOCK_ID' => [
            'PARENT'  => 'DATA',
            'NAME'    => 'Инфоблок',
            'TYPE'    => 'LIST',
            'VALUES'  => $arIblockList,
            'DEFAULT' => '',
            'REFRESH' => 'Y', // перезагружает форму при изменении — нужно для динамических параметров
        ],
        'SECTION_ID' => [
            'PARENT'  => 'DATA',
            'NAME'    => 'Раздел (оставьте пустым для всех)',
            'TYPE'    => 'SECTION',          // специальный тип: выбор раздела инфоблока
            'IBLOCK_ID_VARIABLE' => 'IBLOCK_ID', // берёт ID инфоблока из другого параметра
            'DEFAULT' => '',
        ],
        'ELEMENT_SORT_FIELD' => [
            'PARENT'  => 'DATA',
            'NAME'    => 'Сортировка',
            'TYPE'    => 'LIST',
            'VALUES'  => $arSortOptions,
            'DEFAULT' => 'SORT_ASC',
        ],

        // === Группа FILTER ===
        'SHOW_ACTIVE_ONLY' => [
            'PARENT'  => 'FILTER',
            'NAME'    => 'Только активные',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'Y',
        ],
        'ACTIVE_DATE_FROM' => [
            'PARENT'  => 'FILTER',
            'NAME'    => 'Активны с (дата)',
            'TYPE'    => 'STRING',
            'DEFAULT' => '',
        ],

        // === Группа DISPLAY ===
        'LAYOUT' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Тип отображения',
            'TYPE'    => 'LIST',
            'VALUES'  => $arLayoutOptions,
            'DEFAULT' => 'grid',
        ],
        'COUNT' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Количество элементов',
            'TYPE'    => 'STRING',
            'DEFAULT' => '12',
        ],
        'COLUMNS' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Колонок в строке',
            'TYPE'    => 'LIST',
            'VALUES'  => ['2' => '2', '3' => '3', '4' => '4', '6' => '6'],
            'DEFAULT' => '4',
        ],
        'SHOW_PICTURE' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Показывать изображение',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'Y',
        ],
        'PICTURE_SIZE_X' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Ширина изображения (px)',
            'TYPE'    => 'STRING',
            'DEFAULT' => '300',
        ],
        'PICTURE_SIZE_Y' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Высота изображения (px)',
            'TYPE'    => 'STRING',
            'DEFAULT' => '200',
        ],
        'SHOW_PRICE' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Показывать цену',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'Y',
        ],
        'CSS_CLASS' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Дополнительный CSS-класс блока',
            'TYPE'    => 'STRING',
            'DEFAULT' => '',
        ],

        // === Группа SEO ===
        'SET_TITLE' => [
            'PARENT'  => 'SEO',
            'NAME'    => 'Устанавливать заголовок страницы',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'N',
        ],
        'BLOCK_HEADING' => [
            'PARENT'  => 'SEO',
            'NAME'    => 'Заголовок блока (H2)',
            'TYPE'    => 'STRING',
            'DEFAULT' => '',
        ],

        // === Группа CACHE ===
        'CACHE_TYPE'   => ['DEFAULT' => 'A'],  // A = Auto
        'CACHE_TIME'   => ['DEFAULT' => 3600],
        'CACHE_GROUPS' => ['DEFAULT' => 'N'],  // Кешировать отдельно по группам пользователей
    ],
];

Параметр типа CUSTOM

Когда стандартных типов недостаточно — например, нужен выбор нескольких разделов или цветовая палитра — используется тип CUSTOM:

'SELECTED_SECTIONS' => [
    'PARENT'  => 'DATA',
    'NAME'    => 'Разделы (множественный выбор)',
    'TYPE'    => 'CUSTOM',
    'DEFAULT' => '',
    'JS_EVENT' => 'onCustomParamRender',
],

В JavaScript обработчик onCustomParamRender рисует произвольный HTML-виджет в форме настроек компонента. Это продвинутая возможность, используется редко, но иногда незаменима.

Нормализация параметров в component.php

Параметры из .parameters.php приходят в component.php как строки или массивы — их нужно нормализовать перед использованием:

// В component.php или в onPrepareComponentParams класса
$arParams['IBLOCK_ID']    = (int) $arParams['IBLOCK_ID'];
$arParams['COUNT']        = max(1, min(100, (int) $arParams['COUNT']));
$arParams['COLUMNS']      = in_array($arParams['COLUMNS'], ['2','3','4','6']) ? (int)$arParams['COLUMNS'] : 4;
$arParams['SHOW_PICTURE'] = $arParams['SHOW_PICTURE'] === 'Y';
$arParams['SHOW_PRICE']   = $arParams['SHOW_PRICE'] === 'Y';
$arParams['CSS_CLASS']    = htmlspecialchars(trim($arParams['CSS_CLASS'] ?? ''));

Без нормализации разработчик защищён от опечаток в вызове компонента и от XSS через параметры.

Использование параметров в шаблоне

// template.php
$cssClass = 'products-block products-block--' . $arParams['LAYOUT'];
if ($arParams['CSS_CLASS']) $cssClass .= ' ' . $arParams['CSS_CLASS'];
?>
<div class="<?= $cssClass ?>" style="--columns: <?= $arParams['COLUMNS'] ?>">
    <?php if ($arParams['BLOCK_HEADING']): ?>
        <h2><?= htmlspecialchars($arParams['BLOCK_HEADING']) ?></h2>
    <?php endif; ?>
    <?php foreach ($arResult['ITEMS'] as $item): ?>
        <!-- ... -->
    <?php endforeach; ?>
</div>

CSS-переменная --columns управляет сеткой:

.products-block {
    display: grid;
    grid-template-columns: repeat(var(--columns, 4), 1fr);
    gap: 20px;
}

Документирование параметров

Для команды, которая будет использовать компонент, — документация в README или прямо в .description.php:

$arComponentDescription = [
    'NAME'        => 'Слайдер товаров',
    'DESCRIPTION' => 'Выводит список товаров из выбранного инфоблока. Параметр LAYOUT управляет типом отображения: grid = сетка, slider = карусель Swiper.',
    // ...
];

Сроки

Хорошо спроектированные параметры компонента — это документация в коде. Разработчик открывает .parameters.php и сразу понимает, что умеет компонент и какие значения ожидает.