Версия источника: f50fde03c6615c45530b5ab681a9b585c0c454d7
Синхронизировано: 2026-11-17T23:57:59.493Z
Источник: https://github.com/sergey-from-riders/vibecoding-base/tree/f50fde03c6615c45530b5ab681a9b585c0c454d7

<a id="interface-image-viewer"></a>

# Просмотр изображений

## Коротко

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

## Плохо

```text
В карточке две группы: «Помещения» и «Территория».
Клик по третьему фото «Помещений» → новая вкладка с файлом.
Следующая фотография → случайный снимок из «Территории».
Подпись поверх изображения закрывает половину снимка.
Длинный текст обрезан навсегда; прокрутка двигает страницу сзади.
Закрыть окно можно только маленьким крестиком мышью.
```

## Хорошо

```text
В карточке две группы: «Помещения» и «Территория».
Клик по третьему фото «Помещений» → просмотр «3 / 6» этой группы.
Свайп, стрелки или кнопки → соседнее фото в «Помещениях».
Фото целиком; над ним счетчик и закрытие, под ним краткая подпись.
«Читать полностью» → описание ниже фото, прокрутка внутри окна.
Закрытие → та же позиция страницы и фокус на исходном фото.
```

## Почему

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

## Когда применять

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

Декоративные фоны, иконки, логотипы и баннеры с собственным переходом не становятся галереей автоматически. У изображения-ссылки должно быть одно понятное основное действие; не открывайте одновременно просмотр и карточку товара. Управление ресурсами, обложкой, порядком и описаниями в админке остается в связанном правиле `interface.media-gallery`.

Модальный просмотр всех фотографий галереи и расположение подписей — требования этого справочника. WAI-ARIA APG и WCAG 2.2 задают основания для доступного взаимодействия, но не требуют превращать каждое изображение любого сайта в popup.

### Открытие и группы

- Нажатие на любое фото галереи открывает именно выбранный элемент, а не всегда первый. Элемент открытия доступен с клавиатуры и имеет понятное имя. При отказе JavaScript остается обычная ссылка на разрешенный ресурс изображения или другой предусмотренный путь просмотра.
- Группа определяется явно, например стабильным `gallery_id`; позиция связана с ID изображения и заданным порядком. Не объединяйте все `<img>` страницы в одну группу. Перелистывание не выходит в соседнюю карточку, альбом или группу; счетчик «3 / 6» относится только к текущей группе.
- Для группы из нескольких изображений доступны горизонтальный свайп, видимые кнопки «Предыдущее» / «Следующее» и клавиши влево/вправо внутри просмотрщика. Не перехватывайте эти клавиши в полях ввода или там, где они нужны для собственного управления. Автоматическая смена фотографий выключена; поведение на первом и последнем кадре определено явно.
- Перелистывание плавно показывает направление. При ограничении движения пространственная анимация отключается. Вертикальная прокрутка описания не меняет фотографию, а панорамирование увеличенного снимка имеет приоритет перед перелистыванием. Жест не закрывает окно и не активирует ссылку случайно.

### Фото и подпись

- Модальное окно использует доступную область экрана; на телефоне — практически всё окно браузера. Снимок первоначально помещается целиком с сохранением пропорций, без обрезания, например через `object-fit: contain`. Управление и краткая подпись не должны вытеснять его с первого экрана.
- Короткая подпись располагается над или под фотографией, в отдельной области. Не накладывайте большой текстовый блок на снимок. Если подписи нет, не показывайте пустую плашку. Минималистичное оформление сохраняет читаемый шрифт, контраст и заметное закрытие.
- Длинную подпись показывайте кратко, например двумя-тремя строками, с явной кнопкой «Читать полностью». Число строк — решение проекта, а не норма WCAG. При увеличении шрифта или в низком окне сокращение должно сохранять место фотографии и доступность полного текста.
- Полное описание раскрывается ниже снимка и читается вертикальной прокруткой внутри полноэкранного окна просмотра. Оно не перекрывает изображение и не обрезается окончательно. Предпочтительна одна понятная область вертикальной прокрутки, без маленького вложенного поля текста. Кнопка закрытия остается доступной; после сворачивания или смены снимка пользователь не остается в пустом конце прокрутки.
- Подпись и `alt` решают разные задачи: `alt` кратко передает смысл изображения в контексте, подпись может содержать расширенный рассказ и авторство. Не копируйте длинное описание целиком в доступное имя кнопки или диалога. При смене фото синхронно меняются подпись, `alt` и счетчик; отсутствие подписи не оставляет текст предыдущего снимка.

### Управление, увеличение и ошибки

- Окно имеет семантику именованного модального диалога. При открытии фокус переходит внутрь, Tab и Shift+Tab остаются внутри, фон недоступен для взаимодействия. Есть видимая кнопка закрытия и Escape; после закрытия возвращаются фокус на исходный элемент и прежняя позиция страницы. Если элемент удален, выберите логичное место возврата.
- Если доступно увеличение, добавьте управление масштабом и возврат к виду «целиком». Сохраняйте браузерный zoom; не запрещайте масштабирование страницы глобально. Не выдавайте увеличение низкого разрешения за загрузку более детального снимка.
- Полноэкранный диалог в окне браузера работает сам по себе. Настоящий Fullscreen API — дополнительная возможность по явной кнопке: проверяйте поддержку и обрабатывайте отказ. Запрашивайте полноэкранный режим для всего просмотрщика, включая подпись и управление, а не только для `<img>`. После выхода из системного fullscreen обычное окно просмотра остается работоспособным; закрытие также корректно завершает fullscreen.
- При загрузке резервируйте область фото и показывайте понятное состояние. Ошибка отдельного ресурса не блокирует закрытие и переход к другим фото. Загружайте подходящий размер текущего снимка, при необходимости соседние, без предварительной загрузки всех оригиналов большого альбома. Нельзя показывать предыдущее изображение как будто это новый успешно загруженный кадр.

## Пример применения

В вымышленной карточке объекта шесть фотографий помещений и отдельная группа территории. Посетитель открывает третью фотографию помещений и видит «3 / 6». Под фото — короткая подпись и «Читать полностью». После раскрытия длинное описание читается прокруткой вниз в том же окне. Закрытие возвращает посетителя к третьей миниатюре; следующая фотография никогда не подмешивается из территории.

## Как проверить

- Откройте каждую фотографию двух разных групп, включая первую и последнюю. Сверьте ID, порядок, счетчик и подпись. Проверьте пустую группу и одиночное изображение.
- Пролистайте свайпами, кнопками и клавишами; проверьте отмененный жест, частые переключения и уменьшение движения. Прокрутка текста и панорамирование при увеличении не переключают кадр.
- Используйте подписи без текста, в одну строку и в несколько абзацев. На ширине 320–390 px, в альбомной ориентации и при увеличении текста снимок виден вначале, полный текст достижим прокруткой, закрытие доступно. Смена фото не сохраняет чужую подпись или пустую позицию прокрутки.
- Проверьте портретный, панорамный и маленький снимки: пропорции сохранены, начальный вид не обрезан. Сетевой отказ и медленная загрузка не лишают управления; без JavaScript работает предусмотренный резервный путь.
- Пройдите открытие и закрытие клавиатурой и скринридером: имя диалога, положение фокуса, недоступность фона, Escape, возврат фокуса и прокрутки. Полное описание можно прочитать, не выдавая его целиком за имя окна.
- Если реализован Fullscreen API, проверьте отказ запроса, вход по кнопке, показ полного текста и управление внутри fullscreen, затем выход штатным способом браузера. Доступность API не является условием обычного модального просмотра.
- Зафиксируйте проверенные браузеры, устройства и результаты. Схемы выше — критерии поведения на вымышленных данных, а не отчет о реализованном просмотрщике конкретного сайта.

## Человек

Определяет группы и порядок фотографий, пишет подписи и проверяет, что текст не мешает рассматривать снимок. Принимает поведение раскрытого описания и увеличения на телефоне.

## Агент

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

## Источники

- [WAI-ARIA APG: Modal Dialog Pattern — фокус, фон и закрытие](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
- [WAI-ARIA APG: Carousel Pattern — управление последовательностью](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/)
- [W3C, WCAG 2.2: Dragging Movements — альтернатива жесту](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)
- [MDN: requestFullscreen — явное действие, разрешения и отказ](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullscreen)
- [MDN: prefers-reduced-motion — уменьшение движения](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion)
- [W3C WAI: alt Decision Tree — описание по функции изображения](https://www.w3.org/WAI/tutorials/images/decision-tree/)

Уровень: Обязательно. Опубликовано: 2026-11-17. Проверено: 2026-11-17. Изменено: 2026-11-18.

[Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/f50fde03c6615c45530b5ab681a9b585c0c454d7/registry/standards/ui/admin-interface/rules/image-viewer.md)
