Работа с параметрами компонента

Параметры — это интерфейс компонента для контент-менеджера и разработчика. Грамотно описанный .parameters.php превращает компонент в гибкий инструмент, а корректная обработка $arParams в component.php защищает от неверных данных.

Где описываются параметры

Параметры компонента объявляются в файле .parameters.php в корне компонента. Он возвращает массив $arComponentParameters с двумя ключами: GROUPS (группировка полей в редакторе) и PARAMETERS (сами поля).

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

$arComponentParameters = [
  'GROUPS' => [
    'SETTINGS' => ['NAME' => 'Настройки вывода', 'SORT' => 100],
  ],
  'PARAMETERS' => [ /* поля */ ],
];

Типы полей параметров

Каждый параметр — это массив с ключами PARENT (группа), NAME, TYPE и DEFAULT. Тип определяет элемент управления в редакторе.

Пример поля-списка с множественным выбором:

'SORT_BY' => [
  'PARENT' => 'SETTINGS',
  'NAME' => 'Сортировать по',
  'TYPE' => 'LIST',
  'VALUES' => ['SORT' => 'Сортировке', 'NAME' => 'Названию'],
  'MULTIPLE' => 'N',
  'DEFAULT' => 'SORT',
  'ADDITIONAL_VALUES' => 'Y',
],

Готовые наборы параметров ядра

Не нужно вручную описывать типовые поля вроде настроек кэша или AJAX — ядро предоставляет функции, возвращающие готовые наборы:

• CComponentUtil::GetComponentProps() — служебные утилиты для параметров;
• $arComponentParameters['PARAMETERS'] дополняют через CIBlockParameters::GetFieldCode() для полей инфоблоков;
• стандартные группы CACHE_SETTINGS, AJAX_SETTINGS, URL_TEMPLATES подключают через готовые массивы.

Например, блок настроек кэширования добавляется так:

'CACHE_TIME' => ['DEFAULT' => 36000],

А для полей и свойств инфоблока применяют CIBlockParameters::GetFieldCode() и CIBlockParameters::GetPropertyCodes(), чтобы менеджер выбирал их из выпадающих списков, а не вписывал вручную.

Связанные списки и REFRESH

Классический сценарий: выбрали инфоблок — и в соседнем поле подгрузились его свойства. Это делается через REFRESH_OPTIONS и обращение к уже выбранным значениям через $arCurrentValues.

$iblockId = (int)($arCurrentValues['IBLOCK_ID'] ?? 0);
$props = [];
if ($iblockId > 0) {
  $res = CIBlockProperty::GetList([], ['IBLOCK_ID' => $iblockId]);
  while ($p = $res->Fetch())
    $props[$p['CODE']] = $p['NAME'];
}

Чтобы поле инфоблока перезагружало форму, ему задают 'REFRESH' => 'Y'. Тогда при смене инфоблока редактор параметров переопросит .parameters.php и подставит актуальный список свойств.

Обработка $arParams в component.php

Значения параметров приходят в компонент в массиве $arParams. Их нельзя использовать «как есть»: ядро частично приводит типы, но валидацию и приведение отвечающих за выборку полей выполняют вручную в начале component.php.

$arParams['IBLOCK_ID'] = (int)$arParams['IBLOCK_ID'];
$arParams['COUNT'] = (int)($arParams['COUNT'] ?? 20);
if ($arParams['COUNT'] <= 0) $arParams['COUNT'] = 20;
$arParams['CACHE_TIME'] = (int)($arParams['CACHE_TIME'] ?? 3600);
$arParams['SET_TITLE'] = ($arParams['SET_TITLE'] ?? 'N') === 'Y';

Условное отображение полей

Чтобы редактор не пестрел неактуальными полями, их показывают по условию. За это отвечает связка типа CUSTOM и JS, но чаще достаточно перегенерации через REFRESH: в .parameters.php вы просто не добавляете ненужные поля в массив, если по $arCurrentValues они не требуются.

• показывать поле «Свойство цены» только если включён вывод цен;
• скрывать настройки постраничной навигации при 'DISPLAY_BOTTOM_PAGER' => 'N';
• подгружать список складов только после выбора типа цены.

Такой подход держит форму настроек компактной и понятной для контент-менеджера, снижая число ошибок конфигурации на боевом сайте.

Отдельно стоит помнить про множественные параметры: при 'MULTIPLE' => 'Y' значение приходит в $arParams массивом, и его нужно обрабатывать циклом, а не приводить к строке. А параметры типа CUSTOM позволяют встроить в форму настроек собственный виджет — например, выбор цвета или карту, — подключив JS-файл через ключ JS_FILE и вернув готовый HTML. Это мощный инструмент, но применять его стоит осознанно: чем сложнее форма, тем выше цена поддержки.

Итог

Хороший компонент начинается с продуманного .parameters.php: сгруппированные поля, правильные типы, связанные списки через REFRESH и $arCurrentValues. А безопасность обеспечивает валидация $arParams в component.php и корректный учёт параметров в ключе кэша.

Когда компонентов много и их настройки должны быть единообразны и защищены от ошибок операторов, мы в B2Bsite проектируем параметры и валидацию так, чтобы даже сложный каталог настраивался без правки кода и без сюрпризов с кэшем.