Как настроить параметры компонента в 1С-Битрикс через .parameters.php?

Вы описали поле в .parameters.php, а в визуальном редакторе его нет. Или поле видно, но в component.php массив $arParams пустой, кроме CACHE_TIME. Знакомая боль: цепочка "форма настроек → IncludeComponent → логика компонента" рвётся в неочевидном месте. Ниже - пошаговый разбор файла .parameters.php в 1С-Битрикс: Управление сайтом: от пустого массива $arComponentParameters до рабочей формы и проверки, что выбранные значения доходят до $arParams.

Файл .parameters.php нужен только для формы в режиме редактирования: на публичном хите он не подключается. Вы описываете GROUPS и PARAMETERS, контент-менеджер выбирает значения в админке, а IncludeComponent передаёт их в $arParams. Если поле не видно - проверьте TYPE. Если $arParams пустой в D7-классе - проверьте return в onPrepareComponentParams().

Речь про коробочную CMS на вашем сервере, не про облачный портал Bitrix24. Если вы только знакомитесь с анатомией компонента, сначала прочитайте обзор структуры компонента - здесь углубимся именно в параметры и форму настроек.

Параметры - настройки, которые редактор меняет без правки PHP: ID инфоблока, лимит элементов, флаги вывода. Файл .parameters.php описывает их для визуального редактора.

Разберите, зачем нужен .parameters.php и когда он выполняется

component.php (или D7-класс) работает при каждом показе страницы: читает $arParams и отдаёт данные в шаблон. .parameters.php выполняется только когда кто-то открывает окно "Настройки компонента" в режиме правки. Официальный урок разработчика прямо говорит: при обычном хите файл не подключается.

Типичная ошибка - include __DIR__.'/.parameters.php' в class.php "для дефолтов". На практике это антипаттерн: дефолты задавайте в onPrepareComponentParams(). Параметры из PHP-страницы и из формы редактора сходятся в один $arParams, но описываются в разных местах.

Делайте: храните .parameters.php в корне компонента: /local/components/vendor/name/.parameters.php. Не делайте: не ждите, что код из этого файла выполнится на публичной странице - для runtime нужен только component.php.

Схема цепочки:
Разработчик пишет .parameters.php → редактор видит форму → сохраняет настройки → IncludeComponent передаёт arParams → component.php получает $arParams → шаблон выводит результат

Создайте минимальный .parameters.php с GROUPS и PARAMETERS

Файл возвращает массив $arComponentParameters с двумя ключами верхнего уровня: GROUPS (вкладки в форме) и PARAMETERS (сами поля). Минимальный рабочий пример - одна группа и одно текстовое поле:

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

$arComponentParameters = [
    'GROUPS' => [
        'MAIN' => [
            'NAME' => 'Основные',
            'SORT' => 100,
        ],
    ],
    'PARAMETERS' => [
        'TITLE' => [
            'PARENT' => 'MAIN',
            'NAME' => 'Заголовок блока',
            'TYPE' => 'STRING',
            'DEFAULT' => 'Новости',
        ],
        'COUNT' => [
            'PARENT' => 'MAIN',
            'NAME' => 'Количество элементов',
            'TYPE' => 'STRING',
            'DEFAULT' => '5',
        ],
    ],
];

1. Создайте .parameters.php рядом с component.php.
2. Добавьте GROUPS - вкладку с NAME и SORT.
3. Опишите PARAMETERS - PARENT, NAME, TYPE, DEFAULT для каждого поля.
4. Подключите компонент через IncludeComponent с теми же ключами в arParams.
5. Откройте настройки в режиме правки и сохраните значения.
6. Проверьте $arParams в component.php - временно print_r.

Делайте: совпадение ключей в PARAMETERS и в arParams вызова IncludeComponent. Не делайте: не оставляйте параметр без TYPE - без него поле не появится в форме, даже если ключ прописан в массиве.

Выберите TYPE и настройте REFRESH для зависимых списков

TYPE определяет виджет в форме. Для 90% задач хватает четырёх типов:

Для каскада "тип инфоблока → ID инфоблока" на поле типа ставят 'REFRESH' => 'Y'. После выбора значения и нажатия OK форма перезагружается, и второй LIST может построить VALUES с учётом $arCurrentValues['IBLOCK_TYPE']. Если инфоблок ещё не создан, сначала пройдите гайд по созданию инфоблока.

'IBLOCK_TYPE' => [
    'PARENT' => 'DATA',
    'NAME' => 'Тип инфоблока',
    'TYPE' => 'LIST',
    'VALUES' => $arIBlockType,
    'REFRESH' => 'Y',
],
'IBLOCK_ID' => [
    'PARENT' => 'DATA',
    'NAME' => 'Инфоблок',
    'TYPE' => 'LIST',
    'VALUES' => $arIBlock[$arCurrentValues['IBLOCK_TYPE'] ?? ''] ?? [],
    'REFRESH' => 'Y',
],

Делайте: REFRESH только там, где список зависит от другого поля. Не делайте: не ставьте REFRESH на каждое поле подряд - форма будет дёргаться при каждом клике.

Добавьте параметры шаблона через templates/.default/.parameters.php

Настройки шаблона лежат в templates/.default/.parameters.php и описываются в $arTemplateParameters. Пример: у шаблона "слайдер" - автопрокрутка, у "списка" - число колонок.

В файле шаблона доступен $arCurrentValues - текущие значения всех параметров. Им пользуются, чтобы показать поле только при определённом режиме:

if (($arCurrentValues['VIEW_MODE'] ?? '') === 'SLIDER') {
    $arTemplateParameters['AUTOPLAY'] = [
        'NAME' => 'Автопрокрутка',
        'TYPE' => 'CHECKBOX',
        'DEFAULT' => 'N',
    ];
}

В template.php значения читают через $arParams['AUTOPLAY'] - ключи шаблонных параметров тоже попадают в общий $arParams.

Делайте: выносите в шаблон только то, что меняет вёрстку, а не бизнес-логику. Не делайте: не дублируйте один и тот же ключ и в корневом .parameters.php, и в шаблонном - получите путаницу в форме.

Локализуйте подписи через lang/ru/.parameters.php

Подписи NAME выносите в lang/ru/.parameters.php через $MESS и GetMessage:

// lang/ru/.parameters.php
$MESS['GROUP_MAIN'] = 'Основные';
$MESS['PARAM_TITLE'] = 'Заголовок блока';

// .parameters.php
$arComponentParameters['GROUPS']['MAIN']['NAME'] = GetMessage('GROUP_MAIN');
$arComponentParameters['PARAMETERS']['TITLE']['NAME'] = GetMessage('PARAM_TITLE');

Делайте: один ключ $MESS на подпись. Не делайте: не смешивайте GetMessage и голый текст без причины.

Прогоните чек-лист: форма видна, $arParams не пустой

Когда "всё вроде правильно, но не работает", в реальном проекте пройдите шесть пунктов по порядку:

1. TYPE задан у каждого параметра в PARAMETERS - без TYPE поле не рендерится.
2. PARENT совпадает с ключом группы в GROUPS - иначе поле уйдёт на несуществующую вкладку.
3. Ключ совпадает с тем, что вы читаете в component.php и передаёте в IncludeComponent.
4. onPrepareComponentParams возвращает массив в D7-классе. Пустой метод без return обнуляет все кастомные ключи - частая ошибка на форумах.
5. Кеш компонента сброшен после смены параметров, если включён CACHE_TYPE=A.
6. Не путаете runtime и редактор - .parameters.php не выполняется на хите, дефолты задавайте в onPrepareComponentParams, а не через include файла параметров.

Для отладки включите вывод ошибок по инструкции для settings.php. Ключи с тильдой (~IBLOCK_ID) - сырое значение; в логике берите ключ без тильды.

Делайте: фиксируйте дефолты в onPrepareComponentParams, если параметр может не прийти из формы. Не делайте: не копируйте чужой .parameters.php без проверки TYPE и PARENT - скопируете и чужие баги.

Что дальше

После рабочей формы параметров логично связать компонент с данными: выборка элементов через GetList или D7 ORM, реакция на события ядра - через обработчик событий. Если нужна помощь с кастомным компонентом под ваш проект - напишите нам, разберём задачу до рабочей формы в редакторе.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: официальный урок "Параметры компонента", блог разработчиков по .parameters.php, документация BitrixFramework по созданию компонента.

Частые вопросы