# Квэлп: Мега-меню

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

## Начало

Страницы «Меню сайта» и «Ручное наполнение», формы создания и редактирования ручного меню, история версий, права доступа, перенос и настройки, боковые редакторы баннеров и брендов оформлены в едином стиле Qwelp. Поиск и действия в списке ручных меню сохраняют штатную работу Битрикс. Источник, общие изображения и пункты меню расположены в отдельных панелях; в узком окне таблица прокручивается внутри панели. Настройки разделены на вкладки источника и внешнего вида. В узкой рабочей области подписи переходят над полями. Источник меню и внешний вид сохраняются отдельными кнопками.

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

1. Откройте настройки, выберите сайт и источник. Для ручного меню сначала создайте и опубликуйте вариант в ручном наполнении; для каталога выберите доступный инфоблок.
2. Включите меню и выберите вид: иконки, подробный, текстовый или подборки. В разделе «Меню сайта» добавьте изображения.
3. На вкладке «Подключение» скопируйте пример в шаблон сайта и проверьте кнопку каталога.

Установка сама не добавляет кнопку и не изменяет страницы сайта. Для подключения понадобится доступ к шаблону и базовое знание PHP.

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

Вставьте пример в PHP-файл своего шаблона сайта в том месте, где должна находиться кнопка «Каталог», после подключения заголовка Битрикс. На обычной странице это место между `bitrix/header.php` и `bitrix/footer.php`. В редакторе компонента доступны те же параметры.

```php
<button type="button" data-qmm-menu-trigger aria-controls="catalog-megamenu" aria-expanded="false">Каталог</button>
<?php
$APPLICATION->IncludeComponent('qwelp:megamenu.menu', '.default', [
    'SITE_ID' => '',
    'VIEW_TYPE' => 'site',
    'MAX_DEPTH' => 3,
    'SHOW_IMAGES' => 'Y',
    'SHOW_DESCRIPTIONS' => 'Y',
    'EDIT_MODE' => 'Y',
    'HTML_ID' => 'catalog-megamenu',
    'CACHE_TYPE' => 'A',
    'CACHE_TIME' => 3600,
    'CACHE_GROUPS' => 'N',
]);
?>
```

Оставьте `SITE_ID` пустым: модуль выберет текущий сайт. Значение `VIEW_TYPE = site` использует вид из настроек. Кнопка открывает меню, Escape закрывает его и возвращает фокус.

:::details Несколько меню на одной странице

Для каждого экземпляра задайте своё значение `HTML_ID` и такое же `aria-controls` у соответствующей кнопки. Не повторяйте идентификаторы. Для независимого внешнего вида задайте `VIEW_TYPE`: `icons`, `detailed`, `text` или `collections`.

:::

:::details Кеширование и многосайтовость

Используйте `CACHE_TYPE = A`. Компонент разделяет данные сайтов и административный режим, обновляет кеш после публикации и изменения оформления. Подключайте компонент отдельно в шаблоне каждого сайта; общая папка `/local/` не требуется. Все штатные ресурсы поставляются самим модулем.

:::

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

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

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

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

Баннер и бренды наследуются независимо. В список брендов можно добавлять строки, менять порядок, подписи, ссылки и изображения для тёмного оформления. Лимиты одного сохранения зависят от PHP: большой список сохраняйте частями.

:::details Собственное оформление

Скопируйте шаблон `icons`, `detailed`, `text` или `collections` штатным редактором Битрикс под новым именем в `/local/templates/ВАШ_ШАБЛОН/components/qwelp/megamenu.menu/ВАШ_ВИД/`. Укажите это имя вторым аргументом `IncludeComponent`, а соответствующий вид — в `VIEW_TYPE`. Изменяйте CSS в своей копии; сохраните HTML-идентификаторы, атрибуты управления, вызовы ресурсов и поддержку Композита. Обновление модуля не перезаписывает пользовательскую копию.

:::

Для тёмного оформления задайте `data-qmm-theme="dark"` элементу `html`. Цвета меняются собственными переменными `--qmm-*` в CSS сайта.

Кнопка «К меню сайта» в редакторе баннера и брендов закрывает боковое окно и возвращает к исходной странице. Если редактор открыт отдельной страницей, кнопка открывает меню выбранного сайта.

## Проверка

1. Откройте страницу как посетитель. Проверьте кнопку, вложенные пункты, ссылки, картинки и закрытие по Escape.
2. Проверьте узкое окно и прокрутку длинного меню. Откройте страницу повторно с кешем и Композитом.
3. Измените пункт, опубликуйте черновик и убедитесь, что посетитель видит новую версию.
4. На втором сайте задайте другое меню и проверьте, что настройки первого не изменились.

:::details Меню не открывается или пустое

Проверьте включение меню, сайт, выбранное дерево и его публикацию, привязку каталога и права. Значение «Без всплывающего меню» отключает вывод. Проверьте совпадение `HTML_ID` и `aria-controls`, наличие штатного вывода ресурсов в заголовке и отсутствие ошибок JavaScript. После изменения собственной копии шаблона очистите её кеш штатными средствами Битрикс.

:::

:::details Недоступно сохранение или загрузка

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

:::

## Справка

Откройте «Перенести меню из инфоблока» в настройках. Если ручного меню ещё нет, введите название и создайте его прямо на странице переноса. Пункты вручную добавлять не нужно. Выберите источник и меню, нажмите «Проверить перенос», затем «Перенести в черновик» в результате проверки. Откроется редактор с перенесённой структурой. Режим с изображениями копирует изображения разделов, баннеры и логотипы брендов в локальные файлы модуля; штатное облачное хранилище Битрикс не мешает переносу локальных исходников. «Только структура» не копирует изображения. Повтор того же режима не создаёт дубль; после переноса структуры можно отдельно импортировать изображения. Проверьте черновик и нажмите «Сохранить и опубликовать». Затем в настройках выберите ручной источник и это меню, включите показ и сохраните источник. Перенос сам не переключает меню сайта. Редактор показывает последнюю публикацию, если после неё не сохранён более новый черновик.

Требования: PHP 8.2 и Bitrix main 25.900.0 или новее. Ручной источник не требует торгового каталога; автоматический использует штатные модули `iblock` и `catalog`. Импорт использует `iblock`. Внешних платных сервисов и встроенных покупок нет.

| Параметр | Значение |
| --- | --- |
| SITE_ID | Пусто — текущий сайт; вывод чужого сайта запрещён. |
| VIEW_TYPE | site, icons, detailed, text, collections; none скрывает меню. |
| MAX_DEPTH | Глубина от 1 до 6. |
| SHOW_IMAGES / SHOW_DESCRIPTIONS | Y или N: изображения и описания. |
| EDIT_MODE | Y разрешает ссылки редактора только при включённом режиме правки и достаточных правах. |
| HTML_ID | Уникальный идентификатор, равный aria-controls кнопки. |
| ARIA_LABEL | Доступное название; пусто — стандартное локализованное. |
| CACHE_TYPE / CACHE_TIME | A — автоматически, Y — включён, N — выключен; срок в секундах. |
| CACHE_GROUPS | Y включает группы пользователя в ключ кеша; N отключает. Режим администратора изолирован отдельно. |

:::details Права, импорт и удаление

Общие права D/R/W и действия по сайтам настраиваются в стандартных настройках модуля. Дерево сохраняется в черновик и публикуется отдельно; изображения сохраняются сразу. Импорт сначала показывает предварительную проверку и требует подтверждения, сохраняя источник. Удаление по умолчанию сохраняет данные; полное удаление требует отдельного подтверждения. До обновления или удаления сделайте резервную копию. Общий модуль обслуживает все сайты установки.

:::

:::details Поля существующего каталога: для разработчика

По умолчанию модуль читает только собственные поля. Для подключения пользовательских UF зарегистрируйте экземпляр `Qwelp\Megamenu\Configuration\CatalogFieldMap` в `ServiceLocator` до получения сервисов модуля. Конструктор принимает соответствия `image`, `hidden`, `link`, `fallbackImage`, `visible`, `fallbackLink`, `background`, `bannerImage`, `bannerLink`, `fallbackBannerLink`, `brands` именам UF-полей. Соответствия входят в ключ кеша. Такой адаптер хранится в проекте клиента.

:::