Перейти к содержимому
Поиск
Разработка

Embla Carousel: карусели для интерфейсов — мастерская и 8 живых примеров

Восемь интерфейсов на настоящей Embla: услуги, галерея, адаптивный каталог, отзывы, управляемое движение и динамические данные. Мастерская и исходники.

Александр Некрасов
Embla Carousel: карусели для интерфейсов — мастерская и 8 живых примеров — обложка

Карусель полезна, когда несколько связанных объектов нужно показать в ограниченном пространстве: фотографии товара, варианты услуги, этапы кейса или подборку материалов. Но сама движущаяся лента ещё не делает интерфейс понятным. Пользователь должен видеть, что есть продолжение, уметь перейти к нужной карточке и остановить движение. Особенно важно сохранить эти возможности на телефоне и при работе с клавиатурой.

Embla Carousel отвечает за движение, точки остановки, жесты и события. Разметку карточек, кнопки, подписи, цвета и поведение приложения вы определяете сами. Такой подход удобен для продукта со своим дизайном: не нужно подгонять весь кабинет под внешний вид готового виджета. Можно использовать обычный HTML и JavaScript либо подключить адаптер выбранного фреймворка.

В статье соберём восемь полноценных вариантов: услуги, галерею, адаптивный каталог, свободную ленту, отзывы разной высоты, управляемое автолистание, фильтрацию данных и жизненный цикл компонента. На странице работает настоящая Embla. Все изображения нарисованы нашим кодом, исходники доступны целиком, а запуск показан для Windows и Linux.

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

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

Начинайте с вопроса о действии пользователя. Если ему нужно найти один документ среди сотни, поиск и таблица обычно полезнее бесконечного пролистывания. Если он изучает шесть фотографий одного объекта, карусель естественна. Удобство определяется тем, насколько быстро человек достигает своей цели, а не количеством эффектов или скоростью анимации.

Карусель скрывает часть содержимого за пределами видимой области. Поэтому обязательные условия заказа, предупреждения и основные действия не стоит помещать только на дальние слайды. Для сравнения характеристик товаров часто удобнее сетка или таблица. Если достаточно нативной прокрутки с привязкой, CSS scroll-snap может решить задачу без JavaScript-зависимости.

Embla особенно полезна, когда нужны связанные кнопки, миниатюры, события, плагины и собственный контроль жизненного цикла. Она не предоставляет за вас готовую дизайн-систему. На сайте есть материал про Swiper; его удобно рассматривать рядом с Embla, когда выбираете между большим набором готовых возможностей и компактной основой для собственного интерфейса.

Не принимайте решение только по размеру первого примера. Посчитайте состояния, которые реально нужны продукту: пустой набор, один элемент, ошибки данных, изменение ширины, загрузка изображений и переход с клавиатуры. Иногда простой горизонтальный список окажется надёжнее. В мастерской мы показываем разные ситуации, чтобы можно было проверить поведение до интеграции.

Задача Что рассмотреть
Все элементы нужно сравнить сразу Сетка или таблица
Простая горизонтальная прокрутка CSS overflow + scroll-snap
Свой дизайн, события и связанное управление Embla Carousel
Много готовых эффектов и модулей Сравнение со Swiper по требованиям

Выберите задачу в списке. Рядом появятся её смысл и конкретный эксперимент: пройти до конца, выбрать миниатюру, изменить ширину, найти пустой результат или проверить повторную инициализацию. Карусель использует реальную библиотеку, а не запись заранее подготовленной анимации. Данные учебные, цены демонстрационные, запросы к внешним сервисам не выполняются.

Ниже ленты находятся номер шага, кнопки, индикатор положения, события и JSON текущих настроек. В разделе исходников можно посмотреть и скачать отдельный файл. Полный архив содержит сборку public, код src, lock-файл, тесты и инструкции. Большую мастерскую можно открыть отдельно, чтобы одновременно видеть карточки, параметры и журнал.

Автолистание изначально выключено. Его нужно включить вручную в соответствующем сценарии; системное уменьшение движения имеет приоритет. Изменённый каталог хранится только в текущей вкладке и возвращается к исходному набору при смене задачи или обновлении страницы. Это позволяет свободно экспериментировать, не меняя материалы сайта и не создавая серверных данных.

В проекте закреплены Embla Carousel 8.6.0, Autoplay 8.6.0 и Auto Height 8.6.0. На момент подготовки материала официальный сайт также показывал ветку 9 RC. Это отдельный API: нельзя брать часть настроек из документации v8, другую часть из предварительной v9 и ожидать одинакового поведения. Ссылки в статье ведут именно к документации стабильной восьмой ветки.

Оформление использует Bootstrap 5.3.9 и собственные стили. Сборщик esbuild объединяет JavaScript в app.js; при открытии мастерской CDN не нужен. Для воспроизведения выбран Node.js 24 LTS. package-lock.json фиксирует транзитивные зависимости, поэтому команда npm ci предпочтительнее установки случайного нового набора библиотек.

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

{
  "name": "aen-embla-workshop",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "build": "node tools/build.mjs",
    "test": "node --test tests/*.test.mjs",
    "serve": "node tools/serve.mjs"
  },
  "dependencies": {
    "embla-carousel": "8.6.0",
    "embla-carousel-autoplay": "8.6.0",
    "embla-carousel-auto-height": "8.6.0",
    "bootstrap": "5.3.9"
  },
  "devDependencies": {
    "esbuild": "0.28.2"
  }
}

Установите Node.js 24 LTS, распакуйте архив в отдельную папку и откройте в ней PowerShell. Проверьте версию node, затем установите зависимости, выполните тесты и сборку. Команды не требуют PHP или отдельной базы данных: серверная часть для самой карусели не нужна. Исходники можно редактировать в обычном редакторе.

После serve откройте адрес, который выводит консоль: по умолчанию это http://127.0.0.1:8590/. Встроенный сервер слушает только локальный интерфейс. Чтобы остановить его, нажмите Ctrl+C в той же консоли. Если порт занят другой вашей программой, задайте PORT перед запуском, а не завершайте чужой процесс.

Не открывайте index.html через file://. Мастерская загружает sources.json и JavaScript-модуль, а ограничения файлового протокола отличаются от обычного сайта. Готовая папка public уже включена в ZIP, но после изменения src нужно снова выполнить build. Иначе просмотрщик исходников и код, который фактически исполняется, перестанут соответствовать друг другу.

node --version
npm ci
npm test
npm run build
npm run serve

# Другой порт, если нужен:
$env:PORT = "8594"
npm run serve

На Linux используйте тот же lock-файл и Node.js 24 LTS. Запускайте npm от обычного пользователя проекта. Сборка и тесты не требуют прав root. Для временной проверки на VPS сервер также можно оставить на loopback и открыть через SSH-туннель: это удобнее, чем публиковать служебный порт в интернет.

Dockerfile выполняет установку, тесты и сборку в отдельном Linux-образе. Контейнер проверки запускается с –rm и не использует пользовательские тома. Этот способ подтверждает воспроизводимость проекта на другой платформе, но сам по себе не проверяет отрисовку карусели: для этого нужна браузерная приёмка с реальной геометрией страницы.

Для постоянного размещения Node-сервер из tools не требуется. После build достаточно статических файлов public, которые может отдавать Nginx или Caddy. Разделы ниже показывают этот маршрут. Разделяйте временную лабораторию и эксплуатацию: отладочный сервер удобен для первого запуска, а для действующего сайта важны HTTPS, права на файлы и проверенное обновление.

node --version
npm ci
npm test
npm run build
PORT=8590 npm run serve

# На своём компьютере для доступа к удалённой лаборатории:
ssh -L 8590:127.0.0.1:8590 user@your-server

# Изолированная проверка Linux:
docker build -t aen-embla-lab .
docker run --rm --name aen-embla-check aen-embla-lab

Embla получает элемент viewport. Внутри находится контейнер слайдов, обычно flex-лента. Сам viewport скрывает выходящее за границы содержимое, а библиотека управляет положением контейнера. Размеры карточек задаются CSS, поэтому один и тот же JavaScript можно использовать для одного большого кадра или нескольких узких карточек.

У каждого flex-слайда важно установить min-width:0. Без этого длинный текст или вложенный элемент иногда заставляет карточку стать шире ожидаемого. Промежутки в примере сделаны левым padding слайда и отрицательным margin контейнера. Это лишь выбранная схема оформления; главное, чтобы размеры, которые видит браузер, соответствовали логике ленты.

touch-action:pan-y pinch-zoom сохраняет вертикальную прокрутку страницы и масштабирование. Не блокируйте все жесты ради горизонтального слайдера. На мобильном человек должен спокойно пройти вниз по статье, даже если палец оказался над карточкой. Перетаскивание является дополнительным способом управления, а кнопки остаются доступными всегда.

<div class="embla-viewport" tabindex="0">
  <div class="embla-track">
    <div class="slide"><article>Карточка услуги</article></div>
    <div class="slide"><article>Следующая услуга</article></div>
  </div>
</div>
.embla-viewport { overflow: hidden; touch-action: pan-y pinch-zoom; }
.embla-track { display: flex; margin-left: -16px; }
.slide { flex: 0 0 82%; min-width: 0; padding-left: 16px; }

Первый сценарий показывает несколько предложений с названием, описанием, категорией и учебной ценой. На узком экране видна часть соседней карточки: это подсказывает, что лента продолжается. Кнопки находятся рядом с номером шага, поэтому человеку не приходится искать маленькие стрелки поверх изображения.

По умолчанию loop выключен. На первом шаге кнопка назад недоступна, на последнем отключается переход вперёд. Такое поведение удобно для конечной подборки: пользователь понимает, что уже посмотрел весь набор. Бесконечный цикл иногда выглядит эффектнее, но может затруднить оценку количества элементов и собственного положения.

Кнопки должны получать состояние от API, а не от предположения о числе карточек. На разных ширинах количество точек остановки меняется, и последний шаг не всегда равен последнему индексу массива. В мастерской canScrollPrev и canScrollNext управляют disabled, а selectedScrollSnap и scrollSnapList формируют номер текущего шага.

const api = EmblaCarousel(viewport, {
  loop: false,
  align: 'start',
  containScroll: 'trimSnaps'
});
function updateButtons() {
  prev.disabled = !api.canScrollPrev();
  next.disabled = !api.canScrollNext();
}
prev.addEventListener('click', () => api.scrollPrev());
next.addEventListener('click', () => api.scrollNext());
api.on('select', updateButtons);
api.on('reInit', updateButtons);
updateButtons();

В галерее один кадр занимает всю ширину viewport. Ниже находятся миниатюры с понятными подписями и номером. Нажатие миниатюры вызывает scrollTo, а событие select обновляет её aria-pressed. Это двусторонняя связь: выбранная миниатюра меняется и после жеста, и после нажатия обычной кнопки.

В нашей мастерской используются собственные SVG-панели, созданные кодом. В товарном интерфейсе замените их реальными изображениями и осмысленными альтернативными подписями. Для каждого файла задайте width и height либо aspect-ratio, чтобы загрузка не вызывала скачков размеров. Полноразмерное изображение лучше открывать отдельным действием, а не пытаться вместить все детали в маленькое превью.

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

thumbButtons.forEach((button, index) => {
  button.addEventListener('click', () => api.scrollTo(index));
});
function updateThumbs() {
  const selected = api.selectedScrollSnap();
  thumbButtons.forEach((button, index) => {
    button.setAttribute('aria-pressed', String(index === selected));
  });
}
api.on('select', updateThumbs);
updateThumbs();

В каталоге на телефоне видна одна карточка, на среднем экране две, на широком три. CSS определяет ширину каждого слайда, а slidesToScroll:auto группирует движение по доступному пространству. В результате кнопка переводит человека к следующей видимой группе, а не всегда сдвигает каталог на один узкий элемент.

Здесь особенно важно различать карточку и точку остановки. Массив данных может содержать шесть объектов, но точек навигации на широком экране будет меньше. Для счётчика и точек используйте scrollSnapList. Для списка действительно видимых элементов используйте slidesInView и связывайте полученные индексы с собственными ID данных.

Проверьте изменение ширины не только после обновления страницы, но и при уже выбранном шаге. Embla наблюдает за размерами и переинициализируется, однако ваши подписи и элементы управления тоже должны обновиться на reInit. Важный практический случай — карусель в боковой панели: её ширина может измениться без изменения общего размера окна.

const api = EmblaCarousel(viewport, {
  align: 'start', loop: false, slidesToScroll: 'auto'
});
api.on('reInit', () => {
  rebuildDots(api.scrollSnapList().length);
  updateButtons();
});
.mode-catalog .slide { flex-basis: 100%; }
@media (min-width: 650px) {
  .mode-catalog .slide { flex-basis: 50%; }
}
@media (min-width: 950px) {
  .mode-catalog .slide { flex-basis: 33.333%; }
}

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

Индикатор положения можно построить на scrollProgress. Значение ограничиваем диапазоном от нуля до единицы, затем переводим в проценты. Это защищает визуальную полосу от выхода за пределы при движении возле границ. Индикатор отражает положение ленты, а не процент просмотренного человеком материала: такие смыслы не следует смешивать.

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

const api = EmblaCarousel(viewport, { dragFree: true });
api.on('scroll', () => {
  const value = Math.max(0, Math.min(1, api.scrollProgress()));
  progressBar.style.width = `${value * 100}%`;
  progress.setAttribute('aria-valuenow', String(Math.round(value * 100)));
});

Реальные отзывы редко имеют одинаковую длину. Фиксированная маленькая высота обрезает содержание, а фиксированная большая оставляет много пустого пространства после короткого текста. Auto Height подстраивает контейнер под самый высокий из видимых слайдов. В мастерской один отзыв заметно длиннее остальных, поэтому разницу легко проверить.

Для корректной работы контейнеру нужно align-items:flex-start, а высоту карточки должен определять её контент. Если все слайды принудительно растянуты до одной высоты, плагину нечего подстраивать. В примере добавлен короткий CSS-переход высоты, который отключается при prefers-reduced-motion.

Анимация высоты вызывает перерасчёт раскладки. На насыщенной странице это может быть заметно, поэтому используйте её умеренно и проверяйте длинный текст, увеличенный шрифт и позднюю загрузку изображений. Для отзывов с важной информацией иногда лучше обычный вертикальный список. Плагин помогает решить конкретную задачу оформления, но не делает скрытый текст автоматически удобнее для чтения.

import AutoHeight from 'embla-carousel-auto-height';
const api = EmblaCarousel(viewport, { loop: false }, [AutoHeight()]);
.mode-height .embla-track {
  align-items: flex-start;
  transition: height .2s ease;
}
.mode-height .slide article { height: auto; }
@media (prefers-reduced-motion: reduce) {
  .mode-height .embla-track { transition: none; }
}

Автоматическое движение может мешать читать и выбирать. Поэтому в мастерской Autoplay подключён с playOnInit:false. Пользователь сам нажимает кнопку запуска и видит текстовое состояние. Повторное нажатие останавливает движение. Настройки stopOnInteraction, stopOnMouseEnter и stopOnFocusIn прекращают автолистание, когда человек взаимодействует с каруселью.

Системная настройка уменьшения движения имеет приоритет: при её включении кнопка запуска недоступна, а переходы выполняются без анимации. При уходе вкладки в фон автолистание также останавливается и не запускается самостоятельно после возвращения. Это сохраняет предсказуемость: пауза не является кратким препятствием, которое компонент тут же отменяет.

Не переносите этот пример в рекламный баннер без проверки требований продукта. Важные сообщения должны оставаться доступными достаточно долго, а остановка — заметной и доступной с клавиатуры. Интервал в четыре секунды здесь служит демонстрацией механизма, а не универсальным временем чтения. Для длинного текста автоматическое движение чаще всего лучше вообще не включать.

import Autoplay from 'embla-carousel-autoplay';
const autoplay = Autoplay({
  delay: 4000,
  playOnInit: false,
  stopOnInteraction: true,
  stopOnMouseEnter: true,
  stopOnFocusIn: true
});
const api = EmblaCarousel(viewport, { loop: true }, [autoplay]);
playButton.addEventListener('click', () => {
  if (reducedMotion.matches) return;
  autoplay.isPlaying() ? autoplay.stop() : autoplay.play();
});
document.addEventListener('visibilitychange', () => {
  if (document.hidden) autoplay.stop();
});

В рабочем интерфейсе набор карточек редко остаётся неизменным. Пользователь выбирает категорию, вводит поисковую строку или получает новый ответ API. Наша мастерская фильтрует локальный массив по категории и тексту, позволяет добавить учебную карточку и удалить выбранную. Когда результатов нет, появляется понятное объяснение вместо пустой рамки с работающими стрелками.

Данные должны оставаться источником истины. Сначала вычисляется новый набор объектов, затем создаётся разметка, после этого вызывается reInit. В примере watchSlides:false отключает автоматическое наблюдение за изменениями списка, потому что приложение само управляет переинициализацией. Это делает последовательность явной и не вызывает две независимые реакции на одну замену DOM.

Сохраняем выбранный ID, если объект остался в наборе. Если он удалён, ограничиваем прежний индекс допустимым диапазоном. Для пустого массива возвращаем ноль как технический стартовый индекс, но не создаём бесполезный активный экземпляр. При реальном API добавьте ещё состояния загрузки и ошибки; отсутствие данных и неудачный запрос имеют разный смысл.

const next = selectItems(allItems, category.value, search.value);
const start = restoredIndex(previousId, previousIndex, next);
renderCards(next);
if (next.length === 0) {
  api.destroy();
  showEmptyState();
} else {
  api.reInit({ startIndex: start });
  api.scrollTo(start, true);
}

Индекс меняется при сортировке, фильтрации и вставке. Поэтому сохранение только числа «третий слайд» часто возвращает человека к другому объекту. Стабильный ID принадлежит данным: услуге, документу или фотографии. Он позволяет найти тот же объект после обновления, даже если его место изменилось.

В примере функция restoredIndex сначала ищет прежний ID, затем использует ограниченный индекс как запасной вариант. Для динамического сценария выбран один полный слайд на шаг, чтобы соответствие было явным. При группировке или разных ширинах карточек индекс слайда и индекс точки остановки могут расходиться; там нужно отдельно определить, какой объект считается текущим.

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

export function restoredIndex(previousId,previousIndex,next){const found=next.findIndex(x=>x.id===previousId);return found>=0?found:Math.min(Math.max(0,previousIndex),Math.max(0,next.length-1));}

В одностраничном приложении компонент появляется и исчезает при переключении разделов. В обычном сайте его тоже могут перенести в модальное окно, скрытую вкладку или обновляемый блок. Важно отличать переинициализацию существующего экземпляра от полного уничтожения. reInit пересчитывает состояние, destroy завершает жизненный цикл.

Подписки, созданные через api.on, сохраняются после reInit. Если каждый раз заново добавлять тот же по смыслу обработчик новой функцией, один переход начнёт вызывать несколько одинаковых действий. В мастерской обработчики назначаются один раз при создании экземпляра. Счётчик select позволяет проверить результат: три reInit и один переход должны дать одно событие выбора.

После destroy сохранённый API больше не используется. Наш интерфейс оставляет статический горизонтальный список и отдельную кнопку восстановления. Новое создание получает новые обработчики и актуальные DOM-узлы. Это полезная модель для интеграции: содержимое остаётся доступным, а управляющая логика имеет понятные границы и не накапливает скрытые таймеры.

function onSelect(api) {
  console.log('Шаг:', api.selectedScrollSnap());
}
api.on('select', onSelect);
api.reInit(); // подписка уже существует, повторно api.on не нужен

// Если подписка больше не нужна:
api.off('select', onSelect);

// При уходе компонента:
api.destroy();
api = null;

Карусель не должна требовать точного жеста. В мастерской viewport получает tabindex=0, а кнопки являются обычными button с доступными названиями. Стрелки, Home и End обрабатываются только когда фокус находится внутри viewport. Глобально перехватывать эти клавиши нельзя: они нужны для других полей и привычной навигации по странице.

Номер текущего шага объявляется через aria-live, но во время автолистания объявления отключаются, чтобы не создавать поток навязчивых сообщений. Слайды имеют названия и номер внутри набора. Миниатюры сообщают состояние через aria-pressed, а точка навигации — через aria-current. Цвет дополняет эти признаки, но не заменяет их.

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

viewport.addEventListener('keydown', event => {
  if (!api) return;
  if (event.key === 'ArrowRight') {
    event.preventDefault();
    api.scrollNext(reducedMotion.matches);
  }
  if (event.key === 'Home') {
    event.preventDefault();
    api.scrollTo(0, reducedMotion.matches);
  }
});

Embla предоставляет события для выбора, прокрутки, изменения видимых слайдов и переинициализации. Их удобно разделить по смыслу. scroll нужен для лёгкого визуального прогресса; select — для текущего номера и связанного интерфейса; reInit — для пересоздания точек навигации, когда поменялась геометрия.

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

Если вы отправляете метрику просмотра, не считайте каждый scroll отдельным просмотром карточки. Видимость, выбор и фактическое прочтение — разные события. Для дорогих вычислений используйте завершение движения или собственное ограничение частоты. Обработчик должен быстро возвращать управление браузеру, иначе библиотека не сможет сделать прокрутку плавной.

api.on('select', updateSelectedCard);
api.on('slidesInView', updateVisibleIds);
api.on('reInit', rebuildNavigation);
api.on('scroll', updateProgressOnly);

Большая часть проблем с каруселью начинается с размеров. Изображение загружается позже текста, веб-шрифт меняет ширину заголовка, боковая панель сужает контейнер, скрытая вкладка становится видимой. Библиотека наблюдает за изменениями, но приложение должно заранее выделить разумное место под содержимое и обновить собственные элементы управления.

В мастерской SVG имеют заданный viewBox и контролируемую высоту. Для обычных img используйте корректное соотношение сторон и подходящие размеры файлов. Не отдавайте многомегабайтную фотографию ради маленькой миниатюры. При этом уменьшение файла не должно уничтожать полезные детали большого кадра: превью и исходное изображение могут быть разными ресурсами.

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

/* Зарезервированная область под фотографию */
.product-photo {
  display: block;
  width: 100%;
  aspect-ratio: 4 / 3;
  object-fit: cover;
}
.slide { min-width: 0; }

Embla не загружает каталог и не знает о правах доступа. Она получает готовую разметку. В реальном кабинете данные обычно приходят из API, а приложение решает, когда показывать skeleton, сообщение об ошибке, повтор запроса и пустой результат. Эти состояния должны быть понятны ещё до инициализации движения.

Запрос лучше отменять при уходе со страницы или смене фильтра. Иначе медленный старый ответ может заменить более свежий набор. После успешного ответа проверьте структуру данных, используйте стабильные ID и выводите пользовательский текст через textContent либо экранирование шаблонизатора. Не превращайте описание из API в произвольный HTML только ради удобства.

На сайте есть материал про TanStack Query для управления состоянием серверных данных. Карусель можно использовать как представление таких данных, сохраняя разделение обязанностей: запросы и кеш живут в своём слое, движение и фокус — в компоненте интерфейса. Наша мастерская намеренно использует локальный набор, чтобы сначала было легко проверить именно поведение ленты.

const controller = new AbortController();
try {
  const response = await fetch('/api/services', { signal: controller.signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  validateServices(data);
  replaceCarouselData(data);
} catch (error) {
  if (error.name !== 'AbortError') showRetryMessage();
}
// При уходе компонента: controller.abort();

В этой статье используется vanilla JavaScript, чтобы движение не зависело от конкретного сборщика приложения. Во Vue доступен официальный адаптер, который связывает DOM-ref и API с жизненным циклом компонента. В React, Svelte и Solid есть аналогичные варианты. Выбирайте адаптер той же основной версии, что и используемая документация.

Принцип остаётся прежним: разметка принадлежит компоненту, настройки задаются явно, а подписки не должны дублироваться после обновления данных. Для списка используйте стабильный key объекта. При изменении props решите, достаточно ли реактивного обновления адаптера или нужен собственный пересчёт после завершения обновления DOM.

Не копируйте сразу весь учебный контроллер в компонент фреймворка. Выделите управление движением, состояние данных и отображение кнопок. Затем перенесите один сценарий и проверьте его отдельно. В исходниках мастерской есть все нужные контракты, но пример адаптера ниже служит направлением интеграции, а не заявлением о выполненной проверке отдельного Vue-приложения.

// Отдельный Vue-вариант: официальный адаптер соответствующей версии.
import emblaCarouselVue from 'embla-carousel-vue';
const [emblaRef, emblaApi] = emblaCarouselVue({ loop: false });

// В шаблоне viewport получает ref="emblaRef".
// Доступ к API после создания:
emblaApi.value?.scrollNext();

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

Пример location ниже добавляется в существующий HTTPS server. Не заменяйте им весь действующий конфиг. Сохраните резервную копию, проверьте nginx -t и только затем выполните reload. Указанный пользователь www-data типичен для Debian/Ubuntu; на другой системе уточните владельца процесса и права каталогов.

Проверьте Content-Type JavaScript, доступность sources.json и отсутствие горизонтального переполнения внутри реального контейнера сайта. Относительные ссылки в мастерской позволяют разместить её под /labs/embla/. Если меняется структура каталогов, отдельно поправьте путь скачивания ZIP. Возврат предыдущего набора статических файлов должен оставаться простым и понятным.

sudo install -d -o www-data -g www-data /srv/www/embla
sudo cp -a public/. /srv/www/embla/
sudo nginx -t
sudo systemctl reload nginx
curl -I https://your-domain/labs/embla/app.js
# Вставьте location в свой HTTPS server. Скопируйте public в /srv/www/embla.
location /labs/embla/ {
    alias /srv/www/embla/;
    index index.html;
    add_header X-Content-Type-Options nosniff always;
    add_header Cache-Control "no-cache";
}
# В блоке http должен быть include /etc/nginx/mime.types;

Для отдельного демонстрационного домена Caddy может отдавать статическую папку и управлять HTTPS. Домен должен указывать на сервер, а необходимые сетевые порты должны быть доступны. Конфигурация ниже является шаблоном: замените имя домена и путь, затем проверьте её в своей установке Caddy.

После обновления откройте страницу без старого кеша и выполните короткий пользовательский маршрут: следующий шаг, миниатюра, поиск без результатов, восстановление, просмотр исходников. Одного HTTP 200 недостаточно. Сервер может вернуть HTML вместо JavaScript, а браузер откажется исполнять модуль; статический файл при этом формально доступен.

Для больших проектов используйте имена ресурсов с хешами и согласованную политику кеширования. В этой небольшой мастерской выбран простой no-cache при размещении через Nginx, чтобы обновления было легче проверять. Материалы про Caddy и Nginx на сайте помогут связать пример с ежедневной эксплуатацией сервера.

# Пример отдельного домена; замените на свой и направьте DNS к серверу.
demo.example.com {
    root * /srv/www/embla
    file_server
    encode zstd gzip
    header X-Content-Type-Options nosniff
}

В архив включены одиннадцать тестов прикладной модели: русскоязычный поиск, совместная фильтрация, неизменность исходного набора, сохранение выбранного ID после перестановки, удаление последнего элемента, пустой результат и ограничения новых карточек. Они помогают не сломать поведение каталога при изменении логики данных.

Эти тесты и сборка выполнены на Windows и в Linux-контейнере. Они не притворяются браузером и не подменяют геометрию Embla искусственными размерами. Реальное движение, расположение элементов, клавиатура и мобильная адаптация проверяются отдельно в браузере. Такой разделённый подход делает результат проверки понятным: известно, какой слой действительно исполнялся.

Для своей интеграции добавьте проверки, связанные с риском продукта. Если галерея управляет выбранной комплектацией, нужно проверить соответствие ID. Если каталог обновляется из API, важны отмена старого запроса и восстановление после ошибки. Не стоит писать тест только ради повторения того же выражения из реализации; проверяйте ожидаемый результат пользовательского действия.

npm test
npm run build

# В браузере:
# 1. services → до конца и назад
# 2. gallery → миниатюра 4
# 3. dynamic → пустой поиск → восстановить
# 4. lifecycle → reInit трижды → один переход
# 5. autoplay → ручной запуск → остановка взаимодействием

Если карусель не двигается, сначала проверьте размеры viewport и контейнера: достаточно ли контента для прокрутки, не скрыт ли блок, действительно ли слайды имеют нужный flex-basis. Для одного элемента отсутствие движения является нормальным состоянием. Следующим шагом смотрите загрузку app.js и ошибки консоли, а не добавляйте повторные init наугад.

Если после фильтра кнопки показывают старое количество шагов, проверьте обновление на reInit. Если один клик вызывает несколько одинаковых действий, ищите повторные подписки. Если длинный текст расширяет всю страницу, проверьте min-width:0 у flex-элементов и локальный overflow у кода. Если вертикальная прокрутка на телефоне стала неудобной, пересмотрите touch-action и обработчики жестов.

Если Auto Height не меняет высоту, убедитесь, что карточки не растянуты принудительно и контейнер выравнивает элементы по началу. При неожиданном поведении Autoplay проверьте версию документации и точные параметры v8. Восстанавливайте минимальный воспроизводимый сценарий: один viewport, несколько карточек и только необходимый плагин.

Полный ZIP содержит авторскую мастерскую, готовую сборку, package-lock.json, тесты, Dockerfile и варианты конфигурации сервера. Авторский код распространяется по MIT. Лицензии Embla и Bootstrap сохранены отдельно в public/LICENSES.txt; файл Embla взят из официального репозитория тега v8.6.0, поскольку npm-пакеты не включают отдельный текст лицензии.

Начните с одного полезного блока: галереи проекта или списка нескольких услуг. Оставьте автолистание выключенным, добавьте видимые кнопки и понятный номер шага. Затем проверьте длинные заголовки, один элемент, пустой набор и узкую ширину. Только после этого подключайте динамические данные, плагины и дополнительные эффекты.

Для дальнейшей работы используйте официальные настройки v8, методы API, события, Autoplay и Auto Height. Полезный результат — компонент, который человек понимает с первого взаимодействия и который команда может спокойно сопровождать после первой публикации.