Свой компонент 1С-Битрикс: структура, код и шаблон

Компонент 1С-Битрикс получает данные и передаёт их в шаблон для вывода. Например, он может показывать последние новости, форму или список товаров.

Создадим компонент «Последние новости» на классе CBitrixComponent: подготовим структуру файлов, параметры, кеш и шаблон. Если нужно изменить только внешний вид стандартного компонента, достаточно скопировать его шаблон — этот вариант разобран отдельно.

Структура компонента в /local/components/

Свои компоненты размещай в /local/components/. Первая папка задаёт пространство имён, вторая — название. Например, путь mysite/news.latest/ соответствует имени mysite:news.latest.

Системные компоненты в /bitrix/components/ не редактируй: обновление может заменить их файлы.

/local/components/mysite/news.latest/
├── .description.php        # название и место в списке компонентов
├── .parameters.php         # настройки компонента в визуальном редакторе
├── class.php               # логика: получение данных
└── templates/
    └── .default/
        ├── template.php    # вывод
        └── style.css       # стили шаблона, подключаются сами

Каждый PHP-файл компонента начинается с одной и той же проверки. Она не даёт открыть файл напрямую по ссылке в обход ядра:

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

Описание компонента в .description.php

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

$arComponentDescription = [
    'NAME' => 'Последние новости',
    'DESCRIPTION' => 'Выводит несколько последних элементов инфоблока',
    'PATH' => [
        'ID' => 'mysite',
        'NAME' => 'Мой сайт',
    ],
    'CACHE_PATH' => 'Y',
];

PATH задаёт раздел в списке компонентов визуального редактора: компонент появится в группе «Мой сайт». CACHE_PATH добавляет в режиме правки кнопку сброса кеша компонента. В готовых решениях названия выносят в языковые файлы папки lang, здесь для краткости они написаны прямо в коде.

Параметры компонента в .parameters.php

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

$arComponentParameters = [
    'PARAMETERS' => [
        'IBLOCK_ID' => [
            'PARENT' => 'BASE',
            'NAME' => 'ID инфоблока',
            'TYPE' => 'STRING',
            'DEFAULT' => '',
        ],
        'COUNT' => [
            'PARENT' => 'BASE',
            'NAME' => 'Количество новостей',
            'TYPE' => 'STRING',
            'DEFAULT' => '3',
        ],
        'CACHE_TIME' => ['DEFAULT' => 3600],
    ],
];

Файл .parameters.php описывает форму настройки в визуальном редакторе. При выполнении компонент получает параметры из вызова на странице, поэтому проверять и нормализовать их нужно в классе.

BASE задаёт группу «Основные параметры». Для CACHE_TIME Битрикс выводит настройки кеширования.

Класс CBitrixComponent: выборка и кеширование

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

use Bitrix\Main\Loader;

class MysiteNewsLatestComponent extends CBitrixComponent
{
    public function onPrepareComponentParams($arParams)
    {
        $arParams['IBLOCK_ID'] = (int)($arParams['IBLOCK_ID'] ?? 0);
        $arParams['COUNT'] = max(1, (int)($arParams['COUNT'] ?? 3));
        $arParams['CACHE_TIME'] = (int)($arParams['CACHE_TIME'] ?? 3600);

        return $arParams;
    }

    public function executeComponent()
    {
        if ($this->arParams['IBLOCK_ID'] <= 0) {
            ShowError('Не указан ID инфоблока');
            return;
        }

        if ($this->startResultCache()) {
            if (!Loader::includeModule('iblock')) {
                $this->abortResultCache();
                ShowError('Модуль «Информационные блоки» не установлен');
                return;
            }

            $this->arResult['ITEMS'] = [];

            $elements = CIBlockElement::GetList(
                ['ACTIVE_FROM' => 'DESC', 'SORT' => 'ASC'],
                [
                    'IBLOCK_ID' => $this->arParams['IBLOCK_ID'],
                    'ACTIVE' => 'Y',
                    'ACTIVE_DATE' => 'Y',
                ],
                false,
                ['nTopCount' => $this->arParams['COUNT']],
                ['ID', 'IBLOCK_ID', 'NAME', 'DATE_ACTIVE_FROM', 'DETAIL_PAGE_URL']
            );

            while ($item = $elements->GetNext()) {
                $this->arResult['ITEMS'][] = $item;
            }

            $this->includeComponentTemplate();
        }
    }
}

onPrepareComponentParams() вызывается до выполнения. Здесь параметры приводятся к нужным типам и получают значения по умолчанию. ID и количество превращаются в числа, поэтому в запрос не попадёт строка из адреса или настроек.
executeComponent() — точка входа. Если он есть в классе, отдельный component.php не нужен. Внутри работают с $this->arParams и $this->arResult, а не с глобальными переменными.
startResultCache() проверяет кеш. Если он есть, Битрикс сам выводит сохранённый HTML, и метод возвращает false. Если нет — код внутри условия выполняется, а результат шаблона сохраняется в кеш. Время жизни берётся из CACHE_TIME.
abortResultCache() отменяет сохранение, если что-то пошло не так. Иначе в кеш попадёт ошибка и будет показываться весь час.
При выборке элементов инфоблока внутри кеша компонента Битрикс сам регистрирует тег инфоблока. Поэтому при добавлении или изменении новости кеш сбрасывается, если на сайте включено управляемое кеширование.

Вывод результата в template.php

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

/** @var array $arResult */

if (empty($arResult['ITEMS'])) {
    return;
}
?>
<ul class="news-latest">
    <?php foreach ($arResult['ITEMS'] as $item): ?>
        <li class="news-latest__item">
            <a href="<?= $item['DETAIL_PAGE_URL'] ?>"><?= $item['NAME'] ?></a>
            <?php if ($item['DATE_ACTIVE_FROM']): ?>
                <span class="news-latest__date"><?= $item['DATE_ACTIVE_FROM'] ?></span>
            <?php endif; ?>
        </li>
    <?php endforeach; ?>
</ul>

GetNext() уже экранирует значения полей: в NAME кавычки и угловые скобки заменены на HTML-сущности. Исходные значения лежат в ключах с тильдой: ~NAME. Если выводишь их, экранируй сам через htmlspecialcharsbx().
DETAIL_PAGE_URL строится по шаблону адреса из настроек инфоблока. Для этого в выборке нужен IBLOCK_ID.
Кроме $arResult, в шаблоне доступны $arParams, $templateFolder — путь к папке шаблона — и $component.

Подключение через IncludeComponent()

<?php
$APPLICATION->IncludeComponent(
    'mysite:news.latest',
    '',
    [
        'IBLOCK_ID' => 1,
        'COUNT' => 3,
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => 3600,
    ]
);
?>

Второй аргумент IncludeComponent() — имя шаблона. Пустая строка выбирает .default. Компонент также можно добавить через визуальный редактор из группы «Мой сайт».

Параметр CACHE_TYPE управляет кешем: A учитывает настройки автокеширования, Y включает кеширование, N отключает.

Свой шаблон для готового компонента

Часто новый компонент не нужен: хватает стандартного, например bitrix:news.list, с другим шаблоном. Битрикс ищет шаблон компонента в таком порядке:

/local/templates/<шаблон сайта>/components/<пространство имён>/<компонент>/<шаблон>/
/local/templates/.default/components/…
/bitrix/templates/<шаблон сайта>/components/… и /bitrix/templates/.default/components/…
папка templates самого компонента.

Скопируй системный шаблон, например в /local/templates/.default/components/bitrix/news.list/my/, и укажи 'my' вторым аргументом IncludeComponent().

Для подготовки дополнительных данных создай рядом result_modifier.php. Он выполняется перед шаблоном при формировании результата. При включённом кеше не рассчитывай, что этот код будет запускаться на каждом просмотре.

Почему компонент не отображается или не обновляется

Компонента нет в списке редактора — проверь путь /local/components/пространство/имя/ и .description.php.
Изменения в коде не видны — это кеш. Сбрось его кнопкой в режиме правки или временно поставь 'CACHE_TYPE' => 'N'.
Вместо блока ошибка — включи журнал ошибок, как описано в статье об ошибках Битрикса.