Кастомизация типовых компонентов

Главное правило кастомизации в Битрикс — не редактировать файлы в /bitrix/components/. Любая правка ядра будет затёрта при обновлении. Разберём легальные слои переопределения: от копии шаблона до собственного класса компонента в /local/.

Уровни кастомизации

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

Копирование шаблона компонента

Самый частый сценарий — своя вёрстка. В визуальном редакторе есть кнопка «Копировать шаблон», которая создаёт копию в шаблоне сайта. Тот же результат даёт программный вызов:

CBitrixComponent::includeComponentTemplate() — вызывается автоматически,
а копию создаёт метод:
$obTemplate->CopyTemplateFiles();

Структурно копия ложится по пути:

/local/templates/<шаблон_сайта>/components/bitrix/news.list/<мой_шаблон>/template.php

В вызове компонента шаблон указывается шестым параметром:

$APPLICATION->IncludeComponent(
  'bitrix:news.list',
  'my_template', // имя вашего шаблона
  [ /* параметры */ ]
);

Так вы полностью контролируете HTML, но при этом наследуете логику типового компонента и получаете его обновления.

Внутри скопированного шаблона доступны все переменные вывода: $arResult, $arParams, объект $this и вспомогательные методы вроде $this->GetFolder() для путей к ассетам шаблона. Стили и скрипты кладут рядом в style.css и script.js — ядро подключает их автоматически при рендере шаблона. Это удобно: вся вёрстка компонента вместе с оформлением живёт в одной папке и переносится между проектами целиком.

.default и приоритет /local над /bitrix

Битрикс ищет файлы по цепочке приоритетов. Каталог /local/ всегда важнее /bitrix/, поэтому именно туда кладут все кастомизации.

Порядок поиска шаблона компонента:

1. /local/templates/<шаблон>/components/...
2. /bitrix/templates/<шаблон>/components/...
3. /local/components/.../templates/...
4. /bitrix/components/.../templates/...

Шаблон с именем .default — это стандартный шаблон компонента «из коробки». Его не переименовывают: вместо этого делают копию под своим именем. Если вызвать компонент с шаблоном .default, но положить свою копию в /local/templates/.../components/, она перекроет оригинал без изменения имени вызова.

result_modifier.php для данных

Когда данных в $arResult не хватает или их нужно преобразовать, не засоряйте template.php запросами к БД. Для этого есть result_modifier.php — он выполняется перед шаблоном и его результат кэшируется вместе с шаблоном.

<?php // result_modifier.php
foreach ($arResult['ITEMS'] as &$item) {
  $item['PRICE_FORMATTED'] =
    number_format($item['PROPERTIES']['PRICE']['VALUE'], 0, '', ' ') . ' ₽';
}
unset($item);
?>

Когда копируют весь компонент

Если нужно изменить саму логику — состав выборки, обработку параметров, кэш-ключи, — копируют компонент целиком в /local/components/ под собственным пространством имён (не bitrix):

/local/components/vendor/news.list/component.php
/local/components/vendor/news.list/.parameters.php
/local/components/vendor/news.list/.description.php
/local/components/vendor/news.list/templates/.default/template.php

Вызывается такой компонент уже под своим именем: $APPLICATION->IncludeComponent('vendor:news.list', ...). Минус в том, что вы теряете обновления типового компонента, поэтому этот путь оправдан только для существенных изменений логики. Перед копированием честно оцените, нельзя ли добиться цели обработчиками событий инфоблоков или result_modifier — это дешевле в поддержке и не отвязывает от обновлений платформы.

• наследование от \CBitrixComponent позволяет переопределить лишь нужные методы;
• для комплексных компонентов копируют и component.php, и файлы страниц из папки шаблона.

Чего делать нельзя

Несколько антипаттернов, которые ломают проекты при первом же обновлении платформы:

• Править файлы в /bitrix/components/bitrix/ — обновление вернёт оригинал;
• Переименовывать .default вместо создания копии;
• Класть кастомные компоненты в пространство bitrix: — конфликт при апдейте;
• Держать бизнес-логику в template.php — она не переиспользуется и попадает в кэш непредсказуемо.

Итог

Кастомизация в Битрикс — это дисциплина слоёв: вёрстку меняют копией шаблона, данные — через result_modifier.php, динамику мимо кэша — в component_epilog.php, а логику — копией компонента в /local/. Всё, что лежит в /bitrix/, считайте неприкосновенным.

Мы в B2Bsite выстраиваем кастомизации так, чтобы проект спокойно проходил обновления ядра и маркетплейс-решений: правки живут в /local/, логика отделена от вёрстки, а кэш не хранит чужих данных.