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

Типова ситуація: менеджер просить змінити кількість елементів у слайдері або додати фільтр за датою. Без кастомних параметрів доводиться правити шаблон сторінки, витрачати годину, а потім ще дві на тестування. На одному з проєктів ми зіткнулися із завданням: слайдер товарів мав змінювати кількість елементів залежно від сезону. Розробник витрачав 4 години на правку шаблону. Після впровадження кастомних параметрів менеджер сам змінює налаштування за 2 хвилини. Результат: час внесення змін скоротився в 3 рази, а правки шаблонів перестали бути вузьким місцем. На іншому проєкті потрібно було динамічно змінювати порядок сортування товарів у розділі — після додавання кастомного параметра 'Тип сортування' менеджер міг вибирати 'за ціною', 'за популярністю' без участі розробника. Підсумок: зниження часу на внесення змін у 4 рази. Докладніше про параметри компонентів у документації Бітрікс.

Навіщо потрібен .parameters.php

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

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

Це працює, але при зміні вимог розробник повинен правити код. З .parameters.php менеджер сам змінює налаштування через інтерфейс. Кастомні параметри в 3 рази скорочують час внесення змін порівняно з правкою шаблонів. Економія часу на повторних доопрацюваннях сягає 70%. Досвід показує: грамотно спроєктовані параметри — це документація в коді, яка живе з проєктом.

Типи параметрів і коли що використовувати

У Бітрікс підтримуються такі типи (TYPE у масиві параметра):

Для параметра LIST можна вказати REFRESH => 'Y', щоб при виборі значення перезавантажувалася форма і з'являлися нові параметри — наприклад, залежні поля. У 90% випадків достатньо стандартних типів, CUSTOM-віджети потрібні в 5% проєктів.

Покрокове створення кастомного параметра

1. Створіть файл .parameters.php у папці компонента.
2. Визначте групи параметрів (GROUPS) для логічної структури.
3. Опишіть кожен параметр: тип, назву, значення за замовчуванням.
4. Для залежних параметрів вкажіть REFRESH => 'Y'.
5. Виконайте нормалізацію в component.php або onPrepareComponentParams.
6. Додайте CUSTOM-віджет, якщо стандартних типів недостатньо.

<?php if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die(); use Bitrix\Main\Loader; $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' => [ 'IBLOCK_ID' => [ 'PARENT' => 'DATA', 'NAME' => 'Інфоблок', 'TYPE' => 'LIST', 'VALUES' => $arIblockList, 'DEFAULT' => '', 'REFRESH' => 'Y', ], 'SECTION_ID' => [ 'PARENT' => 'DATA', 'NAME' => 'Розділ (залиште порожнім для всіх)', 'TYPE' => 'SECTION', 'IBLOCK_ID_VARIABLE' => 'IBLOCK_ID', 'DEFAULT' => '', ], 'ELEMENT_SORT_FIELD' => [ 'PARENT' => 'DATA', 'NAME' => 'Сортування', 'TYPE' => 'LIST', 'VALUES' => $arSortOptions, 'DEFAULT' => 'SORT_ASC', ], 'SHOW_ACTIVE_ONLY' => [ 'PARENT' => 'FILTER', 'NAME' => 'Тільки активні', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'Y', ], 'ACTIVE_DATE_FROM' => [ 'PARENT' => 'FILTER', 'NAME' => 'Активні з (дата)', 'TYPE' => 'STRING', 'DEFAULT' => '', ], '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' => '', ], 'SET_TITLE' => [ 'PARENT' => 'SEO', 'NAME' => 'Встановлювати заголовок сторінки', 'TYPE' => 'CHECKBOX', 'DEFAULT' => 'N', ], 'BLOCK_HEADING' => [ 'PARENT' => 'SEO', 'NAME' => 'Заголовок блоку (H2)', 'TYPE' => 'STRING', 'DEFAULT' => '', ], 'CACHE_TYPE' => ['DEFAULT' => 'A'], 'CACHE_TIME' => ['DEFAULT' => 3600], 'CACHE_GROUPS' => ['DEFAULT' => 'N'], ], ]; 

Як додати CUSTOM-віджет параметра?

Коли стандартних типів недостатньо — наприклад, потрібен вибір кількох розділів або кольорова палітра — використовується тип CUSTOM.

На одному проєкті ми реалізували віджет вибору кольорової схеми за допомогою палітри: розробка зайняла 8 годин, але за наступний рік заощадила 20 годин на правках. Розробка такого віджета в середньому займає 4-6 годин. Ось як це виглядає в коді:

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

У JavaScript обробник onCustomParamRender малює довільний HTML-віджет у формі налаштувань компонента. Це просунута можливість, використовується рідко, але іноді незамінна.

Чому нормалізація параметрів важлива?

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

$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 через параметри. Нормалізація також включає приведення дат, масивів ID та перевірку на існування записів. Порівняння: нормалізація знижує кількість помилок часу виконання на 40% порівняно з сирими даними.

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

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

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

Хороша документація скорочує час введення нового розробника в проєкт на 30%.

Що входить у розробку кастомних параметрів

• Аналіз вимог, проєктування структури параметрів
• Створення .parameters.php з групами та залежностями (REFRESH)
• Реалізація CUSTOM-віджетів при необхідності
• Нормалізація вхідних даних у component.php
• Налаштування кешування з урахуванням параметрів для швидкої роботи
• Документування в .description.php або README
• Тестування на всіх браузерах і версіях Бітрікс
• Підтримка після впровадження — допоможемо з доопрацюваннями

Досвід наших розробників — понад 10 років у розробці Бітрікс. Гарантуємо якість і дотримання стандартів безпеки. Якщо хочете, щоб компоненти були гнучкими та керованими — замовте розробку кастомних параметрів. Отримайте консультацію по вашому проєкту — оцінимо трудомісткість і запропонуємо оптимальне рішення.

Строки

Зв'яжіться з нами — допоможемо зробити компоненти гнучкими та керованими. Добре спроєктовані параметри компонента — це документація в коді. Розробник відкриває .parameters.php і одразу розуміє, що вміє компонент і які значення очікує.