> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Анимированные фоны

> Настройка анимированных фонов Cabinet на базе Aceternity UI

## Обзор

Cabinet включает библиотеку из **15 анимированных фонов**, работающих как полноэкранные визуальные эффекты за контентом. Фоны построены на основе компонентов [Aceternity UI](https://ui.aceternity.com/), оптимизированных для производительности в браузере и Telegram MiniApp.

> **15 эффектов**
>
> CSS, Canvas и SVG-анимации на выбор

> **Live-превью**
>
> Предпросмотр прямо в админке при настройке

> **Мобильная оптимизация**
>
> Автоматическое снижение нагрузки на мобильных устройствах

## Доступные фоны

### CSS-анимации

| Тип | Описание | Настройки |
| - | - | - |
| **Aurora** | Градиентное свечение с плавными переливами | 3 цвета, скорость (медленно / нормально / быстро) |
| **Gradient Animation** | Анимированный многоцветный градиент | 5 цветов, интерактивность мышью, размер |
| **Grid** | Сетка с анимацией | Размер ячейки, цвет |
| **Dots** | Точечный паттерн | Размер ячейки, размер точки |
| **Spotlight** | Двигающийся луч света | Цвет, размер |

### Canvas-анимации

| Тип | Описание | Настройки |
| - | - | - |
| **Sparkles** | Мерцающие частицы | Плотность, размер, скорость |
| **Vortex** | Спиральный вихрь частиц | Количество, радиус, оттенок, скорость |
| **Shooting Stars** | Падающие звёзды | Цвет звёзд и хвоста, плотность, скорость |
| **Wavy** | Волновое искажение | Скорость, ширина волны, размытие, прозрачность |
| **Background Lines** | Плавные линии | Количество, цвет, скорость, толщина |
| **Ripple** | Расходящиеся круги | Цвет, количество, скорость |
| **Boxes** | Вращающиеся кубики в сетке | Строки, столбцы, цвет |
| **Meteors** | Падающие метеоры | Количество, цвет |

### SVG-анимации

| Тип | Описание | Настройки |
| - | - | - |
| **Background Beams** | 50 лучей с градиентом cyan→purple→magenta | Только глобальные настройки |
| **Beams Collision** | Лучи со столкновениями | Только глобальные настройки |

## Настройка через админку

Управление фонами доступно в **Настройки → Фоны** в админ-панели Cabinet.

**1. Включите анимацию**

Переключатель «Анимация включена» активирует фон для всех пользователей.

**2. Выберите тип**

Кнопки сгруппированы по категориям (CSS / Canvas / SVG). При выборе тип сразу применяется в превью.

**3. Настройте параметры**

Каждый тип имеет свои настройки: цвета, скорость, плотность частиц и другие. Изменения видны в live-превью.

**4. Глобальные настройки**

Для любого типа доступны общие параметры.

### Глобальные параметры

| Параметр | Диапазон | По умолчанию | Описание |
| - | - | - | - |
| Прозрачность | 0.1 – 1.0 | 1.0 | Общая прозрачность фона |
| Размытие | 0 – 20 px | 0 | Гауссово размытие поверх анимации |
| Снижение на мобильных | Вкл / Выкл | Вкл | Урезает количество частиц и отключает интерактивность на мобильных |

## Производительность

Все фоны оптимизированы для работы без просадок:

* **Portal-рендеринг** — фон рендерится через `createPortal` на `document.body` с `z-index: -1`, полностью исключая implicit compositing между фоном и UI-элементами
* **GPU-ускорение** — CSS-анимации используют `transform` и `will-change` для композиторного слоя
* **CSS containment** — `contain: strict` изолирует перерисовки фона от остального UI
* **Lazy-загрузка** — JS-чанк фона загружается отложенно через `React.lazy`
* **Предзагрузка** — при повторных визитах чанк подгружается из localStorage-кэша ещё до рендера React
* **FPS-троттлинг** — `useAnimationLoop` хук: 30 FPS на мобильных / 60 FPS на десктопе, автопауза при сворачивании вкладки (Page Visibility API) и деактивации Telegram MiniApp
* **Мобильный режим** — количество частиц уменьшается, DPR ограничивается до 1.5, интерактивные эффекты отключаются, blur ограничен 4px
* **`prefers-reduced-motion`** — анимация полностью отключается при системной настройке «Уменьшить движение»
* **Валидация конфигурации** — проверка типа анимации по allowlist, числовые ограничения, лимит размера JSON-конфигурации

### SVG Beams

Компонент Background Beams использует чистые CSS-анимации `stroke-dashoffset` без изменения `opacity` — это предотвращает перерисовку (repaint) всей страницы. Из 50 лучей одновременно анимируются только 17, остальные отображаются статически с минимальной прозрачностью.

### Canvas Boxes

Компонент Boxes переписан с 225 отдельных DOM-элементов на единый `<canvas>`. Это исключает проблему re-compositing'а, когда hover-эффекты на контенте вызывали перерисовку всех 225 регионов. Canvas-содержимое пиксельное и не подвержено влиянию DOM-событий.

## API

| Метод | Путь | Описание |
| - | - | - |
| GET | `/cabinet/branding/animation-config` | Получить текущую конфигурацию |
| PATCH | `/cabinet/branding/animation-config` | Обновить конфигурацию (админ) |
| GET | `/cabinet/branding/animation` | Проверить, включена ли анимация |
| PATCH | `/cabinet/branding/animation` | Включить / выключить анимацию (админ) |

### Формат конфигурации

```json theme={null}
{
  "enabled": true,
  "type": "aurora",
  "settings": {
    "color1": "#00d2ff",
    "color2": "#7a2aff",
    "color3": "#ff0080",
    "speed": "normal"
  },
  "opacity": 1.0,
  "blur": 0,
  "reducedOnMobile": true
}
```

## Кэширование

Конфигурация фона кэшируется в `localStorage` (`cabinet_animation_config`). При загрузке страницы Cabinet сначала использует кэш для мгновенного отображения, затем в фоне запрашивает актуальную конфигурацию с сервера. Это обеспечивает отображение фона без задержки даже при медленном соединении.

## Отключение

Для полного отключения анимированных фонов:

1. **Через админку** — выключите переключатель «Анимация включена» в разделе настроек
2. **Через API** — `PATCH /cabinet/branding/animation` с `{"enabled": false}`
3. **Тип «none»** — выберите тип «Без анимации» для явного отключения


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.