# PPT 生图历史交互经验总结

更新日期：2026-04-26

## 背景

PPT 页面现在主要由整页图片构成，Frame 负责承载、预览、重生成和切换历史图片。
这类交互的关键不是“能记录历史”，而是让用户明确知道：

- 哪张图是当前正在展示的 PPT 页面
- 每张历史图是什么时间生成的
- hover 时能快速判断大图效果

## 这次暴露的问题

### 1. 历史时间不应使用菜单展示时间

历史列表里的时间如果使用“写入历史记录的时间”或“切换历史图的时间”，会误导用户。

正确语义应该是：

- 图片什么时候由 AI 生成，就展示什么时候
- 用户之后切换历史图，不应该刷新这张图的生成时间

一句话：
**生图历史的时间属于图片产物，不属于当前选择动作。**

### 2. 当前图必须在历史列表里显式激活

只靠缩略图和顺序无法让用户判断当前 PPT 页正在用哪张图，尤其是一次生成多张相似图片时。

更稳的做法是：

- 用 `elementId` 优先判断当前图
- `elementId` 不存在或已失效时，用 `imageUrl` 兜底
- 当前项使用激活样式和“当前”标记

一句话：
**历史列表需要表达“当前状态”，不能只表达“候选集合”。**

### 3. hover 大图应优先规避底部遮挡

历史菜单通常靠近页面下方，预览图如果向右下展开，很容易被视口底部截断。

当前更稳的默认定位是：

- 在历史 item 右侧展示
- 以 item 底部为基准向上展开
- 后续如果需要再做完整视口碰撞检测

一句话：
**没有碰撞检测前，右上展开比右下展开更稳。**

## 代码层面固化的规则

### 1. 历史记录写入时带上生成时间

从任务队列写入 PPT 生图历史时，应优先使用：

1. `task.completedAt`
2. `task.updatedAt`
3. `task.createdAt`
4. `Date.now()` 兜底

这样能让历史记录尽量接近图片真实生成完成时间。

### 2. 切换历史图时保留原历史时间

用户从历史菜单切回某张图时，需要把该历史项的 `createdAt` 继续传回 PPT 元数据更新流程，避免被 `Date.now()` 覆盖。

切换历史图只是改变当前展示图，不应该改变历史列表顺序。历史项如果已存在，应原位更新 `elementId` / `prompt` 等轻量信息，而不是重新插到第一位。

### 3. 批量生成时每张图都进入历史

一次生成多张图时：

- 最后一张作为当前展示图
- 所有结果都进入该 Frame 的 `slideImageHistory`
- 历史项保留各自所属任务的生成完成时间
- 新生成结果按生成顺序排在历史列表后面，不反向插入到最前

### 4. UI 激活态要跟数据判断一致

历史 item 的激活态判断应复用当前 PPT 图的真实关联关系：

- 优先比较 `slideImageElementId`
- 再比较 `slideImageUrl`

避免 UI 激活态和实际画布内容不一致。