LETUNOFF DOCS

Битрикс. Параметры компонентов

🧱 Суть

Параметры компонента – это настройки, которые передаются в компонент через метод IncludeComponent().

Они позволяют изменять поведение компонента без изменения его кода.

Например, через параметры можно настроить:

  • количество элементов;
  • сортировку;
  • ID инфоблока;
  • кеширование;
  • шаблон отображения;
  • дополнительные режимы работы.

📦 Проблема

Если жёстко прописывать настройки внутри компонента:

$newsCount = 10;
$iblockId = 5;

то компонент становится сложно переиспользовать.

Для каждого нового сценария придётся изменять его код.

✅ Решение

Передавать настройки через параметры. Тогда один и тот же компонент можно использовать на разных страницах с разными настройками.

💻 Код

Передача параметров

Параметры передаются третьим аргументом метода:

<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "",
    [
        "IBLOCK_ID" => 5,
        "NEWS_COUNT" => 10,
    ]
);
?>

Массив параметров автоматически становится доступен внутри компонента.

Массив $arParams

Все параметры находятся в массиве:

$arParams

Например:

$count = $arParams["NEWS_COUNT"];

или:

$iblockId = $arParams["IBLOCK_ID"];

Именно через $arParams компонент получает свои настройки.

Пример со списком новостей

<?php
$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "",
    [
        "IBLOCK_ID" => 5,
        "NEWS_COUNT" => 5,
        "SORT_BY1" => "ACTIVE_FROM",
        "SORT_ORDER1" => "DESC",
    ]
);
?>

В результате компонент:

  • возьмёт данные из инфоблока №5;
  • покажет 5 элементов;
  • отсортирует их по дате.

Один компонент – разные настройки

На разных страницах можно использовать один и тот же компонент:

Страница новостей:

[
    "IBLOCK_ID" => 5,
    "NEWS_COUNT" => 10,
]

Главная страница:

[
    "IBLOCK_ID" => 5,
    "NEWS_COUNT" => 3,
]

Код компонента останется одинаковым.

Часто используемые параметры

Для инфоблоков часто встречаются:

[
    "IBLOCK_TYPE" => "content",
    "IBLOCK_ID" => 5,
]

Для количества элементов:

[
    "NEWS_COUNT" => 10,
]

Для сортировки:

[
    "SORT_BY1" => "ACTIVE_FROM",
    "SORT_ORDER1" => "DESC",
]

Параметры кеширования

Практически все стандартные компоненты поддерживают кеширование.

Например:

[
    "CACHE_TYPE" => "A",
    "CACHE_TIME" => 3600,
]

Где:

  • A – автоматическое кеширование;
  • 3600 – время жизни кеша в секундах.

Параметры шаблона

Шаблон выбирается вторым аргументом:

$APPLICATION->IncludeComponent(
    "bitrix:news.list",
    "cards",
    []
);

Но некоторые настройки шаблона также могут передаваться через параметры:

[
    "SHOW_DATE" => "Y",
    "SHOW_PREVIEW_TEXT" => "N",
]

После этого шаблон сможет использовать эти значения через $arParams.

Собственные параметры

При разработке собственного компонента можно создавать любые параметры.

Например:

[
    "SHOW_AUTHOR" => "Y",
    "MAX_ITEMS" => 20,
]

Внутри компонента:

if ($arParams["SHOW_AUTHOR"] === "Y") {
    // вывод автора
}

Описание параметров

Для отображения параметров в административной панели используется файл:

.parameters.php

Пример:

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

После этого настройка появится в визуальном редакторе компонента.

Частые ошибки

Не проверять наличие параметра

Плохо:

$count = $arParams["NEWS_COUNT"];

Лучше:

$count = $arParams["NEWS_COUNT"] ?? 10;

Стоит предусматривать значения по умолчанию.

Жёстко прописывать настройки

Плохо:

$limit = 10;

Лучше:

$limit = $arParams["NEWS_COUNT"];

Передавать параметры неверного типа

Плохо:

[
    "NEWS_COUNT" => true
]

Лучше:

[
    "NEWS_COUNT" => 10
]

Использовать магические значения

Плохо:

if ($arParams["MODE"] === "1")

Лучше:

if ($arParams["MODE"] === "DETAIL")

Код становится понятнее.

Хранить бизнес-логику в параметрах

Параметры должны описывать настройки компонента, а не содержать сложную логику приложения.

🎯 Вывод

  • Параметры позволяют настраивать компонент без изменения его кода
  • Передаются третьим аргументом IncludeComponent()
  • Внутри компонента доступны через массив $arParams
  • Один компонент можно использовать на разных страницах с разными настройками
  • Собственные параметры описываются в файле .parameters.php
  • Грамотное использование параметров делает компоненты гибкими и переиспользуемыми

🔗 Связано

Обратные ссылки