Составные компоненты и маршрутизация в Битрикс

За один проход соберём страницу каталога на 1С-Битрикс: URL /catalog/15/ будет попадать в нужный файл, родительский компонент получит идентификатор раздела, а дочерний выведет его содержимое. На рабочем сайте это обычно занимает 30–60 минут, если у вас уже есть доступ к файлам и права на изменение настроек продукта.

Что подготовить до начала

Примеры рассчитаны на классическую модель компонентов 1С-Битрикс: Управление сайтом, используемую в ветках ядра 23.x и новее. Перед внедрением проверьте версию в административной панели: в старых проектах могут отличаться шаблоны, структура компонентов и правила веб-сервера.

• доступ к каталогу проекта и папке /local/;
• права на изменение файла маршрутов /urlrewrite.php либо доступ к настройке ЧПУ в административной панели;
• рабочий сайт с подключёнными header.php и footer.php;
• родительский компонент и дочерний компонент с понятными именами;
• резервная копия файлов перед изменением маршрутов.

Составной компонент — это компонент-контейнер, который получает общие параметры и подключает один или несколько дочерних компонентов. Сноска: ЧПУ — человекопонятный URL, например /catalog/15/, а не адрес с параметрами вроде index.php?SECTION_ID=15.

Шаг 1. Разложите ответственность по слоям

Не заставляйте один файл одновременно разбирать URL, получать данные из инфоблока и рисовать HTML. Минимальная схема выглядит так:

• /catalog/index.php принимает запрос и подключает страницу;
• local/components/acme/catalog собирает данные верхнего уровня;
• local/components/acme/catalog.section выводит дочерний список;
• шаблоны компонентов отвечают только за разметку.

Такой разрез упрощает замену шаблона и позволяет повторно использовать дочерний компонент на другой странице. Проверка: вы можете назвать файл, где создаётся маршрут, файл, где собирается результат, и файл, где выводится HTML.

Шаг 2. Создайте родительский компонент

Создайте каталог /local/components/acme/catalog/ и разместите в нём файлы .description.php, .parameters.php, component.php и папку templates/.default/.

Файл .description.php нужен редактору компонентов:

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

$arComponentDescription = [
    'NAME' => 'Каталог',
    'DESCRIPTION' => 'Составной компонент каталога',
    'PATH' => [
        'ID' => 'acme',
        'NAME' => 'ACME',
    ],
];

Параметр родительского компонента объявите в .parameters.php. В реальном каталоге сюда обычно добавляют идентификатор инфоблока, шаблон URL и режимы сортировки.

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

$arComponentParameters = [
    'GROUPS' => [],
    'PARAMETERS' => [
        'SECTION_ID' => [
            'PARENT' => 'BASE',
            'NAME' => 'Идентификатор раздела',
            'TYPE' => 'STRING',
            'DEFAULT' => '0',
        ],
    ],
];

Проверка: компонент появился в визуальном редакторе и принимает параметр SECTION_ID. Если он не виден, очистите кеш списка компонентов и проверьте, что каталог находится именно в /local/components/.

Шаг 3. Передайте данные дочернему компоненту

В component.php родителя нормализуйте входной идентификатор и подключите шаблон. Здесь не должно быть HTML.

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

$sectionId = (int)($arParams['SECTION_ID'] ?? 0);

$arResult = [
    'SECTION_ID' => $sectionId,
];

$this->includeComponentTemplate();

Теперь создайте templates/.default/template.php:

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

$APPLICATION->IncludeComponent(
    'acme:catalog.section',
    '',
    [
        'SECTION_ID' => $arResult['SECTION_ID'],
    ],
    $component,
    ['HIDE_ICONS' => 'Y']
);

Родительский компонент не должен передавать дочернему весь массив запроса. Передавайте только параметры, которые действительно нужны. Так меньше риск случайно использовать непроверенное значение из URL. Проверка: при открытии шаблона родителя вызывается acme:catalog.section, а в его параметрах есть число раздела.

Маршрутизация должна сообщать компоненту, что запросили. Она не должна решать, как компонент рисует страницу.

Шаг 4. Подключите дочерний компонент

Дочерний компонент может получить данные из инфоблока, ORM или внешнего сервиса. В этом примере оставим место для вашей выборки и покажем безопасную границу между данными и шаблоном.

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

$sectionId = (int)($arParams['SECTION_ID'] ?? 0);
$arResult['ITEMS'] = [];

if ($sectionId > 0) {
    // Здесь размещается конкретная выборка элементов раздела.
    // Результат передаётся в шаблон через $arResult.
}

$this->includeComponentTemplate();

Шаблон local/components/acme/catalog.section/templates/.default/template.php отвечает за вывод:

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

foreach ($arResult['ITEMS'] as $item) {
    echo '<article>';
    echo htmlspecialcharsbx((string)$item['NAME']);
    echo '</article>';
}

В рабочей выборке замените пустой массив на запрос к конкретному источнику данных и убедитесь, что поле NAME экранируется перед выводом. Проверка: при временной передаче тестового элемента в $arResult['ITEMS'] браузер показывает его название без выполнения HTML из значения.

Шаг 5. Свяжите ЧПУ с входным параметром

Создайте страницу /catalog/index.php:

<?php
require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');

$APPLICATION->IncludeComponent(
    'acme:catalog',
    '',
    [
        'SECTION_ID' => (int)($_GET['SECTION_ID'] ?? 0),
    ]
);

require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php');

Затем добавьте правило в /urlrewrite.php. Формат ниже соответствует стандартному массиву правил ЧПУ Битрикс:

[
    'CONDITION' => '#^/catalog/([0-9]+)/?$#',
    'RULE' => 'SECTION_ID=$1',
    'ID' => '',
    'PATH' => '/catalog/index.php',
],

Группа ([0-9]+) разрешает только числовой идентификатор и передаёт его в SECTION_ID. Если маршрут добавляете через административную панель, проверьте, что итоговая запись в файле имеет те же поля. Проверка: запрос /catalog/15/ открывает страницу без редиректа на URL с параметром, а в компонент приходит значение 15.

Что часто ломается

• Открывается 404. Проверьте, включено ли ЧПУ, существует ли /catalog/index.php и не перекрывает ли правило более общий маршрут.
• В компонент приходит ноль. Сверьте имя параметра в полях RULE, в $_GET и в массиве параметров родителя. SECTION_ID и section_id — разные ключи.
• Всегда показывается один и тот же раздел. Ищите жёстко заданный идентификатор в настройках компонента или кешированный результат. После изменения параметров очистите кеш компонента.
• Появляется ошибка о неизвестном компоненте. Проверьте имя пространства и каталог: для вызова acme:catalog.section нужен путь /local/components/acme/catalog.section/.
• Вёрстка дублируется. Не подключайте дочерний компонент одновременно в component.php и в его шаблоне. Вызов должен находиться в одном месте.

Проверка перед публикацией

1. Откройте URL с существующим числовым идентификатором. Должен загрузиться нужный раздел.
2. Откройте URL со строкой вместо числа. Правило не должно подставлять её в параметр.
3. Проверьте несуществующий идентификатор. Компонент должен показать пустой результат или штатную страницу ошибки, а не данные другого раздела.
4. Очистите кеш и повторите три проверки. Результат не должен зависеть от того, кто первым открыл страницу.
5. Проверьте несколько уровней URL, если в проекте есть другие правила. Битрикс обрабатывает их в порядке записей, поэтому широкое регулярное выражение может перехватить запрос раньше нужного.

Что делать дальше

После базовой связки добавьте в дочерний компонент постраничную навигацию, проверку доступности раздела и отдельный шаблон для пустого результата. Инвалидацию кеша, SEO-шаблоны и маршруты с несколькими уровнями вложенности лучше разбирать отдельно: они меняют правила выборки и порядок обработки URL.

На рабочем сайте смотрите три показателя: долю 404 для новых маршрутов, время ответа страницы и количество запросов к базе данных. Если страница медленная, сначала измерьте выборку дочернего компонента, а не переносите логику в роутер.