Как создать свой компонент на 1С-Битрикс с class.php и IncludeComponent?

Вы скопировали шаблон bitrix:catalog.section в /bitrix/components и после обновления потеряли правки. Или написали component.php по старому гайду — блок есть через IncludeComponent, но в визуальном редакторе его нет: типичная проблема, когда логика живёт не в /local. На практике путь к своему компоненту в 1С-Битрикс: Управление сайтом — /local/components, class.php и $APPLICATION->IncludeComponent. К концу материала у вас будет рабочий каркас, который переживёт обновление CMS.

Свой компонент живёт только в /local/components/vendor/name, а не в /bitrix. Логику пишите в class.php с методом executeComponent, описание для редактора - в .description.php с массивом PATH. Подключение - $APPLICATION->IncludeComponent('vendor:name', '', $arParams). Если блок пустой или не виден в редакторе - проверьте namespace, точку в имени .description.php и сброс кэша компонентов.

Речь про коробочную CMS на вашем сервере, не про облачный портал Bitrix24. Компонент — PHP-блок, который собирает данные и отдаёт их в шаблон. Штатные лежат в /bitrix/components/bitrix/, ваши — в /local/components/свой_вендор/. Система сначала ищет /local, потом ядро — кастом не затирается при обновлении. Поля формы редактора разобраны в гайде по .parameters.php — здесь только создание с нуля.

Определите, когда нужен свой компонент, а когда хватит шаблона

Часто хватает переопределения шаблона bitrix:* в /local/templates/ваш_шаблон/components/ - меняете вёрстку, логика остаётся в ядре.

Для каталога штатно смотрите bitrix:catalog.section. Свой компонент - когда логика не укладывается в параметры bitrix:*.

Делайте: начинайте с шаблона, если меняется только HTML/CSS. Не делайте: не клонируйте весь catalog.section в /local ради одного поля - поддержка станет дороже обновления ядра.

Создайте структуру папок в /local/components

Имя в коде - vendor:name, папка - /local/components/vendor/name/. Вендор - ваш бренд (mycompany), не bitrix - иначе конфликт с системными компонентами. Минимальный набор:

• .description.php - имя и путь в дереве визуального редактора (файл с точкой в начале).
• class.php - класс, наследник CBitrixComponent, метод executeComponent.
• templates/.default/template.php - HTML-вывод по $arResult.

1. Выберите vendor (например mycompany) и имя (hello.card).
2. Создайте каталог /local/components/mycompany/hello.card/.
3. Добавьте .description.php с NAME, DESCRIPTION и PATH.
4. Создайте class.php с классом HelloCardComponent extends CBitrixComponent.
5. Сделайте templates/.default/template.php для вывода.
6. Проверьте в браузере, что hello.card отдаёт HTML без фатальных ошибок.

Каркас быстрее собрать консолью: php bitrix.php make:component Mycompany:HelloCard --local.

Делайте: свой vendor в /local/components/. Не делайте: не правьте файлы в /bitrix/components - обновление CMS перезапишет изменения.

Настройте .description.php, чтобы компонент появился в редакторе

Без корректного .description.php компонент не попадёт в панель «Мои компоненты», даже если IncludeComponent на странице работает. Ключ PATH задаёт раздел в дереве редактора. В реальном проекте типичная ошибка — файл description.php без точки в начале имени.

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

$arComponentDescription = [
    'NAME' => 'Приветственная карточка',
    'DESCRIPTION' => 'Выводит заголовок и текст из параметров',
    'PATH' => [
        'ID' => 'mycompany',
        'NAME' => 'Мои компоненты',
    ],
];

Если не виден: файл без точки (description.php вместо .description.php), нет PATH, не сброшен кэш компонентов в админке.

Делайте: проверяйте имя файла .description.php буквально с точкой. Не делайте: не кладите компонент в /local/components/bitrix/ - выберите свой ID в PATH.

Напишите логику в class.php вместо legacy component.php

Старые гайды учат component.php. Сейчас логику пишут в class.php: класс extends CBitrixComponent, вход - executeComponent(). Если оба файла в папке, ядро берёт class.php и игнорирует component.php.

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

use Bitrix\Main\Loader;

class HelloCardComponent extends CBitrixComponent
{
    public function onPrepareComponentParams($arParams)
    {
        $arParams['TITLE'] = trim((string)($arParams['TITLE'] ?? 'Привет'));
        $arParams['CACHE_TIME'] = (int)($arParams['CACHE_TIME'] ?? 3600);
        return $arParams;
    }

    public function executeComponent()
    {
        if ($this->startResultCache()) {
            $this->arResult['TITLE'] = $this->arParams['TITLE'];
            $this->arResult['TEXT'] = 'Компонент mycompany:hello.card работает.';
            $this->endResultCache();
        }
        $this->includeComponentTemplate();
    }
}

onPrepareComponentParams - дефолты и типы. В executeComponent заполняйте $this->arResult, затем includeComponentTemplate(). Шаблон только выводит данные. Параметры формы - в .parameters.php, разбор в гайде по .parameters.php; для hello.card хватит TITLE в IncludeComponent.

Делайте: один вход в логику через class.php. Не делайте: не подключайте .parameters.php вручную из class.php - дефолты задавайте в onPrepareComponentParams.

Схема workflow:
IncludeComponent передаёт $arParams → onPrepareComponentParams нормализует → executeComponent заполняет $arResult → includeComponentTemplate подключает templates/.default/template.php → браузер получает HTML

Подключите компонент через IncludeComponent на странице

Вызов на PHP-странице или в шаблоне сайта:

<?php
$APPLICATION->IncludeComponent(
    'mycompany:hello.card',
    '',
    [
        'TITLE' => 'Заголовок с страницы',
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => '3600',
    ],
    false
);
?>

Аргументы: vendor:name, имя шаблона ('' = .default), массив в $arParams, false без обёртки div. Шаблон:

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
    die();
}
?>
<div class="hello-card">
    <h3><?= htmlspecialcharsbx($arResult['TITLE']) ?></h3>
    <p><?= htmlspecialcharsbx($arResult['TEXT']) ?></p>
</div>

В режиме правки перетащите блок из раздела «Мои компоненты» редактора. Нет вывода — включите ошибки по settings.php и проверьте class.php.

Делайте: совпадение ключей в IncludeComponent и в onPrepareComponentParams. Не делайте: не вызывайте includeComponentTemplate до заполнения $arResult - шаблон получит пустой массив.

Проверьте вывод, кэш и типичные ошибки

Чек-лист перед сдачей задачи в прод:

1. Страница: блок виден, TITLE из параметров попадает в HTML.
2. Редактор: компонент в дереве PATH, перетаскивание создаёт корректный IncludeComponent.
3. Кэш: после правки template.php очистите кэш; при startResultCache пустой результат лучше обрабатывать через abortResultCache.
4. Namespace: папка не в /local/components/bitrix/, vendor в коде совпадает с папкой.
5. Файлы: .description.php с точкой, class.php с executeComponent и includeComponentTemplate в конце.

Старая вёрстка на экране - чаще кэш, не "сломанный" Битрикс. После правки template.php сбросьте кэш или CACHE_TYPE = N для отладки.

Нужна помощь с блоком под каталог - обсудим задачу, примеры в портфолио. Делайте: сначала минимальный hello.card. Не делайте: не правьте ядро и /local одновременно.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: docs.1c-bitrix.ru - создание компонента, урок 2305 курса разработчика, урок 2826 - подключение компонента.

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