Разработка компонента 1С-Битрикс

Разработка компонента 1С-Битрикс

Стандартная библиотека компонентов Битрикс покрывает 80% типовых задач, но когда проект выходит за пределы шаблонного функционала — нужен собственный компонент. Задача разработчика: не просто написать PHP-код, который работает, а создать компонент по правилам платформы — с поддержкой кеширования, параметров, событий, мультисайтовости и возможностью обновления шаблона без изменения логики.

Анатомия компонента Битрикс

Компонент располагается в /local/components/{namespace}/{component.name}/ или /bitrix/components/. Обязательная структура:

/local/components/custom/my.component/
├── .parameters.php          # описание параметров компонента
├── .description.php         # метаданные: название, категория
├── component.php            # основная логика (бизнес-слой)
└── templates/
    └── .default/
        ├── template.php     # шаблон вывода
        ├── style.css        # стили компонента
        ├── script.js        # клиентская логика
        └── result_modifier.php  # опционально: постобработка $arResult

.description.php — минималистичный файл:

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();
$arComponentDescription = [
    'NAME'        => 'Мой компонент',
    'DESCRIPTION' => 'Описание функционала компонента',
    'ICON'        => '/images/icon.gif',
    'CACHE_PATH'  => 'Y',
    'SORT'        => 20,
];

component.php: правила написания бизнес-логики

component.php — не просто скрипт, а файл, который выполняется в контексте объекта $this (экземпляр класса компонента). Это даёт доступ к API кеширования, параметрам и дочерним компонентам.

Минимальная структура component.php:

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

/** @var CBitrixComponent $this */

// Подготовка параметров с дефолтами
$arParams = array_merge([
    'IBLOCK_ID'  => 0,
    'CACHE_TIME' => 3600,
    'COUNT'      => 10,
], $arParams);

// Проверка обязательных параметров
if (!(int)$arParams['IBLOCK_ID']) {
    ShowError('Параметр IBLOCK_ID обязателен');
    return;
}

// Кеширование через StartResultCache / EndResultCache
if ($this->StartResultCache($arParams['CACHE_TIME'], false, '/custom/my.component/')) {
    // Выборка данных
    $res = CIBlockElement::GetList(
        ['SORT' => 'ASC'],
        ['IBLOCK_ID' => $arParams['IBLOCK_ID'], 'ACTIVE' => 'Y'],
        false,
        ['nTopCount' => $arParams['COUNT']],
        ['ID', 'NAME', 'PREVIEW_TEXT', 'PREVIEW_PICTURE', 'DETAIL_PAGE_URL']
    );

    $arResult = ['ITEMS' => []];
    while ($el = $res->GetNext()) {
        $arResult['ITEMS'][] = $el;
    }

    $this->arResult = $arResult;
    $this->IncludeComponentTemplate();
    $this->EndResultCache();
}

Вызов $this->StartResultCache() — это не просто кеш HTML. Битрикс кеширует $arResult и повторно вызывает IncludeComponentTemplate() с кешированными данными, не выполняя тело кеша повторно. При изменении данных кеш сбрасывается через BXClearCache(true, '/custom/my.component/').

.parameters.php: описание параметров

Этот файл делает компонент настраиваемым через визуальный редактор Битрикс («Настройки компонента»). Без него компонент работает, но не удобен для нетехнических пользователей.

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

$arIblockList = [];
$res = CIBlock::GetList(['SORT' => 'ASC'], ['ACTIVE' => 'Y', 'SITE_ID' => SITE_ID]);
while ($ib = $res->Fetch()) {
    $arIblockList[$ib['ID']] = '[' . $ib['ID'] . '] ' . $ib['NAME'];
}

$arComponentParameters = [
    'GROUPS' => [
        'DATA'    => ['NAME' => 'Настройки данных'],
        'DISPLAY' => ['NAME' => 'Настройки отображения'],
    ],
    'PARAMETERS' => [
        'IBLOCK_ID' => [
            'PARENT'  => 'DATA',
            'NAME'    => 'Инфоблок',
            'TYPE'    => 'LIST',
            'VALUES'  => $arIblockList,
            'DEFAULT' => '',
        ],
        'COUNT' => [
            'PARENT'  => 'DISPLAY',
            'NAME'    => 'Количество элементов',
            'TYPE'    => 'STRING',
            'DEFAULT' => '10',
        ],
        'CACHE_TIME' => ['DEFAULT' => 3600],
    ],
];

template.php: разделение логики и отображения

В шаблоне — только разметка. Никаких запросов к базе, никакой бизнес-логики:

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

/** @var array $arResult */
/** @var array $arParams */
/** @var CBitrixComponentTemplate $this */
?>
<div class="my-component">
    <?php foreach ($arResult['ITEMS'] as $item): ?>
        <div class="item">
            <a href="<?= htmlspecialchars($item['DETAIL_PAGE_URL']) ?>">
                <?= htmlspecialchars($item['NAME']) ?>
            </a>
        </div>
    <?php endforeach; ?>
</div>

Стили и скрипты компонента подключаются через Asset в template.php:

\Bitrix\Main\Page\Asset::getInstance()->addCss($this->getFolder() . '/style.css');
\Bitrix\Main\Page\Asset::getInstance()->addJs($this->getFolder() . '/script.js');

Класс компонента вместо процедурного кода

Для сложных компонентов — наследование от CBitrixComponent:

<?php
// /local/components/custom/my.component/class.php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die();

class MyComponent extends CBitrixComponent {
    public function onPrepareComponentParams($arParams): array {
        $arParams['IBLOCK_ID'] = (int)($arParams['IBLOCK_ID'] ?? 0);
        $arParams['COUNT']     = max(1, (int)($arParams['COUNT'] ?? 10));
        return $arParams;
    }

    public function executeComponent(): void {
        if ($this->StartResultCache()) {
            $this->arResult = $this->getData();
            $this->IncludeComponentTemplate();
            $this->EndResultCache();
        }
    }

    private function getData(): array {
        // Логика выборки
        return ['ITEMS' => []];
    }
}

Это предпочтительный подход: параметры нормализуются в onPrepareComponentParams, данные получаются в отдельном методе, компонент легко расширять без изменения структуры.

Инвалидация кеша при изменении данных

Кеш компонента нужно сбрасывать при изменении элементов инфоблока, которые он отображает. Иначе после редактирования в админке изменения появятся только после истечения CACHE_TIME:

// В init.php или в обработчике событий инфоблока
AddEventHandler('iblock', 'OnAfterIBlockElementUpdate', function($arFields) {
    if ($arFields['IBLOCK_ID'] == MY_IBLOCK_ID) {
        BXClearCache(true, '/custom/my.component/');
    }
});

Для тегированного кеша (более точная инвалидация) используется \Bitrix\Main\Data\TaggedCache.

Сроки

Компонент, написанный по правилам Битрикс, легко переносить между проектами, перекрывать шаблоны на уровне сайта и кастомизировать без редактирования ядра.