Как создать компонент битрикс

Компонент в Битрикс – это директория с определённой структурой: /bitrix/components/имя_разработчика/имя_компонента/. Внутри размещаются файлы шаблона, логики, описания и конфигурации. Ключевые файлы: component.php (обработка данных), .parameters.php (описание параметров) и шаблоны в папке /templates/.

Создание собственного компонента – это не только способ расширить функционал сайта, но и важный шаг к стандартизации и масштабируемости проекта. Разработка должна вестись с учётом кеширования, прав доступа и API-интерфейсов, чтобы обеспечить стабильную работу компонента в любых условиях.

Структура папок и файлов компонента в Bitrix

Компоненты в Bitrix размещаются в каталоге /local/components/, что обеспечивает сохранность при обновлениях системы. Структура компонентов строго регламентирована и должна соблюдаться для корректной работы механизма подключения и шаблонов.

• /local/components/имя_вендора/имя_компонента/ – корневая папка компонента.
• component.php – основной исполняемый файл компонента. В нем размещается логика обработки параметров, выборки данных и подключение шаблона.
• .parameters.php – описание параметров компонента для отображения в публичном интерфейсе редактирования (визуальный редактор).
• class.php – необязательный файл, содержащий компонент в виде класса, если используется объектный стиль (наследование от CBitrixComponent).
• templates/ – папка шаблонов компонента.

Внутри templates/ должен быть хотя бы один шаблон:

• style.css и script.js – дополнительные файлы стилей и скриптов (опционально).
• result_modifier.php – файл для модификации результатов, передаваемых в шаблон, до их отображения.

Если используется AJAX или вложенные шаблоны, рекомендуется создание подшаблонов в виде отдельных файлов или вложенных папок внутри шаблона, например include/item.php.

Файлы должны иметь кодировку UTF-8 без BOM. Все директории и имена файлов – в нижнем регистре. Нарушение структуры приведёт к некорректной работе компонента или его неотображению в списке доступных в визуальном редакторе.

Регистрация компонента в системе Битрикс

Для регистрации компонента создайте папку компонента в директории /local/components. Структура должна соответствовать формату /local/components/вендор/код_компонента. Имя вендора пишется латиницей, как правило, в нижнем регистре. Пример: /local/components/myvendor/news.list.

Внутри папки компонента необходимо создать два обязательных файла: component.php и .description.php. Первый содержит основной код компонента, второй – метаинформацию для системы.

Файл .description.php должен возвращать массив с ключами NAME, DESCRIPTION, PATH и CACHE_PATH. Обязательно укажите структуру вложенности через ключ PATH с подпунктами ID и NAME. Пример:

return [
"NAME" => "Список новостей",
"PATH" => [
"ID" => "myvendor",
"NAME" => "Мои компоненты"
],
"CACHE_PATH" => "Y"
];

После сохранения файлов компонент становится доступным в визуальном редакторе и может использоваться в шаблонах и страницах сайта. Битрикс автоматически сканирует директорию /local/components без необходимости дополнительной регистрации в административной панели.

Для группировки компонентов по разделам используйте единый ID в ключе PATH. Это упростит навигацию при большом количестве пользовательских компонентов.

Настройка шаблона компонента и подключение CSS/JS

Подключение CSS и JS осуществляется через файл component.php внутри основного каталога компонента или через template.php при использовании API Asset:

\Bitrix\Main\Page\Asset::getInstance()->addCss($templateFolder."/style.css");
\Bitrix\Main\Page\Asset::getInstance()->addJs($templateFolder."/script.js");

Для подключения CSS/JS, расположенных вне шаблона (например, в /local/assets/), указывайте абсолютные пути относительно корня сайта:

\Bitrix\Main\Page\Asset::getInstance()->addCss("/local/assets/css/custom.css");
\Bitrix\Main\Page\Asset::getInstance()->addJs("/local/assets/js/custom.js");

Избегайте подключения стилей и скриптов через <link> и <script> в шаблоне – это нарушает порядок загрузки и может вызвать конфликты. Используйте $APPLICATION->SetAdditionalCSS() только в исключительных случаях, когда API Asset недоступен.

Для передачи параметров из PHP в JS используйте метод CUtil::InitJSCore() и BX.message(). Пример:

CUtil::InitJSCore();
$jsParams = [
'ajaxUrl' => '/local/components/ваш_путь/ваш_компонент/ajax.php',
'templatePath' => $templateFolder
];
?>

При необходимости подключения сторонних библиотек (например, jQuery), проверяйте, не загружены ли они ранее. Используйте Asset::addJs() перед $APPLICATION->ShowHead() в шаблоне сайта.

Работа с параметрами компонента через .parameters.php

Файл .parameters.php размещается в директории /bitrix/components/ваш_компонент/.parameters.php и предназначен для описания параметров компонента, отображаемых в визуальном редакторе при его добавлении на страницу.

Основной массив для конфигурации – $arComponentParameters. Он должен быть возвращён функцией include в файле .parameters.php. Структура массива включает секции GROUPS и PARAMETERS. Первая определяет логические блоки, вторая – сами параметры.

Пример объявления группы:

$arComponentParameters["GROUPS"]["FILTER_SETTINGS"] = [
"NAME" => "Настройки фильтра",
"SORT" => 200
];

Пример параметра:

$arComponentParameters["PARAMETERS"]["ELEMENT_COUNT"] = [
"PARENT" => "BASE",
"NAME" => "Количество элементов",
"TYPE" => "STRING",
"DEFAULT" => "10"
];

Ключ PARENT определяет принадлежность параметра к группе. Стандартные группы: BASE, DATA_SOURCE, ADDITIONAL_SETTINGS. Значение TYPE может быть: STRING, LIST, CHECKBOX, CUSTOM.

Для параметра с типом LIST необходимо указать массив VALUES:

$arComponentParameters["PARAMETERS"]["SORT_ORDER"] = [
"PARENT" => "DATA_SOURCE",
"NAME" => "Направление сортировки",
"TYPE" => "LIST",
"VALUES" => [
"ASC" => "По возрастанию",
"DESC" => "По убыванию"
],
"DEFAULT" => "ASC"
];

Для динамического получения значений следует использовать CIBlockParameters::GetElementGroups, CIBlockParameters::GetIBlockTypes или аналогичные методы. В этом случае необходимо предварительно подключить нужные модули через CModule::IncludeModule.

Изменения в .parameters.php вступают в силу сразу и не требуют очистки кэша, если компонент не использует кэширование параметров вручную. Проверяйте корректность возвращаемого массива – ошибки приведут к недоступности настроек компонента в админке.

Организация выборки данных внутри компонента

Для выборки данных в компоненте используется метод GetList соответствующего ORM-класса или API-модуля. Например, при работе с инфоблоками применяется CIBlockElement::GetList, либо \Bitrix\Iblock\Elements\Element{ИмяИнфоблока}Table::getList при использовании D7.

Выборка должна выполняться в методе executeComponent или вынесена в отдельную защищённую функцию внутри компонента. Все параметры фильтрации, сортировки и выборки должны быть заданы явно, без использования глобальных переменных.

Пример фильтрации по активным элементам с заданным свойством:

$filter = [
'IBLOCK_ID' => $this->arParams['IBLOCK_ID'],
'ACTIVE' => 'Y',
'!=PROPERTY_HIDE' => 'Y'
];
$select = ['ID', 'NAME', 'PREVIEW_TEXT', 'DETAIL_PAGE_URL'];
$sort = ['SORT' => 'ASC'];
$elements = \CIBlockElement::GetList($sort, $filter, false, ['nTopCount' => 10], $select);

При использовании ORM предпочтительно применять fetchCollection() для работы с результатами как с объектами:

use Bitrix\Iblock\Elements\ElementNewsTable;
$result = ElementNewsTable::getList([
'select' => ['ID', 'NAME'],
'filter' => ['ACTIVE' => 'Y'],
'order' => ['SORT' => 'ASC'],
'limit' => 10
]);
$items = $result->fetchCollection();

if (!$this->startResultCache()) {
return;
}
$this->arResult['ITEMS'] = $items;
$this->includeComponentTemplate();

Фильтрация по пользовательским параметрам допустима только после их валидации. Нельзя напрямую передавать значения из $_GET в фильтр без проверки на допустимость.

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

Для повышения производительности пользовательских компонентов в Битрикс необходимо использовать встроенный механизм кеширования. Основной инструмент – методы $this->startResultCache() и $this->endResultCache(), обеспечивающие сохранение результата работы компонента.

При вызове $this->startResultCache($cacheTime, $cacheId, $cachePath) передается время жизни кеша (в секундах), уникальный идентификатор и путь к папке кеша. Если кеш существует и не истек, код внутри блока не выполняется, а данные берутся из кеша.

Важно правильно формировать ключ кеша, учитывая все параметры, влияющие на результат. Например, если компонент зависит от фильтров или пользовательских настроек, они должны входить в $cacheId. Это предотвращает выдачу устаревших данных.

Для автоматического сброса кеша при изменении данных можно использовать событие OnAfterIBlockElementUpdate или вручную вызывать $this->abortResultCache() при обнаружении ошибок или несоответствий.

Не стоит кешировать слишком большие объемы данных или хранить кеш дольше, чем нужно. Оптимальное время жизни – от 5 минут до нескольких часов, в зависимости от частоты обновления информации.

В случае AJAX-запросов кеширование можно настроить отдельно, исключая повторную загрузку одинаковых данных, что снижает нагрузку на сервер и ускоряет отклик.

Использование метода $this->setResultCacheKeys() позволяет указать ключи массива $arResult, которые должны сохраняться вне кеша, например, для динамических данных.

Правильное кеширование пользовательских компонентов уменьшает количество обращений к базе данных и существенно повышает скорость загрузки страниц без потери актуальности информации.

Для вызова собственного компонента в шаблоне или файле страницы используется функция includeComponent. Ее базовый синтаксис:

$APPLICATION->IncludeComponent("ваш_префикс:имя_компонента", "шаблон", array("ПАРАМЕТР1" => "значение1", "ПАРАМЕТР2" => "значение2"), $parentComponent);

Обязательным параметром является идентификатор компонента в формате префикс:имя, который соответствует структуре вашего каталога в /bitrix/components/. Вторым параметром указывается имя шаблона компонента. Если шаблон не требуется, достаточно передать пустую строку.

Для передачи параметров используйте конкретные ключи с описанными в компоненте возможными значениями. Например, "ELEMENT_ID" => 42 или "SHOW_DATE" => "Y". Избегайте передачи необработанных пользовательских данных без валидации.

Четвертым параметром можно передать родительский компонент, если требуется вложенность и наследование параметров. Если это не нужно, передайте null.

$APPLICATION->IncludeComponent("custom:news.detail", "", array("ELEMENT_ID" => $_REQUEST["ID"], "CACHE_TIME" => 3600), null);

Важно: передаваемые параметры должны строго соответствовать описанию компонента, иначе возможны ошибки или некорректное поведение. Для комплексных параметров можно передавать вложенные массивы.

Вопрос-ответ:

Какие основные файлы нужно создать для собственного компонента в Битрикс?

Для создания компонента нужно подготовить минимум три файла: description.php с описанием параметров и настроек, component.php, где размещается основная логика, и template.php для оформления вывода. В зависимости от сложности, могут использоваться дополнительные файлы, например, для обработки AJAX-запросов или подключения стилей.

Как правильно передать параметры из вызова компонента в его шаблон?

Параметры, которые указываются при подключении компонента, передаются в массив $arParams внутри component.php. Чтобы использовать их в шаблоне, необходимо через $this->arParams получить доступ к этим значениям. Это позволяет гибко настраивать отображение компонента без изменения кода шаблона.

Какие рекомендации по организации шаблонов для компонентов в Битрикс?

Шаблоны компонентов стоит располагать в отдельной папке внутри /bitrix/templates/ваш_шаблон/components/название_компонента/. В шаблонах следует использовать локализацию и избегать хардкода, чтобы обеспечить возможность легкой кастомизации и поддержки. Для разделения логики и представления стоит оставить в шаблоне только код, отвечающий за вывод, а всю логику — в component.php.

Можно ли использовать компоненты, созданные вручную, совместно со стандартными средствами Битрикс?

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

Как реализовать кеширование данных в собственном компоненте?

Кеширование организуется через методы $this->StartResultCache() и $this->EndResultCache() внутри component.php. При первом запуске данные сохраняются, а при повторных вызовах берутся из кеша, что снижает нагрузку на сервер. Важно правильно настроить ключи кеша и очищать его при изменении данных, чтобы отображалась актуальная информация.

Как правильно зарегистрировать собственный компонент в системе Битрикс?

Для регистрации своего компонента необходимо создать папку с уникальным именем в директории /local/components или /bitrix/components. Внутри этой папки размещаются файлы компонента: описание, шаблоны и PHP-скрипты. Далее требуется подключить компонент в нужном месте сайта с помощью функции $APPLICATION->IncludeComponent(), указав путь к вашему компоненту и необходимые параметры. Также рекомендуется добавить файл .description.php с базовой информацией, чтобы система могла распознать компонент.

Какие особенности стоит учитывать при разработке шаблона для собственного компонента?

Шаблон компонента отвечает за визуальное отображение данных. Важно, чтобы шаблон находился в папке /templates вашего компонента и использовал стандартные переменные, передаваемые из PHP-логики. Следует избегать жестко прописанных путей и данных, чтобы обеспечить гибкость и возможность переиспользования. Также стоит обеспечить поддержку нескольких шаблонов для разных сценариев и учитывать адаптивность дизайна. В шаблоне рекомендуется отделять логику от разметки, используя массивы с данными, переданные из компонента.