变体媒体模块：让选择、图片、视频与 3D 保持一致
变体媒体模块帮助顾客确认“我当前选中的配置实际是什么样”。它连接商品或变体数据、图片、视频、3D 等媒体、当前选择状态和购买区，而不是一个与选项无关的独立轮播。
变体媒体 = 当前选择 × 对应媒体集合 × 浏览状态 × 回退规则
先定义媒体归属
同一商品的媒体可能适用于全部变体，也可能只描述一种颜色、材质或配置。每项媒体都需要明确归属，不能仅根据文件顺序或模糊的替代文字猜测。
| 层次 | 作用 | 示例 |
|---|---|---|
| 商品级媒体 | 说明所有变体共有的结构或能力 | 功能演示、整体尺寸、通用安装视频 |
| 变体级媒体 | 说明当前选择的可见差异 | 颜色、面料、配件组合 |
| 购买辅助媒体 | 帮助确认适配或操作方式 | 尺寸图、使用姿势、安装步骤 |
媒体归属与媒体形式是两件事。一段视频可以属于整个商品，也可以只属于某个变体；3D 模型同样需要说明是否随当前选择变化。
切换变体时保持同一事实状态
变体变化后，媒体、标题或选项标签、价格、库存和购买动作应指向同一选择。异步加载期间保留明确的过渡状态，较早请求晚返回时不能覆盖较新的选择。
一次切换通常包含：
- 顾客选择一个有效选项组合；
- 页面确定目标变体及其可用状态；
- 媒体区加载或恢复该变体的媒体集合；
- 当前媒体位置按规则保留、重置或映射；
- 价格、库存、链接和购买表单同步到同一变体；
- 加载失败时保留可理解的回退内容和重试路径。
不要只更新缩略图高亮。顾客能够看到新颜色图片，但加入购物车仍提交旧变体，是比媒体缺失更严重的状态分裂。
回退规则需要预先决定
- 当前变体有专属媒体：优先展示，并允许访问适用的商品级媒体；
- 当前变体没有专属媒体：回退到变体主图或商品通用媒体，同时避免暗示错误颜色；
- 只有一项媒体：退化为单媒体卡片，移除无意义的分页和左右按钮；
- 视频或 3D 不可用：提供预览图、说明或替代媒体，不留下空面板；
- 媒体加载失败：保持商品身份和购买区可用，给出重试或继续查看其他媒体的方式。
桌面端和移动端可以采用不同布局或减少次要媒体，但不应改变当前变体身份。移动端只展示一张图时，也应明确它为何代表当前选择。
图片、视频与 3D 的共同要求
- 图片保留准确替代文字、尺寸和响应式资源；
- 视频提供控制、字幕或同等信息，非必要内容不强制自动播放；
- 3D 提供进入、退出和设备不支持时的替代路径；
- 缩略图与主媒体之间的当前状态对键盘和辅助技术可理解；
- 全屏、放大和媒体切换不会遮挡退出入口或破坏焦点顺序；
- 首屏优先媒体与其余媒体采用不同加载优先级，避免一次下载全部高成本资源。
具体媒体形态见Media Gallery，商品视频的内容职责见商品视频。
映射到 Shopify
Shopify Product media 可以包含图片、外部视频（YouTube 或 Vimeo）、视频和 3D 模型。在 Liquid 中，variant.featured_media 返回关联到该变体的第一项媒体；需要为一个变体展示一组专属媒体时，应先核实所用数据来源能否表达这种归属，不能默认平台已提供完整的变体媒体集合。Theme 负责选择适合当前页面和设备的呈现方式，并在 Variant 变化时保持媒体与购买状态一致。媒体来自商品、变体关联数据或其他经确认的内容来源时，应分别记录，不把某个主题的字段约定写成平台通则。
验证一次媒体切换
选择至少两个媒体集合明显不同的变体，连续快速切换并观察主媒体、缩略图、价格、库存、URL 和购买表单。随后覆盖只有一张图、没有专属媒体、视频失败、3D 不支持、移动端和减少动态效果等条件。最终加入购物车，确认行项目确实对应最后看到的选择。
固定版本主题实现
- Dawn 商品媒体、Horizon 媒体放大与热点：两个主题的商品媒体画廊与变体联动实现。
固定基线为 Dawn v15.3.0 与 Horizon 4.2.0；结论限于这两个提交，均为静态源码分析，未运行验证。