Создание собственного компонента в Битрикс — это ключевой навык для любого разработчика, работающего с этой мощной CMS. Это не просто техническая задача, а возможность создавать переиспользуемые, структурированные и профессиональные модули функциональности, которые интегрируются в единую экосистему платформы. В этом руководстве мы разберем процесс от А до Я.
Что такое компонент Битрикс и зачем он нужен?
Компонент в терминологии Битрикс — это логически завершенный блок, который выполняет определенную функцию на странице: вывод новостей, фильтрацию каталога, форму обратной связи. В отличие от простого включения файла (include), компонент предоставляет единый интерфейс для настройки, кэширования, управления правами доступа и интеграции с системой событий (events).
Важно: Компоненты бывают комплексные (состоящие из нескольких шаблонов и логики) и простые. Мы сосредоточимся на создании комплексного компонента, как наиболее распространенного случая.
Структура компонента: основа основ
Каждый компонент располагается в папке /local/components/ (для собственной разработки) или /bitrix/components/ (для стандартных). Имя папки формируется по схеме namespace:component_name. Например, custom:news.list.
Обязательные файлы и папки:
- .description.php — описание компонента, его параметров, групп прав.
- class.php (опционально, но рекомендуется) — класс компонента, где описывается основная логика.
- component.php или .parameters.php — файл инициализации и обработки параметров.
- templates/ — папка для шаблонов. По умолчанию используется шаблон
.default. - lang/ — папка для языковых файлов (например,
/ru/.description.php).
Пошаговый процесс создания
Шаг 1: Создание структуры папок
Создайте папку для вашего компонента, например: /local/components/custom/news.detail/. Внутри сразу создайте папки templates/.default и lang/ru.
Шаг 2: Файл описания (.description.php)
Это «визитная карточка» компонента. Здесь вы задаете имя, описание, путь в визуальном редакторе, иконку и, самое главное, — массив параметров ($arComponentParameters). Параметры позволяют администратору настраивать компонент через визуальный интерфейс.
Используйте языковые файлы для всех строк в .description.php. Это обязательная практика для интернационализации.
Шаг 3: Класс компонента (class.php)
Наследуйте класс от \CBitrixComponent. Основные методы:
onPrepareComponentParams($arParams)— предобработка входящих параметров.executeComponent()— главный метод, который вызывается ядром. Здесь должна быть основная бизнес-логика: получение данных из БД, их обработка, подготовка массива$arResultдля передачи в шаблон.
Шаг 4: Точка входа (component.php)
Этот файл подключает класс и запускает компонент. Его код часто стандартен:
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED!==true) die();
$this->includeComponentTemplate();
executeComponent().
Шаг 5: Создание шаблона
В папке templates/.default/ создайте файл template.php. Это обычный PHP-файл, который получает данные из $arResult и $arParams и формирует HTML-вывод. Разделяйте логику и представление: в шаблоне — минимум PHP, в основном — HTML и вызовы данных.
Подключение и отладка
Подключить компонент можно двумя способами:
- В коде страницы:
$APPLICATION->IncludeComponent('custom:news.detail', '', $arParams); - Через визуальный редактор: В режиме правки страницы добавьте область и выберите ваш компонент из списка.
\Bitrix\Main\Diag\Debug::dump($variable); и смотрите логи в Административном разделе.
Не забывайте про кэширование! В методе executeComponent() можно задать ID кэша, теги и время жизни, чтобы значительно ускорить работу сайта.
Продвинутые техники
Когда основы освоены, изучите:
- AJAX-режим компонента: Возможность обновлять только часть компонента без перезагрузки страницы.
- Работа с D7 (Bitrix\Main): Использование современного ORM и API ядра вместо устаревших функций.
- Интеграция с композитным сайтом: Правильная настройка компонента для работы в режиме композитного кэширования.
- Создание собственных типов свойств (property types) для параметров в визуальном редакторе.
FAQ: Часто задаваемые вопросы
В чем разница между /local/components/ и /bitrix/components/?
Компоненты в /local/components/ — ваши собственные или доработанные. Они не будут перезаписаны при обновлении ядра Битрикс. /bitrix/components/ — для стандартных компонентов платформы.
Обязательно ли создавать класс (class.php)?
Нет, для простых компонентов можно обойтись только component.php и шаблоном. Но класс делает код структурированным, переиспользуемым и соответствует принципам ООП.
Как правильно именовать компонент?
Используйте осмысленные пространства имен (например, название компании или проекта) и имя, отражающее суть: project:catalog.filter, mycompany:feedback.form.
Мой компонент не появляется в визуальном редакторе. В чем проблема?
Проверьте корректность файла .description.php, особенно секцию 'PATH' => array('ID' => '...'). Убедитесь, что компонент размещен в правильной директории и что вы очистили кэш сайта (Административный раздел → Настройки → Настройки продукта → Очистка кэша).
Как организовать постраничную навигацию (пагинацию) в компоненте?
Используйте класс \Bitrix\Main\UI\PageNavigation (D7) или стандартные методы работы с $_GET['PAGEN_1'] и CDBResult::NavStart() в устаревшем подходе. Не забудьте передать параметры навигации в $arResult['NAV_STRING'] для вывода в шаблоне.