# 媒体查看器组件 PRD

版本：v0.2  
状态：当前正式需求

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-08-03 | v0.1 | 初始创建 / 合并定义 | 建立图片、视频、PDF 等单项资料的查看对象。 |
| 2026-08-03 | v0.2 | 合并旧 PRD / 重大范围确认 | 合并原“图片查看器组件”交互与验收；确认图片支持全屏缩放和平移，其他媒体仅按其原生阅读/播放能力展示。 |

## 1. 定义与目标

唯一标识：`media-viewer`。用于查看调用方指定的单项图片、视频或 PDF；不承担多图画廊、内容筛选、下载、分享、收藏、编辑或独立详情页。

图片查看是 P0 核心能力：顾客可全屏阅读户型图等细节，关闭后可靠回到调用位置。视频和 PDF 可使用本组件的单项打开、阅读/播放、关闭与局部失败规则，但不自动继承图片缩放手势。

## 2. 内容与调用边界

| 输入 | 必需性 | 规则 |
| --- | --- | --- |
| 媒体地址、类型、名称 | 必需 | 由调用方提供；类型仅限图片、视频、PDF。 |
| 替代文字、说明 | 可选 | 图片应提供可访问名称。 |
| 当前对象稳定标识 | 必需 | 用于关闭后恢复调用上下文，不自行改选其他对象。 |

- 不支持类型显示“不可查看”与关闭，不造成整页错误。
- 图片初始按视口完整适配并保持比例；手机支持双指缩放、放大后单指平移；PAD/PC 支持明确控件或滚轮缩放、放大后拖动。
- 图片提供恢复适配和明确关闭；键盘环境支持 `Esc` 关闭。双击、下滑关闭、背景点击关闭均不触发。
- 不做多图切换、缩略图栏、自动播放、下载、分享、批注、旋转、裁剪、OCR 或 AI 解读。

## 3. 核心流程与状态

1. 顾客从调用方打开单项媒体；查看器在当前页面上方承载，背景页面不可滚动或误操作。
2. 图片加载成功后进入适配状态，顾客可放大、平移、恢复适配或关闭；视频/PDF 提供与类型相符的播放/阅读和关闭。
3. 任一媒体加载失败仅在查看器内显示局部错误和关闭；不使用其他媒体补位，不升级为 403、404 或全局错误。
4. 关闭后恢复调用方筛选、展示模式、当前对象、滚动位置和键盘焦点。

| 状态 | 处理 |
| --- | --- |
| 加载中 | 保持可关闭，显示局部加载状态。 |
| 图片适配 / 已放大 | 保持比例；已放大时允许平移，关闭与恢复始终可达。 |
| 不支持 / 加载失败 | 展示可理解的局部提示和关闭动作。 |
| 已关闭 | 完整恢复调用方可安全恢复的状态。 |

## 4. UI、响应式与设计系统

采用 **VISTA C 图片栏/弹窗** 语义：大图可清除非必要 UI 后缩放和平移，控件不得覆盖关键图纸或无法关闭。视频、PDF 的标识和控件应与媒体类型相符。320px、375px、768px、1024px、1440px 下均保持可关闭；图片至少在 200% 放大时稳定可读。精确缩放步长、最大值和控件视觉为 **待设计系统补充**。

## 5. 验收

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-MEDIA-01 | 有效图片 | 手机打开 | 按视口完整适配，双指缩放和放大后平移稳定可用。 |
| AC-MEDIA-02 | 图片查看器已打开 | PAD/PC 缩放、拖动或恢复适配 | 操作可用且关闭始终可达。 |
| AC-MEDIA-03 | 图片已放大和平移 | 顾客关闭或按 `Esc` | 返回原页面并恢复调用状态。 |
| AC-MEDIA-04 | 有效视频或 PDF | 顾客打开 | 只展示匹配类型的阅读/播放控件，不误用图片手势。 |
| AC-MEDIA-05 | 媒体无效、类型不支持或加载失败 | 顾客查看 | 仅查看器局部失败，可关闭，调用页面继续可用。 |

## 6. 明确不做与待确认

- 不做画廊、多媒体序列切换、下载、分享、收藏、编辑、AI 解读或独立媒体页面。
- 视频/PDF 的进阶控制能力、图片精确缩放数值和视觉规格待设计系统/技术设计补充。