CMain::IncludeComponent: универсальный «швейцарский нож» 1С-Битрикс

Компоненты — основа подхода «взял-вставил» в Bitrix Framework.

Метод CMain::IncludeComponent() позволяет «с одного выстрела» подключить, отрисовать и при желании вернуть результат любого компонента 2.0. Ниже — исчерпывающее руководство с практическими примерами и советами, накопленными в боевых проектах.

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

mixed CMain::IncludeComponent(
    string $componentName,
    string $componentTemplate = "",
    array  $arParams = [],
    CBitrixComponent $parentComponent = null,
    array  $arFunctionParams = [],
    bool   $returnResult = false
);

Возвращает string|array|null: сгенерированный HTML либо arResult, если запрошено.

Базовое подключение

Самый короткий путь:

<?php
$APPLICATION->IncludeComponent("bitrix:catalog", "", [
    "IBLOCK_TYPE_ID" => "catalog",
    "SEF_MODE" => "N",
    "ACTION_VARIABLE" => "action",
    "BASKET_PAGE_TEMPLATE" => "/personal/basket.php",
    "CACHE_TIME" => 86400,
]);
?>

Шаблон по умолчанию .default будет взят из директории компонента или темы сайта.

Собственный шаблон

$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "tile", // ./bitrix/templates/<site>/components/bitrix/news.list/tile/
    [
        "IBLOCK_ID" => 7,
        "NEWS_COUNT" => 12,
        "SET_TITLE" => "N",
        "CACHE_TYPE" => "A",
    ]
);

Шаблон tile можно хранить как в шаблоне сайта, так и в компоненте-модуле.

Передаём параметры динамически

$pageSize = (int)($_GET['per_page'] ?? 20);
$APPLICATION->IncludeComponent(
    "bitrix:forum.topic.list",
    "",
    [
        "FID" => 3,
        "TOPICS_PER_PAGE" => $pageSize,
        "SET_TITLE" => "N",
    ]
);

AJAX-компонент «из коробки»

Больше магии — меньше JS ручками.

$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "infinite-scroll",
    [
        "IBLOCK_ID" => 5,
        "NEWS_COUNT" => 6,
        "AJAX_MODE" => "Y", // ⚡
        "AJAX_OPTION_JUMP" => "N",
        "AJAX_OPTION_HISTORY" => "N",
    ]
);

Bitrix сам сформирует bxajaxid, обработает POST и перерисует only нужный фрагмент.

Скрываем иконки конструктора

$APPLICATION->IncludeComponent(
    "bitrix:catalog.section",
    "",
    [ /* … */ ],
    null,
    ["HIDE_ICONS" => "Y"]
);

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

Получаем arResult без вывода

Иногда нужно переиспользовать данные компонента:

$arResult = $APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "",
    [
        "IBLOCK_ID" => 2,
        "NEWS_COUNT" => 5,
        "SET_TITLE" => "N",
    ],
    null,
    [],
    true // ← вернуть, а не echo
);
// выводим в другом месте:
foreach ($arResult["ITEMS"] as $item) {
    echo "<li>{$item['NAME']}</li>";
}

Вложенный компонент

В шаблоне комплексного компонента (bitrix:photogallery) подключаем детальную карточку:

$APPLICATION->IncludeComponent(
    "bitrix:photo.detail",
    "",
    [
        "IBLOCK_TYPE" => $arParams["IBLOCK_TYPE"],
        "IBLOCK_ID" => $arParams["IBLOCK_ID"],
        "ELEMENT_ID" => $arResult["VARIABLES"]["ELEMENT_ID"],
    ],
    $component // ← ссылка на «родителя»
);

Это гарантирует корректную работу навигации и кэша.

Выбор шаблона на лету

$template = SITE_TEMPLATE_ID === 'dark' ? 'dark-cards' : 'light-cards';
$APPLICATION->IncludeComponent(
    "bitrix:catalog.section.list",
    $template,
    [ "IBLOCK_ID" => 10 ]
);

Отключаем компонент по условию

if ($USER->IsAuthorized()) {
    $APPLICATION->IncludeComponent(/* … */);
} else {
    // гостям выводим плейсхолдер
    echo "<p>Пожалуйста, войдите для просмотра каталога.</p>";
}

Альтернативно — флаг ACTIVE_COMPONENT ⇒ "N", но условие удобнее читается.

Пример SPA-перезагрузки через bx.reload()

HTML-кнопка вызывает AJAX-загрузку блока:

<div id="fav-block">
<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.line",
    "favorites",
    [
        "CACHE_TIME" => 3600,
        "NEWS_COUNT" => 3,
        "FILTER_NAME" => "arrFavFilter",
        "AJAX_MODE" => "Y",
        "AJAX_OPTION_ADDITIONAL" => "fav-block",
    ]
);
?>
</div>
<button onclick="BX.ajax.insertToNode('?update=Y', BX('fav-block'));">
    Обновить избранное
</button>

Создаём собственный компонент и подключаем

1. local/components/my/blog.comments/component.php
2. templates/.default/template.php
3. Подключаем:

$APPLICATION->IncludeComponent(
    "my:blog.comments",
    "",
    [
        "POST_ID" => $postId,
        "CACHE_TYPE" => "A",
    ]
);

Часто встречающиеся ошибки

Итоги

IncludeComponent() — фундаментальный инструмент, который:

1. Изолирует бизнес-логику в переиспользуемых блоках.
2. Экономит время с помощью готовых AJAX-, кэширующих и правильных SEO-механизмов.
3. Позволяет гибко управлять выводом: скрывать иконки, вкладывать друг в друга, работать как «функция данных».

Освойте приёмы из примеров — и ваши проекты на 1С-Битрикс станут чище, быстрее и удобнее в поддержке.