LETUNOFF DOCS

Битрикс. Переопределение шаблонов компонентов

🧱 Суть

Переопределение шаблона компонента – это создание собственной версии шаблона без изменения файлов ядра Битрикса.

Такой подход позволяет:

  • изменить внешний вид компонента;
  • сохранить возможность обновления системы;
  • использовать несколько вариантов отображения одного компонента.

Изменяется только представление, а логика компонента остаётся прежней.

📦 Проблема

Стандартные шаблоны находятся внутри ядра:

/bitrix/components/

Если изменить их напрямую:

  • изменения будут потеряны после обновления Битрикса;
  • станет сложнее сопровождать проект;
  • могут возникнуть конфликты при обновлении.

✅ Решение

Создать собственный шаблон и подключить его через IncludeComponent().

Это безопасный и рекомендуемый способ изменения внешнего вида.

💻 Код

Где находятся стандартные шаблоны

Например:

/bitrix/components/
└── bitrix/
    └── news.list/
        └── templates/
            └── .default/

Эти файлы относятся к ядру и не должны редактироваться.

Где создавать собственный шаблон

Шаблоны сайта располагаются внутри активного шаблона сайта:

/local/templates/
└── my_template/
    └── components/

Именно здесь рекомендуется размещать собственные шаблоны компонентов.

Структура собственного шаблона

Например, для компонента bitrix:news.list:

/local/templates/
└── my_template/
    └── components/
        └── bitrix/
            └── news.list/
                └── cards/
                    ├── template.php
                    ├── style.css
                    ├── script.js
                    └── result_modifier.php

Здесь:

  • bitrix – пространство имён;
  • news.list – компонент;
  • cards – имя шаблона.

Подключение шаблона

Второй аргумент IncludeComponent() определяет используемый шаблон.

Например:

<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "cards",
    []
);
?>

Будет использован шаблон:

templates/cards/

Если указать пустую строку:

""

или

".default"

используется шаблон по умолчанию.

Что можно изменять

В собственном шаблоне обычно изменяют:

  • HTML-разметку;
  • CSS;
  • JavaScript;
  • расположение элементов;
  • классы;
  • подключение дополнительных стилей и скриптов.

При этом логика получения данных остаётся внутри компонента.

Использование нескольких шаблонов

Для одного компонента можно создать несколько вариантов отображения.

Например:

news.list/
├── .default/
├── cards/
├── slider/
└── table/

На разных страницах подключаются разные шаблоны:

"cards"

или

"slider"

Компонент остаётся одним и тем же.

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

Обычно процесс выглядит так:

  1. Найти стандартный шаблон.
  2. Скопировать его в папку шаблона сайта.
  3. Переименовать при необходимости.
  4. Изменить только внешний вид.

Таким образом изменения будут независимы от ядра.

Файлы шаблона

Типичный шаблон содержит:

template.php
style.css
script.js
result_modifier.php
component_epilog.php

Назначение файлов:

  • template.php – вывод HTML;
  • style.css – оформление;
  • script.js – клиентская логика;
  • result_modifier.php – подготовка данных для шаблона;
  • component_epilog.php – код после вывода компонента.

Частые ошибки

Изменять файлы в /bitrix

Плохо:

/bitrix/components/...

После обновления изменения исчезнут.
Лучше использовать собственный шаблон.

Менять бизнес-логику в шаблоне

Плохо:

$result = CIBlockElement::GetList(...);

Шаблон должен только отображать данные.

Использовать один шаблон для всех случаев

Если отображение сильно отличается, лучше создать отдельный шаблон (cards, slider, table), чем усложнять один файл множеством условий.

Не использовать result_modifier.php

Если требуется небольшая подготовка данных перед выводом, лучше выполнить её в result_modifier.php, а не перегружать template.php.

Удалять лишние файлы

Даже если style.css или script.js пока не используются, их наличие упрощает дальнейшее развитие шаблона.

🎯 Вывод

  • Шаблоны компонентов позволяют изменить внешний вид без изменения логики
  • Стандартные шаблоны ядра изменять не рекомендуется
  • Собственные шаблоны создаются внутри шаблона сайта (/local/templates/.../components)
  • Один компонент может иметь несколько шаблонов
  • Переопределение шаблонов делает проект безопасным для обновлений и упрощает поддержку

🔗 Связано

Обратные ссылки