# 图片查看器组件 PRD

版本：v0.1
状态：第一阶段 MVP 范围已确认；响应式交互原型已制作，待开发
组件标识：C-COM-02

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-29 | v0.1 | 初始创建 / 重大范围确认 | 定义户型图全屏查看、移动端双指缩放与平移、PAD/PC 缩放与拖动、恢复适配、关闭和状态恢复；明确不做双击缩放及画廊能力。 |
| 2026-07-29 | v0.1 | 非重大：原型交付同步 | 户型页面已实现全屏查看、缩放、平移、恢复适配、关闭和原位置恢复的交互原型。 |

## 1. 文档目的与适用对象

本文档用于产品、设计、开发、测试及 Codex 统一实现 MVP 户型图大图查看能力。

MVP 使用位置：

- 户型列表页
- M-10 户型卡片列表 Widget

图片查看器是页面内部通用组件，不是 Widget，不进入 A 端 Widget 注册、排序或内容配置。

## 2. 产品背景与目标

户型图包含大量细节，卡片缩略图无法完成阅读任务。图片查看器需要让移动端用户可靠放大和平移，同时保证随时能够关闭并回到原户型位置。

本组件目标：

1. 全屏展示当前户型图。
2. 支持移动端和 PAD/PC 的基本缩放、平移与恢复适配。
3. 关闭后完整恢复调用页面状态。
4. 将加载失败限制在查看器内部，不破坏户型列表。

## 3. 版本范围与边界

### 3.1 MVP 包含

- 单张户型图全屏查看。
- 图片加载、成功和失败状态。
- 手机双指缩放、放大后平移、恢复适配和关闭。
- PAD/PC 缩放控件或滚轮缩放、放大后拖动、恢复适配和关闭。
- 键盘环境使用 `Esc` 关闭。
- 关闭后恢复筛选、展示模式、当前卡片和滚动位置。

### 3.2 MVP 明确不做

- 多图画廊、缩略图栏、左右切换和自动播放。
- 双击缩放、下滑关闭和点击背景关闭。
- 下载、分享、收藏、批注、旋转、裁剪或编辑。
- 图片识别、OCR、AI 解读或户型比较。
- 独立页面、独立 Widget 或单户型详情页。

## 4. 用户角色与核心场景

| 用户角色 | 核心场景 | 用户目标 |
| --- | --- | --- |
| 顾客 / 外部访问者 | 在户型卡片中查看图纸细节 | 放大、移动并读清房间布局 |
| 顾客 / 外部访问者 | 查看完成或图片失败 | 安全关闭并回到原户型浏览位置 |

## 5. 用户用例

### UC-IMAGE-01 手机查看户型图

1. 用户点击户型卡片中的户型图或查看大图动作。
2. 图片查看器全屏打开，图片初始按视口完整适配。
3. 用户使用双指缩放。
4. 图片放大后，用户使用单指平移查看不同区域。
5. 用户可执行恢复适配，回到完整图纸视野。
6. 用户点击始终可达的关闭按钮返回页面。

### UC-IMAGE-02 PAD/PC 查看户型图

1. 用户打开图片查看器。
2. 使用明确缩放控件或鼠标滚轮缩放。
3. 图片放大后使用指针拖动查看。
4. 使用恢复适配回到完整图纸。
5. 点击关闭按钮或按 `Esc` 返回页面。

### UC-IMAGE-03 图片加载失败

1. 当前户型大图请求失败。
2. 查看器显示局部错误，不退出页面、不替换为其他户型图。
3. 用户可以关闭查看器返回原卡片。

## 6. 功能需求矩阵

| 功能 ID | 功能名称 | 关联用例 | 优先级 | 状态 |
| --- | --- | --- | --- | --- |
| F-IMAGE-01 | 全屏打开与适配 | UC-IMAGE-01、02 | P0 | 待设计 / 待开发 |
| F-IMAGE-02 | 缩放与平移 | UC-IMAGE-01、02 | P0 | 待设计 / 待开发 |
| F-IMAGE-03 | 恢复适配与关闭 | UC-IMAGE-01、02 | P0 | 待设计 / 待开发 |
| F-IMAGE-04 | 图片失败处理 | UC-IMAGE-03 | P0 | 待设计 / 待开发 |
| F-IMAGE-05 | 调用状态恢复 | UC-IMAGE-01、02、03 | P0 | 待开发 |

## 7. 功能详细说明

### 7.1 打开与初始状态

- 查看器在当前页面之上全屏打开，不改变页面 URL，不生成单户型页面。
- 初始状态按视口完整显示图纸，保持原始宽高比，不裁切关键内容。
- 背景页面在查看器打开期间不可滚动或误操作。
- 关闭按钮始终可达，不因图片缩放或平移离开视口。

### 7.2 缩放与平移

**手机：**

- 支持双指缩放。
- 图片大于适配尺寸后支持单指平移。
- 图片处于适配尺寸时，单指操作不应把图片拖离可视区域。
- 双击不触发缩放或其他产品动作。

**PAD/PC：**

- 支持明确的放大、缩小和恢复适配控件。
- 支持鼠标滚轮或触控板缩放。
- 图片大于适配尺寸后支持指针拖动。

- 所有端必须设置合理的最小和最大缩放边界，避免无限缩放；具体数值为 **待技术设计**，但不得影响 200% 放大下的稳定查看验收。

### 7.3 恢复适配与关闭

- 恢复适配将图片重置为完整显示状态并回到视口中心。
- 手机、PAD、PC 均提供明确关闭按钮。
- 键盘环境支持 `Esc` 关闭。
- 不使用下滑关闭或点击背景关闭，避免与图纸平移及误触冲突。
- 关闭后恢复调用前的筛选条件、Widget 展示模式、当前卡片和页面滚动位置。

### 7.4 加载与失败

- 加载中显示图片查看器局部加载状态。
- 加载失败显示明确错误和关闭操作；不得随机使用其他图片补位。
- 错误状态不升级为页面 403、404 或全局错误。

## 8. 交互与状态规则

| 状态 | 处理 |
| --- | --- |
| 加载中 | 全屏查看器保持可关闭，显示局部加载状态 |
| 初始适配 | 完整图纸位于视口内，保持原始比例 |
| 已放大 | 允许平移；关闭和恢复适配始终可达 |
| 已恢复 | 回到完整图纸和视口中心 |
| 加载失败 | 显示局部错误，允许关闭返回 |
| 已关闭 | 恢复调用前页面状态和键盘焦点 |

## 9. 数据与配置说明

- 图片来源为当前户型卡片绑定的已发布户型图。
- 查看器只消费调用方传入的图片资源、替代文字和当前户型稳定标识。
- 组件不自行选择其他户型、不请求外部搜索图片、不保存用户缩放状态。
- 图片清晰度与响应式资源规则进入项目内容数据与素材字典及技术设计。

## 10. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-IMAGE-01 | 户型图有效 | 手机打开查看器 | 图纸按视口完整适配，关闭按钮可用 |
| AC-IMAGE-02 | 手机查看器已打开 | 双指放大到至少 200% 并平移 | 图纸稳定显示，可查看不同区域，不闪退或跳回 |
| AC-IMAGE-03 | 手机查看器已打开 | 用户双击图片 | 不触发缩放、关闭或跳转 |
| AC-IMAGE-04 | PAD/PC 查看器已打开 | 使用控件或滚轮缩放并拖动 | 缩放和平移可用，关闭按钮始终可达 |
| AC-IMAGE-05 | 图片已被放大和平移 | 用户执行恢复适配 | 图纸恢复完整显示并回到视口中心 |
| AC-IMAGE-06 | 查看器已打开 | 用户点击关闭或在键盘环境按 Esc | 返回原页面并恢复筛选、模式、卡片和滚动位置 |
| AC-IMAGE-07 | 大图加载失败 | 用户查看错误 | 只显示查看器局部错误，并可关闭返回 |
| AC-IMAGE-08 | 320px、375px、768px、1024px、1440px | 用户完成打开、缩放、平移和关闭 | 核心操作均可达，不依赖设备专属业务逻辑 |

## 11. 风险与依赖

| 风险 / 依赖 | 类型 | 影响 | 应对 |
| --- | --- | --- | --- |
| 原图分辨率不足 | 素材依赖 | 高 | 发布素材规则明确最低可读要求，查看器不虚构清晰度 |
| 手势与页面滚动冲突 | 交互风险 | 高 | 查看器打开时锁定背景，平移只在图片放大后生效 |
| VISTA C 缩放控件精确规格不完整 | 设计依赖 | 中 | 复用图片栏/弹窗相关语言，具体控件视觉标记为待设计系统补充 |

## 12. 待确认事项

- 最大缩放倍数、缩放步长、控件精确尺寸和动效：**待技术设计 / 待设计系统补充**，不改变本 PRD 已确认的操作范围。

## 13. 供 Codex 使用的执行说明

- 必须实现为通用图片查看器组件，不得注册为 Widget。
- 不得添加双击缩放、下滑关闭、画廊、下载、分享或编辑能力。
- 关闭与错误状态必须优先保证用户能返回原页面。
- 原型先验证 320px、375px 的双指缩放、平移、恢复适配和关闭，再验证 PAD/PC。