Типичная ситуация: менеджер просит изменить количество элементов в слайдере или добавить фильтр по дате. Без кастомных параметров приходится править шаблон страницы, тратить час, а потом ещё два на тестирование. На одном из проектов мы столкнулись с задачей: слайдер товаров должен был менять количество элементов от сезона. Разработчик тратил 4 часа на правку шаблона. После внедрения кастомных параметров менеджер сам меняет настройку за 2 минуты. Результат: время внесения изменений сократилось в 3 раза, а правки шаблонов перестали быть узким местом. На другом проекте потребовалось динамически менять порядок сортировки товаров в разделе — после добавления кастомного параметра 'Тип сортировки' менеджер мог выбирать 'по цене', 'по популярности' без участия разработчика. Итог: снижение времени на внесение изменений в 4 раза. Подробнее о параметрах компонентов в документации Битрикс.
Зачем нужен .parameters.php
Стандартный вызов компонента с жёсткими параметрами:
$APPLICATION->IncludeComponent('custom:product.slider', '', [
'IBLOCK_ID' => 5,
'COUNT' => 8,
'SHOW_PRICE' => 'Y',
]);
Это работает, но при изменении требований разработчик должен править код. С .parameters.php менеджер сам меняет настройки через интерфейс. Кастомные параметры в 3 раза сокращают время внесения изменений по сравнению с правкой шаблонов. Экономия времени на повторных доработках достигает 70%. Опыт показывает: грамотно спроектированные параметры — это документация в коде, которая живёт с проектом.
Типы параметров и когда что использовать
В Битрикс поддерживаются следующие типы (TYPE в массиве параметра):
| Тип | Когда использовать |
|---|---|
STRING |
Заголовок, CSS-класс, URL |
LIST |
Выбор из набора значений |
CHECKBOX |
Да/Нет флаги |
NUMBER |
Количество, лимиты |
COLORPICKER |
Выбор цвета |
FILE |
Путь к файлу |
CUSTOM |
Произвольный HTML-виджет |
Для параметра LIST можно указать REFRESH => 'Y', чтобы при выборе значения перезагружалась форма и появлялись новые параметры — например, зависимые поля. В 90% случаев достаточно стандартных типов, CUSTOM-виджеты требуются в 5% проектов.
Пошаговое создание кастомного параметра
- Создайте файл
.parameters.phpв папке компонента. - Определите группы параметров (GROUPS) для логической структуры.
- Опишите каждый параметр: тип, название, значение по умолчанию.
- Для зависимых параметров укажите REFRESH => 'Y'.
- Выполните нормализацию в
component.phpилиonPrepareComponentParams. - Добавьте CUSTOM-виджет, если стандартных типов недостаточно.
Полноценный .parameters.php (нажмите, чтобы развернуть)
<?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 лет в разработке Битрикс. Гарантируем качество и соблюдение стандартов безопасности. Если хотите, чтобы компоненты были гибкими и управляемыми — закажите разработку кастомных параметров. Получите консультацию по вашему проекту — оценим трудоёмкость и предложим оптимальное решение.
Сроки
| Объём параметров | Что входит | Срок |
|---|---|---|
| 5–10 параметров | Стандартные типы, группы, нормализация | 1–2 дня |
| 15–25 параметров | + SECTION-тип, REFRESH, зависимые параметры | 3–5 дней |
| + CUSTOM-виджеты | + JS-обработчики, сложные UI в форме | 1 неделя |
Свяжитесь с нами — поможем сделать компоненты гибкими и управляемыми. Хорошо спроектированные параметры компонента — это документация в коде. Разработчик открывает .parameters.php и сразу понимает, что умеет компонент и какие значения ожидает.