灯箱
Lightbox
别名:图片灯箱大图预览图片放大预览看大图lightbox
这是什么
以压暗遮罩放大展示图片或视频的媒体浮层，原页面暂时失去交互。内容居中呈现，常配左右切换、缩放与关闭；它是媒体专用的模态框，与通用对话框的区别在于主体是可观赏的视觉内容而非表单或文案。
名词辨析
Lightbox 是媒体专用的 Modal；Modal 是通用容器。灯箱打开的是「可以看的东西」，对话框打开的是「要你处理的事」。
交互实验室
试一试，再决定怎么用打开灯箱浏览一组图片，用箭头切换并尝试缩放与关闭。
正在加载实验室…
使用时关注什么
- 01遮罩外点击或 Esc 可关闭，关闭后焦点回到缩略图
- 02图片加载失败或视频不可用时有替代说明
✓ 适用场景
- 需要查看图片细节、原图或成组照片
- 视频需要脱离页面布局专注播放
- 缩略图点击后预期放大预览
✕ 不适用场景
- 内容是表单、说明或确认操作，用 modal
- 用户需要边看边操作底层页面，用 drawer 或 popover
- 媒体本身就是页面主体，直接用画廊页或视频播放页
常见形式
图片放大
Image zoom
单图全屏放大，可缩放或平移查看细节
画廊切换
Gallery
带左右箭头与计数，连续浏览组图
视频灯箱
Video lightbox
浮层内播放视频，常自动播放并可全屏
实现要点
position: fixedobject-fit: containz-indexbackground-color遮罩固定铺满并压暗底层，媒体用 object-fit: contain 居中，避免裁切。打开时锁定页面滚动、焦点困在浮层内；左右箭头与 Esc 均可键盘操作。切换用轻微淡入而非大幅位移，尊重 prefers-reduced-motion。
平台 API
<dialog>role="dialog"aria-modal="true"代码里叫什么
同一控件在不同体系里的叫号——用对名字，Prompt 和检索才准。
| 体系 | 名称 |
|---|---|
| ARIA APG | Dialog (Modal) |
| yet-another-react-lightbox | Lightbox |
| MUI | Dialog (full-screen image) |
相关概念
覆盖在页面之上、带半透明遮罩的对话框，打断用户当前流程，要求先完成弹窗内的任务或决策。 遮罩阻断与底层页面的交互，焦点被暂时困在弹窗内，是容器类浮层中打断程度最高的一种。
组件替代方案用水平滑动的轨道展示一组内容，同一时刻只突出一项，其余滑出视野或露出边缘作暗示。通过分页点、 箭头或自动播放切换，常用于首屏 Banner、图片画廊与推荐位。适合「一组同类内容、逐个浏览」的场景， 不适合需要并排对照的信息。
组件搭配使用从屏幕边缘（多为右侧或左侧）滑入、通常带遮罩的面板。比模态框轻：能承载较长内容又不离开当前页面， 关闭后原样回到上下文；移动端常以左滑导航或底部抽屉的形式出现。
组件相似概念容易混淆
modal 承载通用任务与文案，lightbox 专用于放大观赏媒体
carousel 在页面内轮播，lightbox 在压暗遮罩上全屏展示