Розробка кастомних параметрів компонентів 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 і одразу розуміє, що вміє компонент і які значення очікує.