Создаём первый компонент в 1С-Битрикс: пошаговое руководство

Постановка задачи

Создадим компонент my:hello, который:

• принимает текстовый параметр MESSAGE (приветствие);

• если параметр не задан, используется значение по умолчанию «Здравствуйте!»;

• выводит этот текст в абзаце с классом hello-message.

Шаг 1. Создаём структуру папок и файлов

Все пользовательские компоненты мы размещаем в /local/components/. Создадим следующую иерархию:

/local/components/
└── my/                          # пространство имён
    └── hello/                   # название компонента
        ├── .description.php
        ├── .parameters.php
        ├── component.php        # основной файл логики
        └── templates/
            └── .default/
                ├── template.php
                └── style.css     # добавим для красоты

Важно: в Linux регистр имён файлов важен! Все названия пишем строчными буквами.

Шаг 2. Описание компонента — .description.php

Этот файл нужен, чтобы компонент отображался в визуальном редакторе с правильным названием и иконкой.

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

$arComponentDescription = [
    'NAME' => 'Приветствие',
    'DESCRIPTION' => 'Выводит приветственное сообщение с настраиваемым текстом',
    'PATH' => [
        'ID' => 'my',
        'NAME' => 'Мои компоненты',
    ],
];

Теперь в визуальном редакторе в разделе «Мои компоненты» появится наш компонент с названием «Приветствие».

Шаг 3. Параметры компонента — .parameters.php

Здесь мы опишем единственный параметр MESSAGE. Он будет строковым, с возможностью ввода произвольного текста в настройках компонента.

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

$arComponentParameters = [
    'PARAMETERS' => [
        'MESSAGE' => [
            'NAME' => 'Текст приветствия',
            'TYPE' => 'STRING',
            'DEFAULT' => 'Здравствуйте!',
            'PARENT' => 'BASE',
        ],
    ],
];

• TYPE = STRING означает текстовое поле ввода.

• DEFAULT — значение по умолчанию, если пользователь ничего не введёт.

• PARENT = BASE — помещает параметр в основную группу настроек.

Шаг 4. Логика компонента — component.php

Этот файл — «мозг» компонента. Здесь мы обрабатываем входные параметры и готовим данные для шаблона.

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

// Если параметр MESSAGE не передан или пуст, подставляем значение по умолчанию
$arParams['MESSAGE'] = trim($arParams['MESSAGE']);
if (empty($arParams['MESSAGE'])) {
    $arParams['MESSAGE'] = 'Здравствуйте!';
}

// Передаём сообщение в $arResult для вывода в шаблоне
$arResult['MESSAGE'] = htmlspecialcharsbx($arParams['MESSAGE']);

// Подключаем шаблон
$this->includeComponentTemplate();

Что здесь важно:

• Мы используем htmlspecialcharsbx() для экранирования вывода — это защита от XSS-атак.

• Всю подготовку данных делаем до вызова шаблона.

• Шаблон подключается последним.

Альтернатива с class.php (D7):

Если вы предпочитаете современный подход, создайте файл class.php вместо component.php:

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

class HelloComponent extends CBitrixComponent
{
    public function executeComponent()
    {
        $this->arParams['MESSAGE'] = trim($this->arParams['MESSAGE']);
        if (empty($this->arParams['MESSAGE'])) {
            $this->arParams['MESSAGE'] = 'Здравствуйте!';
        }
        
        $this->arResult['MESSAGE'] = htmlspecialcharsbx($this->arParams['MESSAGE']);
        $this->includeComponentTemplate();
    }
}

Для простоты в этой статье мы используем component.php, но в серьёзных проектах рекомендую переходить на классы.

Шаг 5. Шаблон вывода — templates/.default/template.php

Теперь создаём HTML-код, который будет видеть пользователь.

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

<div class="hello-block">
    <p class="hello-message"><?= $arResult['MESSAGE'] ?></p>
</div>

Добавим немного стилей в style.css, чтобы вывод выглядел аккуратно:

.hello-block {
    padding: 15px;
    background: #f9f9f9;
    border-left: 4px solid #1e88e5;
    margin: 10px 0;
}
.hello-message {
    font-size: 18px;
    color: #333;
    margin: 0;
}

Теперь компонент полностью готов к использованию.

Шаг 6. Подключение компонента на страницу

Есть два способа добавить компонент на сайт.

Способ 1. Через визуальный редактор (для редакторов и контент-менеджеров)

1. Откройте любую страницу в режиме редактирования (например, главную).

2. В панели инструментов нажмите «Редактировать страницу» или «Изменить дизайн».

3. В визуальном редакторе выберите место для вставки компонента (например, добавьте «Компонент» в нужную область).

4. В появившемся окне выбора компонента найдите наш my:hello в разделе «Мои компоненты».

5. Установите параметр «Текст приветствия» (например, «Добро пожаловать на наш сайт!»).

6. Сохраните изменения — и на странице появится ваше приветствие.

Способ 2. Программно через PHP-код (для разработчиков)

Если вы правите шаблон сайта или создаёте своё решение, можно вставить компонент прямо в код:

<?$APPLICATION->IncludeComponent(
    "my:hello",
    ".default",
    array(
        "MESSAGE" => "Привет, мир!"
    ),
    false
);?>

Этот код можно разместить в любом шаблоне страницы или в файле index.php.

Проверка и отладка

После добавления компонента на страницу вы должны увидеть что-то вроде:

Добро пожаловать на наш сайт!

Если вместо этого появляется пустота или ошибка, проверьте:

• Правильно ли созданы все файлы (регистр имён!).

• Нет ли синтаксических ошибок в PHP-коде.

• Включён ли режим отладки (в настройках сайта) для просмотра ошибок.

Что дальше?

Мы создали простейший компонент, который уже можно использовать в проектах. Но в реальной жизни компоненты редко ограничиваются выводом статической строки. Чаще всего они работают с инфоблоками, пользователями, корзиной и т.д.

В следующей статье мы научимся:

• работать с параметрами разных типов (списки, числа, флажки);

• получать данные из инфоблоков;

• формировать сложные $arResult для шаблонов.

Подписывайтесь на обновления блога, чтобы не пропустить продолжение!

Если у вас возникли вопросы или вы столкнулись с трудностями — пишите в комментариях, разберёмся вместе!