# Квэлп: Блоки товаров с вкладками

Полное руководство из встроенной справки qwelp.productblocks. Версия 1.0.0, сверка 11.10.2026.

## Начало

### Первая товарная подборка

Все настройки находятся в одном редакторе: состав товаров, оформление, слайдер и код подключения.

1. Откройте настройки модуля и выберите инфоблоки товаров по умолчанию.
2. В списке подборок нажмите «Добавить подборку», задайте название и выберите «Слайдер» или «Сетка» на вкладке «Основное».
3. На вкладке «Товары» заполните состав. Для нескольких наборов выберите группировку «Вкладки».
4. На вкладке «Карточки» выберите типы цен и оформление. На вкладках «Слайдер» и «Стрелки и точки» настройте прокрутку и навигацию.
5. Включите «Подборка активна» и сохраните. Откройте «Код подключения», скопируйте готовый пример и вставьте его на страницу с подключённым прологом Битрикса.

Создавать отдельное место размещения больше не требуется. Одна подборка имеет свой состав, настройки и код. Сохранение подборки само по себе не вставляет компонент в страницу.

Новая подборка создаётся выключенной. Сначала заполните её, затем включите. Изменение источников по умолчанию не меняет источники уже сохранённых вкладок.

Создать подборкуОткрыть подборкиНастройки модуля

## Подборки и вкладки

### Единый редактор подборки

В списке подборок виден общий режим вывода: слайдер, сетка или прежний шаблон сайта. Здесь же есть ссылка на код подключения каждой подборки.

| Вкладка | Настройки |
| --- | --- |
| Основное | Название, активность, заголовок, режим вывода, группировка товаров и ссылка «Смотреть все». |
| Товары | Источники, ручной список, автоматический фильтр, лимит и порядок товарных вкладок. |
| Карточки | Простая или каталожная карточка, типы цен, изображение и шаблон подборки. |
| Слайдер | Количество карточек, шаг, отступы, скорость, эффекты и адаптивные диапазоны. |
| Стрелки и точки | Положение, размер, цвета и состояния навигации. |
| Код подключения | Готовый вызов компонента для этой подборки. Доступен после первого сохранения. |

Кнопки сохранения общие для всех вкладок редактора. Режим «Один блок» выводит первый активный набор товаров, «Вкладки» позволяет переключать наборы. Сетка и слайдер выбираются отдельно на вкладке «Основное».

Кнопка «Переменные» у ссылки «Смотреть все» вставляет `#SITE_DIR#` в позицию курсора или вместо выделенного текста. Например, `#SITE_DIR#catalog/` ведёт в каталог текущего сайта.

### Оформление на разных сайтах

Над редактором сохранённой подборки выберите общие настройки или конкретный сайт. Выбор относится к оформлению; состав товаров и основные поля подборки общие. Сайт без собственного оформления использует общие настройки. Изменение поля оформления снимает флажок наследования; чтобы вернуться к общим настройкам, включите его и сохраните.

При первом сохранении старой подборки её прежнее оформление переносится из настроек размещения вместе с отдельными настройками сайтов. Далее каждая подборка настраивается независимо.

:::details Вкладка не появилась на сайте

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

:::

## Отбор товаров

### Как выбрать товары

Настройка «Состав по умолчанию» находится у каждой вкладки. Начните с ручной подборки, если нужен фиксированный набор; для обновляемого списка используйте автоматический отбор.

| Режим | Результат |
| --- | --- |
| Ручная подборка | Выводятся закреплённые товары в пределах заданного количества. Автоматический фильтр не дополняет список. |
| Автоматический отбор | Товары выбираются по готовому условию или расширенному фильтру. Если закрепить товары вручную, они займут первые позиции, а отбор заполнит оставшиеся. |
| Смешанный: ручные товары и автоотбор | Закреплённые товары идут первыми, остальные места заполняются по фильтру без повторов. |

### Ручной список

1. Выберите «Ручная подборка».
2. В поле «Закреплённые товары» откройте выбор товаров. При нескольких источниках переключайте инфоблок в окне выбора, находите товары по названию, артикулу или ID и добавляйте нужные элементы.
3. Установите «Количество» не меньше желаемого числа карточек и сохраните.

### Готовые условия

Для автоотбора доступны «Все активные товары», «Хиты продаж», «Новинки» и «Спецпредложения». Последние три условия зависят от свойств товаров: SALELEADER, NEWPRODUCT и SPECIALOFFER. Проверьте их заполнение в своём каталоге.

:::details Свои условия: пример JSON-фильтра

Выберите «Свои условия» и вставьте в «Расширенный фильтр»:

```
{"SECTION_ID": 12, "INCLUDE_SUBSECTIONS": "Y"}
```

Замените 12 на ID раздела своего каталога. Пример выберет товары из него и подразделов. Количество по-прежнему ограничивается настройкой вкладки.

Фильтр должен быть JSON, а не PHP-кодом. Разрешены поля товара, свойства PROPERTY_* и поддерживаемые поля CATALOG_*. Вложенные группы LOGIC не поддерживаются; неизвестные ключи отбрасываются. Проверяйте результат на сайте, чтобы условие не оказалось шире ожидаемого.

:::

:::details Количество товаров отличается от заданного

«Количество» — верхняя граница. Если подходящих товаров меньше или они недоступны посетителю, карточек будет меньше. Также проверьте активность товаров, выбранный каталог и настройки публичного компонента.

:::

## Подключение

### Подключение подборки на страницу

1. Откройте нужную подборку и вкладку «Код подключения».
2. Нажмите «Копировать». Если браузер запрещает копирование, код выделится для ручного копирования.
3. Вставьте пример в PHP-включаемую область или шаблон страницы. Это выполняет разработчик с доступом к файлам сайта.

```php
<?php
$APPLICATION->IncludeComponent(
    'qwelp:productblocks.placement',
    '',
    [
        'BLOCK_CODE' => 'my_selection',
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => 3600,
    ]
);
?>
```

Замените `my_selection` на системный код подборки или скопируйте готовый пример из её редактора. Вызов выводит одну активную подборку. Внутри уже открытого PHP-блока внешние теги не нужны. Пустой второй аргумент позволяет выбирать шаблон в редакторе подборки.

:::details Ранее подключённые места размещения

Старые вызовы с `PLACEMENT_CODE` сохраняются и выводят привязанные активные подборки. Создавать такие вызовы для новых подборок не требуется. Для вывода одной подборки используйте `BLOCK_CODE`; он имеет приоритет.

```php
<?php
$APPLICATION->IncludeComponent(
    'qwelp:productblocks.placement',
    '',
    [
        'PLACEMENT_CODE' => 'catalog_top',
        'CACHE_TYPE' => 'A',
        'CACHE_TIME' => 3600,
    ]
);
?>
```

Пользовательские копии шаблонов сохраняются. Если в старом месте выводится несколько подборок, общий внешний шаблон этого вызова по-прежнему определяется прежним размещением; независимый выбор внешнего шаблона доступен через вызов с `BLOCK_CODE`.

:::

:::details Контекст каталога

Разработчик может передать `CONTEXT_PRODUCT_ID` и `CONTEXT_SECTION_ID`. Это контекст страницы, а не фильтр товаров сам по себе. Текущий сайт определяется Битриксом.

:::

## Оформление

### Карточки и слайдер

Откройте подборку. Переключатель «Вывод товаров» находится на вкладке «Основное», рядом показано, включён ли слайдер. Настройки прокрутки на вкладке «Слайдер» действуют только в режиме «Слайдер». Для старых подборок доступен прежний шаблон сайта без слайдера модуля.

На вкладке «Карточки» выберите простую карточку или `bitrix:catalog.item`. Простая карточка ведёт на страницу товара; покупка и выбор торговых предложений зависят от каталожного шаблона. Типы цен выбираются из списка. После сохранения оформления подборки этот выбор имеет приоритет над `PRICE_CODE` во всех режимах; доступ к цене и покупке проверяет каталог Битрикса.

Слайдер поддерживает количество и шаг слайдов, отступы, скорость, autoplay и паузы, loop/rewind, эффекты, жесты, клавиатуру, колесо, свободную прокрутку, scrollbar и адаптивные диапазоны. Вертикальному режиму нужна высота. Эффекты кроме slide/coverflow требуют одну карточку на всех ширинах и отключённую свободную прокрутку. При недостатке товаров loop заменяется на rewind.

На вкладке «Стрелки и точки» задаются положение, размеры, рамки, скругления, цвета и состояния наведения. Swiper 11.2.10 и MIT-лицензия включены в модуль. Совместимый Swiper 11 сайта используется повторно; неизвестная версия не заменяется. Другие модули Qwelp не требуются.

### Свой шаблон

Скопируйте весь шаблон из `/bitrix/components/qwelp/productblocks.placement/templates/.default/` в `/local/templates/ВАШ_ШАБЛОН/components/qwelp/productblocks.placement/ИМЯ/`. Для общей копии используйте `/local/templates/.default/components/qwelp/productblocks.placement/ИМЯ/`. Выберите копию на вкладке «Карточки».

`products.php`, `display.css` и `display.js` задают обёртку; `bitrix/catalog.section/qpb_cards/simple.php` — простую карточку. Шаблон catalog.item копируется штатным способом. Обновление модуля сохраняет пользовательские копии; новые возможности нужно переносить в старую копию вручную.

:::details Шаблон не меняется

Пустой второй аргумент IncludeComponent использует настройки подборки. Явно переданное имя, включая .default, имеет приоритет. Проверьте код подключения и кеш изменённой страницы.

:::

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

## Проверка и кеш

### Проверка результата и кеш

1. Откройте страницу с подборкой в обычном режиме и отдельно как неавторизованный посетитель.
2. Сверьте заголовок, порядок блоков и вкладок, закреплённые товары и количество карточек.
3. Переключите вкладки, проверьте ссылки товаров и «Смотреть все», прокрутку или сетку на узком экране.
4. Если блок используется на нескольких сайтах, проверьте каждый адрес с его шаблоном и каталогом.

### Если что-то не появилось

| Симптом | Что проверить |
| --- | --- |
| Нет всего блока | Компонент подключён на этой странице; код подборки совпадает; подборка и хотя бы одна вкладка активны; есть доступные товары. |
| Нет отдельных товаров | Выбран правильный каталог, товары активны и доступны посетителю. Проверьте лимит, фильтр и закреплённый список. |
| Неверный состав | Проверьте режим отбора и JSON. Встроенные правила сайта могут дополнительно определять состав блока; сравните результат с настройками интеграции этой страницы. |
| Нет цены или карточки выглядят иначе | Проверьте выбранные типы цен на вкладке «Карточки», права посетителя и шаблон карточки. |
| После сохранения виден старый результат | Обновите страницу. Затем проверьте кеш компонента, Композит и кеш браузера после изменения CSS/JS. |
| Подборка есть в админке, но не на сайте | Новая область требует вызова компонента в шаблоне или включаемой области. Название подборки не задаёт позицию в HTML автоматически. |

:::details Как проверить кеш

Сохранение подборки сбрасывает кеш данных модуля. При ручной правке шаблонов обновите кеш изменённого компонента штатными средствами Битрикса. Если включён Композит, обновите также его копию нужной страницы и откройте её без авторизации.

В примерах указан `CACHE_TIME = 3600` секунд. Переданный параметр компонента имеет приоритет над общим временем кеша. Отключение кеша не должно оставаться постоянным способом исправления устаревшего вывода.

:::

:::details Что передать разработчику

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

:::

## Справка

### Параметры компонента

| Параметр | Назначение |
| --- | --- |
| BLOCK_CODE | Код одной подборки. Основной способ подключения; готовый пример есть в редакторе. |
| PLACEMENT_CODE | Совместимость со старыми вызовами: выводит активные подборки прежнего места размещения. |
| CATALOG_IBLOCK_ID | Резервный источник. Источники товарной вкладки имеют приоритет. |
| SECTION_TEMPLATE | Шаблон catalog.section для прежнего режима вывода. |
| PRICE_CODE | Совместимость со старыми вызовами. После сохранения оформления подборки типы цен берутся из её вкладки «Карточки». До первого сохранения в прежнем режиме явный PRICE_CODE сохраняет приоритет, а отсутствующий наследует цены размещения. В сетке и слайдере используются настройки оформления. |
| DETAIL_URL / BASKET_URL | Шаблон ссылки на товар и путь корзины. |
| CONTEXT_PRODUCT_ID / CONTEXT_SECTION_ID | Контекст товара и раздела страницы, по умолчанию 0. |
| CACHE_TYPE / CACHE_TIME | Режим кеша и срок в секундах. Пример использует A и 3600. |
| Второй аргумент IncludeComponent | Пустая строка — оформление из настроек подборки; явное имя шаблона имеет приоритет. |

### Настройки и права

Настройки модуля содержат источники товаров по умолчанию, служебный инфоблок и время кеша. Смена служебного инфоблока показывает его подборки, не переносит и не удаляет прежние данные. В штатном разделе настроек модулей находится вкладка «Доступ»: чтение позволяет открыть подборки и справку, запись — менять настройки.

:::details Обновление и удаление

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

:::