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