业务背景与大图预览灯箱的设计痛点

在现代电子商务平台（如亚马逊、淘宝商品主图相册）、数字内容社区（如小红书、Behance、Instagram）、企业协同文档管理（如 Google Drive 附件预览、飞书画板）以及医疗与 CAD 工业图纸审查系统中，大图预览灯箱与画廊查看器（Image Lightbox & Gallery Viewer） 是承载高保真图像检验、细节缩放审查与连续切图浏览的核心交互容器。

相较于普通的图片卡片或简单居中弹窗，大图预览灯箱在 Figma 中的企业级架构落地存在诸多深层次工程痛点：

1. 多宽高比（Aspect Ratio）原图自适应居中与防溢出机制：用户的真实图片包含横图（16:9、4:3）、竖图（9:16、3:4）、全景超长图甚至超高长图。传统设计中拉伸或固定尺寸极易导致图像挤压变形；若简单设置居中，竖图往往会超出屏幕顶部或遮挡顶部关闭按钮。
2. 双向缩略图导轨（Thumbnail Strip）与主图焦点的动态同步：底部缩略图通常采用横向滚动视口（Horizontal Scroll）。当用户在主图点击“下一张”时，底部缩略图的当前激活边框（Active Ring）与滚动偏移动作必须精准跟随；反之，点击缩略图也需瞬时切换主视口，而在 Figma 中若采用散落变体容易引发爆炸式嵌套。
3. 悬浮操作工具栏（Toolbar）与视口控制解耦：现代灯箱通常提供放大（Zoom In）、缩小（Zoom Out）、1:1 像素复位、顺逆时针 90° 旋转、水平镜像翻转、下载与全屏切换等控制项。工具栏必须保持悬浮吸顶或居底，且不能随主图缩放而发生几何位移。
4. 全屏沉浸遮罩穿透与键盘快捷键交互断层：桌面端需支持 Esc 退出、ArrowLeft / ArrowRight 前后切图、空格键缩放；移动端则需支持双指捏合（Pinch）与轻扫关闭。在 Dev Mode 开发模式 交付时，前端常因缺乏图元坐标锚点与缩放变换原点（Transform Origin）而导致还原度严重打折。

借助 Auto Layout 动态设计、图层效果与滤镜、覆盖层 Overlay 原型机制 与 Figma Variables 变量系统，我们可以打造一套兼顾极端比例容错与高保真动效的现代化画廊灯箱组件架构。

---

架构选型对比：画廊灯箱组件实现方案评估

在 Figma 中构建大图预览与画廊灯箱系统，主要有以下三种架构选型：

评估维度	方案 A：静态画板多页面克隆模式（Page Cloning）	方案 B：纯 Open Overlay 居中弹窗挂载（Basic Modal）	方案 C：全屏暗色视口 + 导轨插槽 + Variables 状态机解耦架构（推荐）
底层实现机制	为每张大图建立一个完整的独立 Frame 画板，连线跳转	使用 Figma 原型自带的 Open overlay 居中弹窗触发器	根容器采用 100vw/100vh 全屏容器，主图视口、悬浮控制条、缩略图导轨三层解耦，通过数值变量驱动索引与旋转角度
多图扩展维护成本	极高。若相册有 20 张图片，修改一次控制栏样式需同步 20 个画板	中等。每张图片仍需单独配置弹窗 Frame，改动时容易漏改	极低。单一灯箱母版，通过替换图片属性插槽或切换图片索引变量，自动适配任意图片数量
缩放与旋转动态模拟	无法做到平滑连续缩放与旋转微交互	仅能做预设的固定尺寸弹窗，无法动态计算角度	极佳。借助变量计算与 Smart Animate 智能动画，可丝滑演示 90° 旋转与 100%~300% 动态阶梯缩放
缩略图双向联动	只能手动连线，线网交织极易产生死链	无法在弹窗内部做到动态滚轴与激活态位移	完美。缩略图组件根据当前 activeImageIndex 变量自动高亮匹配项，并支持点击修改变量回写
Dev Mode 前端代码转化	代码零碎片化，缺少整体容器拓扑结构	仅能生成居中 fixed 样式，缺少事件与状态抽象	卓越。精确映射为 PhotoSwipe、Yet Another React Lightbox 或 Radix Dialog 的配置规范与 CSS 属性

因此，方案 C（全屏暗色视口 + 导轨插槽 + Variables 状态机解耦架构） 是大型团队与高精产品设计的最佳选择。

---

步骤一：全屏沉浸式容器与多态遮罩（Backdrop）搭建

灯箱的核心基础是一个具备多端自适应能力的沉浸式全屏舞台（Viewport Stage）。

1. 视口全屏容器拓扑

1. 新建一个 Frame，设置尺寸为 1440 × 900（桌面端标准基准视口），命名为 Lightbox-Root。
2. 约束设置：将横向与纵向约束设为 Scale & Scale，或在嵌套布局中设置为 Fill container，使其具备流体响应式弹性。
3. 容器布局规划采用垂直三段式 Auto Layout（或绝对定位图层覆盖）：
   • Header-Bar：高度 56px，顶部对齐（包含图片序号 3 / 12、文件名与关闭 Esc 按钮）。
   • Stage-Viewport：高度 Fill container，居中对齐，作为主图承载视口。
   • Footer-Control：高度 Hug contents，底部对齐（包含悬浮操作栏与缩略图导轨）。

2. 沉浸式暗色遮罩与背景模糊

为了隔绝底层画面的干扰并提升主体聚光感：

• 背景色填充：使用半透明暗黑变量 rgba(15, 23, 42, 0.92)（Slate 900 伴随 92% 不透明度）。在暗色模式与浅色模式下均推荐保持沉浸暗色底。
• 背景模糊滤镜（Background Blur）：在 图层效果与滤镜 中添加 Background blur: 24px。当灯箱以 Overlay 方式覆盖在业务主界面上方时，能够营造精致的磨砂玻璃光泽。
• 防止误触穿透：确保 Lightbox-Root 开启了填充与点击阻断，避免点击背景空白区时意外穿透到底层操作表单。

---

步骤二：主图自适应视口与悬浮工具栏解耦

1. 主图容器约束与极端比例防变形

将真实大图放入 Stage-Viewport 视口中：

1. 在视口中央放置一个子容器 Main-Image-Wrapper。
2. 属性设置：
   • Resizing：水平设为 Hug contents，垂直设为 Hug contents。
   • Max Width：设置为 calc(100% - 160px)（为左右翻页箭头预留安全点击区）。
   • Max Height：设置为 calc(100% - 180px)（为顶部标题栏与底部工具栏预留空间，避免竖向长图把控制栏挤出视口）。
3. 内部图片图层设置：
   • 填充方式选择 Fit（适应）而非 Fill，确保无论图片原始长宽比是 1:1、4:3 还是 9:16，均完整呈现在安全视口中，严禁图片被意外裁剪。参考 图片置入与调整技巧。

2. 悬浮悬臂操作工具栏（Floating Toolbar）

在 Stage-Viewport 下方或居底悬浮放置一个独立的快捷操作栏 Lightbox-Toolbar：

• 布局方式：Auto Layout 水平排列，间距 8px，内边距 8px 16px。
• 背景与阴影：背景填充 rgba(30, 41, 59, 0.85)（深色胶囊），圆角设为 999px，添加 Drop shadow: Y=4, Blur=16, Color=rgba(0,0,0,0.4)。
• 操作项原子插槽：
  1. btn-zoom-in：放大（每次步进 +25%）。
  2. btn-zoom-out：缩小（每次步进 -25%）。
  3. btn-zoom-reset：1:1 像素居中复位。
  4. divider：竖向分割线（1px 高 16px，颜色 #475569）。
  5. btn-rotate-cw：顺时针旋转 90°。
  6. btn-flip-h：水平镜像翻转。
  7. btn-download：一键下载原图。
  8. btn-fullscreen：切换全屏。

每个操作按钮统一采用 32 × 32px 的触控热区，内部图标采用 20 × 20px 的统一组件属性（Instance Swap），确保光标悬停与禁用态具有明确的对比反馈。

---

步骤三：底部缩略图胶囊导轨（Thumbnail Strip）联动

灯箱底部通常包含多张缩略图的连续排版导轨，让用户一览全部图片并快速跃迁。

1. 缩略图单元（Thumbnail Unit）原子组件规范

创建 _Thumbnail-Item 原子组件，包含两种关键变体状态：

• Default（未激活）：
  • 尺寸：56 × 56px，圆角 6px。
  • 图片填充方式：Fill（居中裁剪保证统一规格）。
  • 遮罩覆盖：覆盖一层 rgba(0, 0, 0, 0.45) 的半透明暗层，降低未激活项视觉噪音。
  • 边框：无。
• Active（当前激活项）：
  • 遮罩覆盖：移除暗层，保持 100% 原始饱和度。
  • 边框：添加 2px 外描边或内描边，颜色绑定 primary-default（如 #38BDF8 或高亮白 #FFFFFF）。
  • 动效微调：可略微等比放大 1.05 倍，形成悬浮高亮聚焦点。

2. 横向滚动视口组装

1. 将 8~12 个 _Thumbnail-Item 实例排列在 Auto Layout 水平容器中，间距设为 8px。
2. 外层包裹一个固定宽度（如 720px）的 Frame，开启 带滚动溢出的高级原型制作 中的 Horizontal scrolling（横向滚动）。
3. 勾选 Clip content，两端添加渐变羽化遮罩（Fade Mask），提示用户后方存在更多可横滑图片。

---

步骤四：Variables 驱动的大图画廊状态机与交互原型

借助 Figma Variables 变量系统，我们无需画 50 个画板，就能在单一画板内实现全套大图翻页、旋转与缩放计算。

1. 变量拓扑与命名字典

在本地变量面板中创建 LightboxState 命名空间：

变量名称	数据类型	默认初始值	业务逻辑与驱动图层
gallery.currentIndex	Number	1	当前浏览的图片索引序号（1 ~ N）
gallery.totalCount	Number	8	相册图片总数
gallery.zoomScale	Number	1.0	当前缩放比率（1.0 ~ 3.0，对应 100% ~ 300%）
gallery.rotationDeg	Number	0	当前旋转度数（0, 90, 180, 270）
gallery.isFlipped	Boolean	false	是否处于水平镜像翻转态
gallery.showToolbar	Boolean	true	是否展示悬浮控制栏（点击主图可隐藏/唤起）

2. 原型动作绑定实操

1. 左右箭头切图（Previous / Next）：
   • 选中右侧大箭头 btn-next，添加交互 On click -> Set variable：
     • 条件判断：若 gallery.currentIndex < gallery.totalCount，则执行 gallery.currentIndex = gallery.currentIndex + 1；若已到达末尾，则循环回到 1。
     • 同时重置缩放与旋转：gallery.zoomScale = 1.0，gallery.rotationDeg = 0。
2. 顶部序号动态文本显示：
   • 将标题栏中的文本 "3 / 8" 解耦为三个文本图层：CurrentNumber、/、TotalNumber。
   • 选中 CurrentNumber 文本，在文本属性右侧点击绑定变量图标，绑定到 gallery.currentIndex。当翻页时，文本数字将自动实时变更。
3. 放大缩小按钮计算：
   • 选中 btn-zoom-in，添加 On click -> Set variable：gallery.zoomScale = min(gallery.zoomScale + 0.25, 3.0)。
   • 选中 btn-zoom-out，添加 On click -> Set variable：gallery.zoomScale = max(gallery.zoomScale - 0.25, 0.5)。
   • 将 Main-Image-Wrapper 的宽度或缩放倍率直接与 gallery.zoomScale 进行联动。
4. 90° 顺时针旋转：
   • 选中 btn-rotate-cw，添加 On click -> Set variable：gallery.rotationDeg = (gallery.rotationDeg + 90) % 360。
5. 覆盖层呼出与关闭：
   • 在主界面网格图片上添加 On click -> Open overlay，选择 Lightbox-Root，勾选 Close when clicking outside 与 Add background blur，详情查阅 覆盖层 Overlay 原型指南。

---

步骤五：Dev Mode 交付规范与前端 PhotoSwipe / React 代码落地

在 Dev Mode 开发模式 下，为前端工程师提供清晰的几何标定、无障碍 ARIA 属性与业界标准库（PhotoSwipe v5 / Yet Another React Lightbox）对接规范。

1. PhotoSwipe v5 标准化初始化配置（TypeScript）

前端开发通常不会重复造轮子编写复杂的触控手势逻辑，而是采用成熟的开源灯箱引擎 PhotoSwipe：

import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/style.css';

interface GalleryItem {
  largeURL: string;
  thumbnailURL: string;
  width: number;
  height: number;
  title?: string;
  altText: string;
}

export function initProductGallery(gallerySelector: string, items: GalleryItem[]) {
  const lightbox = new PhotoSwipeLightbox({
    gallery: gallerySelector,
    children: 'a',
    pswpModule: () => import('photoswipe'),
    
    // 严格对照 Figma 设计系统 Token 映射参数
    bgOpacity: 0.92,                // Figma: 背景遮罩不透明度 92%
    spacing: 0.12,                  // 幻灯片之间的滑动间隙比率
    allowPanToNext: true,           // 缩放后允许拖拽滑向下一张
    loop: true,                     // 循环无缝轮播
    wheelToZoom: true,              // 滚轮缩放支持
    pinchToClose: true,             // 双指轻捏关闭支持
    closeOnVerticalDrag: true,      // 移动端垂直下拉手势退出
    
    // 注入自定义悬浮工具栏插槽 (匹配 Figma Lightbox-Toolbar)
    paddingFn: (viewportSize) => {
      return {
        top: 56,                    // Figma: Header-Bar 避让高度
        bottom: 84,                 // Figma: Toolbar + Thumbnail 避让高度
        left: 20,
        right: 20,
      };
    },
  });

  // 注册顺时针旋转自定义插件
  lightbox.on('uiRegister', () => {
    lightbox.pswp?.ui?.registerElement({
      name: 'custom-rotate-button',
      ariaLabel: '顺时针旋转90度',
      order: 8,
      isButton: true,
      html: '<svg viewBox="0 0 24 24"><path d="M12 4V1L8 5l4 4V6c3.31 0 6 2.69 6 6 0 1.01-.25 1.97-.7 2.8l1.46 1.46A7.93 7.93 0 0020 12c0-4.42-3.58-8-8-8zm0 14c-3.31 0-6-2.69-6-6 0-1.01.25-1.97.7-2.8L5.24 7.74A7.93 7.93 0 004 12c0 4.42 3.58 8 8 8v3l4-4-4-4v3z"/></svg>',
      onClick: (event, el, pswp) => {
        const currSlide = pswp.currSlide;
        if (!currSlide || !currSlide.content) return;
        const img = currSlide.content.element as HTMLImageElement;
        const currentRot = Number(img.dataset.rotation || '0');
        const nextRot = (currentRot + 90) % 360;
        img.dataset.rotation = String(nextRot);
        img.style.transform = `rotate(${nextRot}deg)`;
        img.style.transition = 'transform 0.25s cubic-bezier(0.4, 0, 0.2, 1)';
      },
    });
  });

  lightbox.init();
  return lightbox;
}

更多前端交付转换规范与 CSS Transform 映射，可参阅 Figma 转换为 HTML 规范手册。

---

设计系统 Token 规范与画廊灯箱高频避坑清单

1. 设计系统 Tokens 映射速查

Token 路径	默认值	语义用途	对应 CSS 自定义属性
lightbox.backdrop.color	rgba(15, 23, 42, 0.92)	全屏背景暗色透明度	--lightbox-backdrop: rgba(15, 23, 42, 0.92);
lightbox.backdrop.blur	24px	背景磨砂玻璃模糊度	--lightbox-blur: 24px;
lightbox.toolbar.bg	rgba(30, 41, 59, 0.85)	悬浮控制栏胶囊背景	--lightbox-toolbar-bg
lightbox.toolbar.radius	999px	控制栏全圆角	--lightbox-toolbar-radius: 999px;
lightbox.thumbnail.size	56px	底部缩略图基准尺寸	--lightbox-thumb-size: 56px;
lightbox.thumbnail.border-active	#38BDF8	激活缩略图外边框高亮	--lightbox-thumb-active-border
lightbox.duration.transition	250ms	缩放与旋转过渡时长	--lightbox-transition: 250ms;

更多系统级 Token 配置规范，请参阅 设计系统 Tokens 规范速查。

2. 画廊灯箱高频踩坑防御指南（Troubleshooting）

• ⚠️ 避免置入未压缩超高分辨率原图导致 Figma 内存溢出：如果在设计画廊时，将 10~20 张每张高达 20MB 的 4K/8K 摄影原图直接塞入画板，会迅速撑满 Figma 浏览器的 2GB 内存配额，引发崩溃或页面重载。在设计阶段，建议将预览切图通过 TinyPNG 或 WebP 格式压缩至 500KB 以内，原图链接保留在 Dev Mode 属性面板中，排查方法查阅 文件无法打开与内存排查指南。
• ⚠️ 切忌在图片图层上直接使用固定宽高（Fixed Width / Fixed Height）：必须使用 Fit 保持长宽比，并结合外层容器的 Max Width 与 Max Height 限制，否则在多设备断点自适应时图片会被强行压扁变形。
• ⚠️ 必须配置无障碍快捷键键盘导航（a11y）：确保灯箱组件包含清晰的 aria-modal="true"、role="dialog" 标注，并在设计说明中明确 Esc 键对应关闭、左右方向键对应切图，快捷键规范见 Figma 常用快捷键速查表。
• ⚠️ 缩略图导轨避免过度嵌套 Auto Layout：缩略图列表建议单层水平 Auto Layout，避免在每个 item 内部嵌套超过 3 层 Frame，降低画布渲染负荷，更多调优方案参考 常见故障排查手册。