Рано или поздно на проекте появляется задача, которую штатные компоненты 1С-Битрикс не закрывают: особая выборка, интеграция с внешним сервисом, нестандартный блок с собственной логикой. Соблазн — «дописать» штатный компонент прямо в ядре. Так делать нельзя: правки затрутся при первом обновлении, а проект превратится в мину замедленного действия. Правильный путь — написать собственный компонент по стандартам платформы.
Это практическое руководство: как устроен компонент, где его размещать, как написать класс на D7, описать параметры, вывести данные в шаблон, настроить кэширование и AJAX. Материал — для разработчиков и техлидов, которые хотят делать поддерживаемый код, а не «костыли». Если нужна не теория, а готовое решение, посмотрите нашу услугу автоматизации на 1С.
Коротко
- Свой компонент нужен, когда штатные не покрывают логику; размещать его надо в /local/components/ со своим namespace.
- Логика живёт в class.php (наследник CBitrixComponent, D7-ORM), вывод — в template.php через $arResult.
- Параметры описываются в .parameters.php, тяжёлые выборки оборачиваются в управляемый кэш с корректным ключом.
- Интерактив делают через ajax-действия компонента, а шаблоны штатных компонентов переопределяют в шаблоне сайта.
Когда нужен свой компонент
Прежде чем писать код, стоит честно ответить: а нужен ли вообще новый компонент? Штатные компоненты Битрикс покрывают огромную долю задач — каталог, корзину, формы, новости, авторизацию. Своё решение оправдано, когда логика по-настоящему уникальна:
- Особая выборка данных. Данные собираются из нескольких источников по нестандартной логике.
- Интеграция. Компонент обращается к внешнему API или сервису и выводит результат.
- Нестандартный вывод. Блок, которого нет среди штатных, с собственным поведением.
- Переиспользуемость. Один и тот же нетиповой блок нужен на многих страницах и проектах.
Маркер того, что пора делать своё: вы копируете штатный компонент и переписываете половину его логики. В этот момент проще и чище написать собственный компонент, чем бороться с чужим. Но если готовое решение есть — используйте его, не изобретая велосипед.
Простой и комплексный компонент
В Битрикс есть два типа компонентов, и важно выбрать правильный.
| Критерий | Простой компонент | Комплексный компонент |
|---|---|---|
| Задача | Один блок / одна страница | Целый раздел из нескольких страниц |
| Маршрутизация | Нет | Своя, через ЧПУ |
| Пример | Блок «Похожие товары» | Каталог: список, раздел, детальная |
| Вложенность | Самостоятелен | Может вызывать простые внутри |
Для большинства кастомных задач достаточно простого компонента. Комплексный оправдан, когда нужен многостраничный раздел с человекопонятными URL и внутренней маршрутизацией. В этой статье фокус — на простом компоненте как базовом навыке; комплексный строится на тех же принципах, но добавляет обработку URL.
Структура файлов компонента
Компонент — это папка со строго заданной структурой, размещённая в пространстве имён. Правильное место — /local/components/namespace/component.name/, где namespace — ваш префикс (студия, проект). Каталог /local/ отделён от ядра и переживает обновления. Минимальный состав:
- class.php — класс компонента с логикой (наследник CBitrixComponent).
- .parameters.php — описание входных параметров для визуального редактора.
- .description.php — имя, описание и раздел компонента в каталоге.
- templates/.default/template.php — шаблон вывода по умолчанию.
- lang/ — языковые файлы для локализации подписей.
Такая структура — не формальность: она разделяет логику, параметры и вывод, и именно поэтому компонент легко поддерживать. Namespace защищает от конфликтов со штатными и сторонними компонентами.
Класс компонента на D7
Сердце компонента — класс в class.php, наследующий CBitrixComponent с методом executeComponent(). Именно он выполняется при подключении компонента. Внутри вы:
- Готовите входные параметры. В onPrepareComponentParams() приводите $arParams к нужным типам и значениям по умолчанию.
- Выбираете данные. Через D7-ORM собираете нужное и складываете в $arResult.
- Оборачиваете в кэш. Тяжёлую выборку помещаете между startResultCache() и endResultCache().
- Подключаете шаблон. Вызываете includeComponentTemplate() для вывода.
Ключевой принцип — вся логика живёт здесь, а не в шаблоне. Для выборок используйте современный D7-ORM, а не устаревшие методы: это чище, быстрее и предсказуемее. Подробно о выборках мы писали в статье про D7 и ORM в Битрикс.
Описание параметров
Файл .parameters.php описывает входные параметры компонента для визуального редактора Битрикс. Благодаря ему контент-менеджер настраивает компонент через удобный интерфейс, а не правит код. В параметрах задают:
- Тип поля. Строка, список, флажок, привязка к инфоблоку.
- Значения по умолчанию. Чтобы компонент работал «из коробки».
- Группировку. Логические группы настроек для удобства.
- Параметры кэширования. Стандартные поля времени и типа кэша.
Хорошо описанные параметры превращают компонент в переиспользуемый инструмент: один и тот же код настраивается под разные задачи без правок. Это особенно ценно, когда компонент используется на многих страницах или проектах.
Шаблон и вывод $arResult
Шаблон template.php получает готовый массив $arResult, сформированный в классе, и превращает его в HTML. Здесь действуют простые правила хорошего тона:
- Только вывод. Никаких выборок к базе и тяжёлой логики — всё уже подготовлено в классе.
- Экранирование. Пользовательские данные выводятся с защитой от XSS.
- result_modifier.php. Дополнительную подготовку данных под конкретный шаблон выносят сюда, не трогая класс.
- Ассеты через API. CSS и JS подключаются штатными средствами, а не «зашиваются» в HTML как попало.
Разделение «класс — данные, шаблон — вывод» позволяет менять внешний вид независимо от логики и наоборот. Один компонент может иметь несколько шаблонов под разные места использования.
Кэширование результата
Компонент без кэша на нагруженном сайте — источник тормозов. Тяжёлые выборки оборачивают в штатный механизм кэширования компонента:
- Оберните выборку. Поместите её между startResultCache() и endResultCache().
- Соберите корректный ключ. В кэш-ключ включите всё, что влияет на результат: раздел, язык, группу пользователя, страницу, значимые параметры.
- Подключите теговый кэш. Регистрируйте теги кэша, чтобы он сбрасывался при изменении связанных данных.
- Кладите в кэш только нужное. В $arResult — минимум данных для шаблона, без «мусора».
Самая частая ошибка — неполный ключ кэша: если группа пользователя или страница не учтены, часть посетителей увидит чужой «прилипший» результат. Кэш ускоряет сайт только тогда, когда он корректен. Тему производительности мы продолжаем в статье про хостинг и инфраструктуру BitrixVM, а инженерную выкладку изменений — в материале про CI/CD и деплой на Битрикс.
AJAX-действия компонента
Интерактив — подгрузку, фильтрацию, отправку форм — реализуют через механизм ajax-действий компонента. Это класс с методами-действиями, которые вызываются с фронтенда через BX.ajax.runComponentAction. Преимущества перед «самопальными» обработчиками:
- Единая точка входа. Все действия компонента в одном месте, а не в разрозненных файлах.
- Проверка сессии. Встроенная защита от подделки запросов.
- Удобная передача данных. Параметры и ответ в структурированном виде.
- Единый формат ошибок. Ответы приходят в предсказуемой структуре.
Внутри действия обязательно проверяйте права и валидируйте вход — это публичный endpoint, к нему применимы те же требования безопасности, что и к любому API. Подробнее — в статье про REST, вебхуки и безопасность в Битрикс.
Подключение и переопределение шаблона
Готовый компонент подключается на странице стандартным вызовом с указанием пути и параметров. А чужой (штатный или сторонний) компонент кастомизируют, не трогая его самого: шаблон копируют в шаблон сайта /local/templates/ваш_шаблон/components/... и правят там.
Это фундаментальное правило обновляемости: файлы в /bitrix/ менять нельзя — правки затрутся при обновлении платформы. Переопределение через шаблон сайта — единственный безопасный способ изменить вывод штатного компонента. Так вы получаете нужный внешний вид и сохраняете возможность спокойно обновлять ядро.
Пошаговый порядок разработки
- Проверьте, нет ли готового. Убедитесь, что штатный компонент задачу не решает.
- Создайте структуру. Папка в /local/components/namespace/ с обязательными файлами.
- Напишите класс. D7-класс с onPrepareComponentParams() и executeComponent().
- Опишите параметры. .parameters.php с типами, дефолтами и полями кэша.
- Сделайте шаблон. template.php выводит только $arResult.
- Включите кэш. Обёртка с корректным ключом и теговым кэшем.
- Добавьте AJAX при необходимости. Через ajax-действия с проверкой прав.
- Протестируйте. Разные параметры, группы пользователей, сброс кэша, нагрузка.
Частые ошибки
- Правки в /bitrix/. Изменения ядра затираются при обновлении — работайте в /local/.
- Логика в шаблоне. Запросы к базе в template.php ломают кэш и поддержку.
- Неполный ключ кэша. Не учли группу или страницу — часть пользователей видит чужие данные.
- Нет кэша вовсе. Тяжёлые выборки на каждый хит убивают производительность.
- Устаревшие методы. Старые API вместо D7-ORM — медленнее и хуже поддерживается.
- Самопальный AJAX. Обработчики без проверки сессии и прав — дыра в безопасности.
- Нет namespace. Компонент без своего префикса конфликтует с чужими.
Чек-лист качества
- Размещение верное. Компонент в /local/components/namespace/ со своим префиксом.
- Логика в классе. D7-класс отвечает за данные, шаблон — только за вывод.
- Параметры описаны. .parameters.php позволяет настраивать компонент без кода.
- Кэш корректен. Ключ учитывает все влияющие факторы, есть теговый сброс.
- AJAX безопасен. Через ajax-действия с проверкой прав и валидацией.
- Шаблон переопределяем. Вывод меняется в шаблоне сайта, ядро не тронуто.
- Протестировано. Разные параметры, группы, нагрузка и сброс кэша проверены.
Вывод
Собственный компонент в 1С-Битрикс — это не «хак», а штатный, поддерживаемый способ расширять платформу. Ключ к качеству — дисциплина: размещать код в /local/ со своим namespace, держать логику в D7-классе, а вывод — в шаблоне, аккуратно кэшировать с корректным ключом и делать интерактив через безопасные ajax-действия.
Такой компонент легко поддерживать, переиспользовать и переносить между проектами, а платформа при этом остаётся обновляемой. Если начать с проверки «нет ли готового решения» и дальше следовать структуре из этой статьи, вы получите чистый код вместо «костылей» — и сэкономите себе месяцы боли на сопровождении.
