LETUNOFF DOCS

Битрикс. Вызов компонентов через IncludeComponent()

🧱 Суть

Метод $APPLICATION->IncludeComponent() используется для подключения компонентов на страницу.

Именно через него Битрикс:

  • запускает компонент;
  • передаёт ему параметры;
  • получает данные;
  • подключает шаблон;
  • выводит готовый HTML.

Практически любая динамическая страница Битрикса содержит один или несколько вызовов IncludeComponent().

📦 Проблема

Без компонентов разработчику пришлось бы вручную:

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

Это приводит к большому количеству повторяющегося кода.

✅ Решение

Использовать IncludeComponent(), который инкапсулирует всю работу компонента и позволяет гибко управлять его поведением через параметры.

💻 Код

Базовый синтаксис

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

Метод принимает несколько аргументов, определяющих работу компонента.

Сигнатура метода

Полная форма выглядит так:

<?php
$APPLICATION->IncludeComponent(
    $componentName,
    $templateName,
    $params,
    $parentComponent = null,
    $functionParams = []
);
?>

На практике чаще всего используются первые три аргумента.

Первый аргумент – имя компонента

Определяет, какой компонент будет выполнен.

Например:

"bitrix:news.list"

или собственный компонент:

"company:weather"

Формат имени:

пространство:компонент

Второй аргумент – шаблон

Позволяет выбрать шаблон отображения компонента.

Стандартный шаблон:

""

или

".default"

Подключение собственного шаблона:

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

В этом случае будет использован шаблон:

templates/cards/

Третий аргумент – параметры

Через массив передаются настройки компонента.

Например:

<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "",
    [
        "IBLOCK_ID" => 5,
        "NEWS_COUNT" => 10,
        "SORT_BY1" => "ACTIVE_FROM",
        "SORT_ORDER1" => "DESC",
    ]
);
?>

Параметры становятся доступны внутри компонента через массив:

$arParams

Родительский компонент

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

Например:

$APPLICATION->IncludeComponent(
    "company:child",
    "",
    [],
    $component
);

Это позволяет объединять компоненты и корректно работать с кешированием.
В большинстве случаев этот аргумент не требуется.

Дополнительные параметры

Последний аргумент содержит служебные настройки.

Например:

[
    "HIDE_ICONS" => "Y"
]

Они используются реже и относятся к особенностям работы компонентов.

Последовательность выполнения

После вызова метода происходит следующая цепочка:

IncludeComponent()
        │
        ▼
Получение параметров
        │
        ▼
Запуск component.php
        │
        ▼
Получение данных
        │
        ▼
Заполнение $arResult
        │
        ▼
Подключение template.php
        │
        ▼
Вывод HTML

Пример подключения списка новостей

<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "",
    [
        "IBLOCK_ID" => 5,
        "NEWS_COUNT" => 5,
        "CACHE_TYPE" => "A",
        "CACHE_TIME" => 3600,
    ]
);
?>

Компонент:

  • получит данные из инфоблока;
  • закеширует результат;
  • выведет список новостей.

Несколько компонентов на странице

На одной странице можно вызывать несколько компонентов.

Например:

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

Каждый из них работает независимо.

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

Передавать параметры неверного типа

Плохо:

[
    "NEWS_COUNT" => true
]

Лучше:

[
    "NEWS_COUNT" => 10
]

Типы параметров должны соответствовать документации компонента.

Изменять стандартный компонент

Не рекомендуется редактировать файлы:

/bitrix/components/

Лучше:

  • создать собственный шаблон;
  • либо собственный компонент в /local/components.

Выполнять сложную логику в шаблоне

Шаблон должен только отображать данные.
Получение данных и бизнес-логика должны находиться в компоненте.

Не использовать кеширование

Если компонент часто обращается к базе данных, стоит настроить параметры:

"CACHE_TYPE"
"CACHE_TIME"

Это значительно снижает нагрузку на сервер.

Жёстко прописывать значения

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

🎯 Вывод

  • IncludeComponent() – основной способ подключения компонентов в Битриксе
  • Через него запускается весь жизненный цикл компонента
  • Первые три аргумента определяют компонент, шаблон и параметры
  • Компонент получает настройки через $arParams, а шаблон выводит данные из $arResult
  • Один и тот же компонент можно использовать с разными шаблонами и параметрами
  • Правильное использование IncludeComponent() делает код гибким и переиспользуемым

🔗 Связано

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