Компонент на странице Битрикс: пошагово и без частых ошибок

За 20 минут вы выведете на странице Битрикса список элементов инфоблока¹ через вызов IncludeComponent, а затем подключите собственный шаблон так, чтобы его не стёрло обновлением платформы. Новички чаще всего спотыкаются не на самом вызове, а на трёх соседних вещах: пустой странице из-за неверного ID, правках не в том файле и кеше, который показывает вчерашний результат.

Что нужно иметь до начала

• «1С-Битрикс: Управление сайтом» с ядром main 20.x или новее и установленным модулем «Информационные блоки». Материал написан для вызова компонентов в этих версиях.
• Права администратора на сайте.
• Доступ к файлам: через раздел «Контент → Структура сайта → Файлы и папки» либо по FTP или SSH. Нужна запись в корень сайта и в папку /local/ (если её нет, создадите на четвёртом шаге).
• Инфоблок хотя бы с одним активным элементом. Если его нет, создайте тестовый тип и инфоблок в разделе «Контент → Инфоблоки».

¹ Инфоблок: хранилище однотипных записей в Битриксе (новости, товары, вакансии). Записи называются элементами, у каждой есть название, текст, свойства и признак активности.

Шаги

1. Создайте тестовую страницу. Положите в корень сайта папку test-news, а в неё файл index.php. Расширение .php обязательно: в .html код выполняться не будет. Почему так: компонент вызывается методом объекта $APPLICATION, а он появляется только после подключения header.php.

   <?php
   require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');
   $APPLICATION->SetTitle('Тест компонента');
   
   require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php');
   

   Проверка: по адресу /test-news/ открывается страница в оформлении вашего сайта с заголовком «Тест компонента» и пустым рабочим полем.

2. Найдите код типа и ID инфоблока. Откройте «Контент → Инфоблоки → Типы инфоблоков и инфоблоки». ID указан в колонке рядом с названием, а код типа виден в списке типов. Эти два значения компонент не угадывает.

   Проверка: у вас записаны два значения, например тип news и ID 1. В примерах ниже стоят именно они, подставьте свои.

3. Вставьте вызов компонента. Замените содержимое файла целиком. Здесь подключается стандартный компонент bitrix:news.list с шаблоном .default.

   <?php
   require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');
   $APPLICATION->SetTitle('Новости');
   
   $APPLICATION->IncludeComponent(
       'bitrix:news.list',
       '.default',
       [
           'IBLOCK_TYPE' => 'news',
           'IBLOCK_ID' => '1',
           'NEWS_COUNT' => '10',
           'SORT_BY1' => 'ACTIVE_FROM',
           'SORT_ORDER1' => 'DESC',
           'SET_TITLE' => 'N',
           'CACHE_TYPE' => 'N',
           'CACHE_TIME' => '3600',
       ],
       false
   );
   
   require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php');
   

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

4. Вынесите шаблон в /local/. Создайте файл /local/templates/.default/components/bitrix/news.list/my_list/template.php. Путь повторяет структуру компонента: пространство имён, имя, затем имя шаблона. Почему именно сюда: папка /bitrix/ принадлежит платформе, и обновление перезапишет в ней всё, что вы меняли.

   <?php
   if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
       die();
   }
   /** @var array $arResult */
   ?>
   <ul class='news-list'>
   <?php foreach ($arResult['ITEMS'] as $arItem): ?>
       <li>
           <a href='<?= htmlspecialcharsbx($arItem['DETAIL_PAGE_URL']) ?>'><?= htmlspecialcharsbx($arItem['NAME']) ?></a>
       </li>
   <?php endforeach; ?>
   </ul>
   

   Теперь в вызове со страницы замените второй аргумент '.default' на 'my_list'. Проверка: список превратился в простые ссылки без картинок и дат. Значит, Битрикс берёт ваш шаблон, а не стандартный.

Что куда вписать

Файл внутри /bitrix/components/bitrix/ вам не принадлежит. Всё, что вы там правили, обновление платформы перезапишет без предупреждения.

Если не получилось

Белая страница или «Call to a member function IncludeComponent() on null»

Объект $APPLICATION не создан: в файле нет require с header.php, либо вызов стоит выше него. Верните require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php') первой строкой после <?php. Если страница по-прежнему белая, а текста ошибки нет, включите вывод ошибок. Как это делается в вашей версии, смотрите в документации по режиму отладки (настройка exception_handling в файле /bitrix/.settings.php).

Заголовок есть, а блока с элементами нет

Компонент не ругается, он просто ничего не нашёл. Проверьте по порядку: совпадают ли IBLOCK_TYPE и IBLOCK_ID с реальными, активны ли элементы, не стоит ли дата начала активности в будущем, а дата окончания в прошлом. Типичный случай: ID скопирован с боевого сайта, а на тестовом у инфоблока другой номер.

На странице виден текст $APPLICATION->IncludeComponent(...)

Файл сохранён как .html или в нём нет открывающего <?php. Переименуйте файл в index.php и проверьте первую строку.

Правки в шаблоне не видны

Причин две. Либо вы правите не тот файл: во втором аргументе вызова стоит '.default', а изменения внесены в my_list. Либо страницу отдаёт кеш. На время разработки держите CACHE_TYPE равным 'N' и сбрасывайте кеш в разделе управления кешем («Настройки → Производительность», названия пунктов отличаются между версиями).

Компонент не найден

Проверьте имя: пространство имён, двоеточие, название, например bitrix:news.list. Опечатка в одной букве даст сообщение об ошибке на месте компонента, его точный текст зависит от версии и языка интерфейса. Собственные компоненты из /local/components/ вызываются по имени своего пространства имён, не по bitrix.

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

Перед выходом на боевой сайт верните CACHE_TYPE в 'A' и задайте осмысленный CACHE_TIME. Сверьте IBLOCK_ID на проде: он почти наверняка отличается от тестового. Папку /local/ положите в git, чтобы шаблон не жил только на сервере. Затем замерьте время генерации страницы с кешем и без него в панели производительности административного раздела. Разница покажет, зачем кеш нужен. Комплексные компоненты с ЧПУ и детальной страницей элемента здесь не разбираются: это следующий шаг после списка.