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

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

Комплексный компонент — это компонент, который управляет набором дочерних компонентов, определяет их состав в зависимости от URL и точки монтирования на странице. Именно комплексные компоненты реализуют разделы каталога, блога, личного кабинета — когда на одном URL может быть список, на другом — детальная страница, на третьем — форма оформления. Без понимания механики комплексных компонентов невозможно правильно реализовать многостраничный функционал на Битрикс.

Чем комплексный компонент отличается от обычного

Обычный компонент (bitrix:news.detail) — выводит один конкретный блок. Комплексный (bitrix:news) — точка монтирования раздела. Он сам решает, какой дочерний компонент вызвать: если URL /news/ — список новостей, если /news/title-novosti/ — детальная страница.

Комплексный компонент связывает URL с дочерними компонентами через механизм SEF-URL (Search Engine Friendly) и файл page_templates.php.

Структура комплексного компонента

/local/components/custom/my.section/
├── .description.php
├── .parameters.php
├── component.php              # диспетчер: определяет тип страницы
├── page_templates.php         # маппинг URL-шаблонов на дочерние компоненты
├── templates/
│   └── .default/
│       ├── template.php       # шаблон обёртки (заголовок, навигация)
│       └── page_templates/    # шаблоны дочерних компонентов
│           ├── list.php
│           └── detail.php

page_templates.php: маппинг URL

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

$arSefTemplates = [
    // список
    'list'   => '',
    // детальная страница
    'detail' => '#ELEMENT_CODE#/',
    // раздел
    'section' => '#SECTION_CODE#/',
    // поиск
    'search' => 'search/',
];

Битрикс сопоставляет текущий URL с этими шаблонами и определяет тип страницы ($arCurrentValues['PAGE_ELEMENT_TYPE']).

component.php комплексного компонента: диспетчер

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

/** @var CBitrixComponent $this */

// Инициализация SEF
$this->setFrameMode(true);

if ($arParams['SEF_MODE'] === 'Y') {
    $arSEFUrlTemplates = [];
    $arDefaultSEFUrlTemplates = [
        'list'   => '',
        'detail' => '#ELEMENT_CODE#/',
        'section' => '#SECTION_CODE#/',
    ];
    // ... парсинг текущего URL

    // Определяем тип страницы
    $page = 'list'; // default

    if (isset($arVariables['ELEMENT_CODE']) && $arVariables['ELEMENT_CODE']) {
        $page = 'detail';
    } elseif (isset($arVariables['SECTION_CODE']) && $arVariables['SECTION_CODE']) {
        $page = 'section';
    }
} else {
    // Параметрный режим (не SEF)
    $page = $arParams['PAGE_ELEMENT_TYPE'];
}

// Подключаем нужный шаблон страницы
$this->includePageTemplate($page);

Дочерние компоненты в шаблоне

Файл templates/.default/page_templates/list.php вызывает дочерний компонент списка:

<?php
// templates/.default/page_templates/list.php
$APPLICATION->IncludeComponent('custom:my.section.list', '', [
    'IBLOCK_ID'     => $arParams['IBLOCK_ID'],
    'SECTION_ID'    => $arResult['VARIABLES']['SECTION_ID'] ?? 0,
    'SECTION_CODE'  => $arResult['VARIABLES']['SECTION_CODE'] ?? '',
    'PAGE_SIZE'     => $arParams['PAGE_SIZE'],
    'CACHE_TIME'    => $arParams['CACHE_TIME'],
    'SET_TITLE'     => 'Y',
    'SET_BROWSER_TITLE' => 'Y',
], $component);

Параметр $component (ссылка на родительский компонент) — критичен. Без него кеш дочернего компонента будет независимым от родительского, что нарушает инвалидацию.

Параметры комплексного компонента

Комплексный компонент объединяет параметры всех дочерних — настройки пагинации, кеширования, SEF-шаблонов:

// .parameters.php
$arComponentParameters = [
    'GROUPS' => [...],
    'PARAMETERS' => [
        'SEF_MODE' => [
            'NAME'    => 'Режим ЧПУ',
            'TYPE'    => 'CHECKBOX',
            'DEFAULT' => 'Y',
        ],
        'SEF_FOLDER' => [
            'NAME'    => 'Папка для ЧПУ',
            'TYPE'    => 'STRING',
            'DEFAULT' => '/news/',
        ],
        'IBLOCK_ID' => ['...'],
        'PAGE_SIZE' => [
            'NAME'    => 'Элементов на странице',
            'TYPE'    => 'STRING',
            'DEFAULT' => '12',
        ],
        'DETAIL_URL'  => ['DEFAULT' => '#SITE_DIR##SECTION_CODE#/#ELEMENT_CODE#/'],
        'SECTION_URL' => ['DEFAULT' => '#SITE_DIR##SECTION_CODE#/'],
        'INDEX_URL'   => ['DEFAULT' => '#SITE_DIR#'],
        // ... SEF-шаблоны URL
    ],
];

Обработка ошибок и 404

Если элемент или раздел не найден, комплексный компонент должен отдавать корректный 404:

// В дочернем компоненте detail
if (!$element) {
    LocalRedirect(SITE_DIR . '404.php');
    // или:
    \Bitrix\Main\Response\HttpResponse::create()->setStatus('404 Not Found')->send();
    require(Application::getDocumentRoot() . '/404.php');
    die();
}

Права доступа в комплексных компонентах

Если раздел требует авторизации (личный кабинет, B2B), комплексный компонент проверяет права до вызова дочерних:

// В component.php
global $USER;
if (!$USER->IsAuthorized()) {
    LocalRedirect(SITE_DIR . 'login/?backurl=' . urlencode($APPLICATION->GetCurPage()));
    die();
}
// Проверка группы пользователя
if (!$USER->IsInGroup($arParams['ALLOWED_GROUP_ID'])) {
    $APPLICATION->SetStatus('403 Forbidden');
    $APPLICATION->RestartBuffer();
    require($_SERVER['DOCUMENT_ROOT'] . '/403.php');
    die();
}

Кеширование в комплексных компонентах

Комплексный компонент сам по себе кешируется редко (диспетчерская логика дешёвая). Кешируются дочерние. Важно, что кеш-ключ дочернего компонента включает переменные из URL (ELEMENT_CODE, SECTION_CODE), иначе все страницы будут показывать одинаковый кешированный ответ.

В классе дочернего компонента:

$cacheId = serialize([
    $arParams['IBLOCK_ID'],
    $arParams['ELEMENT_CODE'],
    $USER->GetGroups(), // разные группы видят разный контент
    LANGUAGE_ID,
]);
if ($this->StartResultCache($arParams['CACHE_TIME'], $cacheId)) {
    // ...
}

Тестирование комплексного компонента

Перед сдачей — проверочный список:

• Все страницы (list, detail, section) работают в SEF и параметрном режиме
• 404 отдаётся при несуществующем элементе/разделе
• Кеш инвалидируется при обновлении элемента в админке
• Компонент работает на всех сайтах мультисайтовой установки
• Хлебные крошки корректно отображаются на всех типах страниц

Сроки

Комплексный компонент — правильная архитектура для любого раздела сайта с несколькими типами страниц. Это не перестраховка, а обязательное условие для сайтов, которые планируют поддерживать и развивать.