# ImageViewer 更新日志

先阅读 [完整 LICENSE](https://snowui.dev/LICENSE)；同任务、同版本、同范围去重。

- 2026-09-21：统一使用文档、源码属性表与 Site / AI 阅读入口；仅文档修订，不改变组件行为。

- **ImageViewer-Docs.2026-05-25** 源码顶部历史更新日志已归档；后续新增变更统一写入本文档 更新日志，源码顶部只保留职责、当前关键架构与文档路径。

### v1.4.1 (2026-07-05)

#### 调整
- `dismissMode` 默认值由 `button` 改为 `backdrop`：默认隐藏关闭按钮并允许点击媒体外空白关闭。
- 需要可见关闭按钮时显式声明 `dismissMode="button"`。

### v1.4.0 (2026-07-05)

#### 新功能
- 新增 `dismissMode="button|backdrop"`，以关闭交互策略统一派生关闭按钮视觉。
- button：显示关闭按钮，点击空白不关闭；backdrop：隐藏关闭按钮，点击媒体外空白关闭。

### v1.3.1 (2026-07-05)

#### 调整
- 自动模式 Viewer 接入页面级 owner 选举；多个实例同时存在时仅首个 owner 响应事件并渲染 Portal。
- 页面存在共享 Viewer 时，未显式声明 previewMode 的 Image / ImageGroup 自动接入；服务不存在时回退 window。
- owner 卸载后由下一个已注册 Viewer 自动接管。

### v1.3.0 (2026-07-05)

#### 新功能
- 上一张、下一张、关闭控制键升级为默认内置 Button，分别使用 `ArrowLineLeft`、`ArrowLineRight` 与 SnowUI `Close`。
- 内置 Button 默认 `size="md"`、`variant="gray"`、`backgroundBlur={true}`，并开放 `parts.Button` 批量配置。
- 保留 children + `as="prev|next|close"` 显式组合模式。

### v1.2.1 (2026-03-15)

#### 修复
- **IV-Docs.1** 统一代码头、文档头与 changelog 版本号为 `v1.2.1`。
- **IV-Skeleton.1** 为字符串图片/视频资源补充真实加载态骨架桥接：媒体切换加载期间渲染 `Skeleton` 覆盖层，加载完成或失败后退出。
- **IV-Docs.2** 完整补齐 `ImageViewer` 的所有使用方式文档，包含 `previewMode="viewer" / "window" / "none"`、`ImageGroup previewMode`、原生 HTML / `resource-svelte` 图片的 `data-snowui-image-viewer-mode`、`data-snowui-image-viewer-scope` 以及单图 / 成组 / 回退行为示例。

### v1.2.0 (2026-03-12)

#### 调整
- **IV-Adjust.16** 自动模式新增 DOM 图片接入：原生 HTML `<img data-snowui-image-viewer-mode="viewer" />` 与 `resource-svelte` 根 `<img data-snowui-image-viewer-mode="viewer" />` 现在都能直接接入页面级 `ImageViewer`。
- **IV-Adjust.17** 新增 `[data-snowui-image-viewer-scope]` 作用域分组；定义 scope 时，作用域内 DOM 图片会按 DOM 顺序形成上一张 / 下一张列表。
- **IV-Adjust.18** 原生 HTML `<img data-snowui-image-viewer-mode="window" />` 在自动模式下会直接改走新窗口，不进入 Viewer。

### v1.1.24 (2026-03-12)

#### 调整
- **IV-Nav.24** 将上一张 / 下一张从首尾循环改为边界停止：第一张隐藏上一张且键盘无效，最后一张隐藏下一张且键盘无效；按钮与键盘行为一致。

### v1.1.23 (2026-03-12)

#### 调整
- **IV-Nav.23** 将上一张 / 下一张 / 关闭收口到自动模式与手动模式共用；第一张可循环到最后一张，最后一张可循环回第一张，按钮和键盘行为保持一致。

### v1.1.22 (2026-03-12)

#### 调整
- **IV-Key.22** 收回空格键切到下一张的映射；自动模式下下一张仅保留 `S / D / ArrowRight / ArrowDown`。

### v1.1.21 (2026-03-12)

#### 调整
- **IV-Key.21** 扩展自动模式键盘导航：`A / W / ArrowUp` 映射为上一张，`S / D / Space / ArrowDown` 映射为下一张；保留 `Escape` 关闭。

### v1.1.20 (2026-03-12)

#### 文档
- **IV-Doc.20** 将当前源码中的实现逻辑与样式结构完整同步到文档，包括自动/手动模式、事件总线、预取逻辑、根层点击关闭、宿主上下文协议、portal 挂载方式以及根层/视口层/媒体层/控制层的样式分层。

### v1.1.19 (2026-03-12)

#### 修复
- **IV-Fix.1** 显式传递 `Frame` 三个能力开关，并为 portal host 补上 `bind:element`，对齐现有 portal 组件约束。
- **IV-Fix.2** 默认关闭控件移除页面 utilities 类依赖，改为组件内部 `snowui-image-viewer-default-close` 样式。
- **IV-Fix.3** 收口内部变量命名、角色代理选择器和占位尺寸单位，修复 standards 中的命名与样式规则问题。

### v1.1.18 (2026-03-11)

#### 文档
- **IV-Doc.18** 将本轮明确确认的交互与布局需求写入文档：媒体与屏幕四边保持 `10%`、按钮与屏幕边缘保持 `3%`、点击媒体外空白区域关闭、`Esc` 关闭以及左右方向键切换。

### v1.1.17 (2026-03-11)

#### 调整
- **IV-Adjust.17** `ImageViewer` 将空白关闭从独立 backdrop 命中改为根层点击委托，只有媒体命中区和按钮层会被排除；同时把 `10%` 安全边距从 `padding` 改为 `viewport inset: 10vh 10vw`，确保媒体显示区域直接受屏幕四边硬约束。

### v1.1.16 (2026-03-11)

#### 调整
- **IV-Adjust.16** `ImageViewer` 移除外层 `Frame` 浮层根，改成纯 DOM 的 `backdrop / viewport / controls` 三层 overlay；`viewport` 直接使用 `padding: 10vh 10vw` 提供硬边距，媒体外空白区域交给 backdrop 关闭，控制按钮单独位于独立层并恢复自身点击命中。

### v1.1.4 (2026-03-11)

#### 文档
- **IV-Doc.1** 补全本轮对话中关于 `ImageViewer` 的全部定义：页面级单一 Viewer 主路径、自动/手动模式、与 `Image` / `ImageGroup` 的联动、禁用与回退链路、按钮 `as` 用法、视频定义以及当前性能实现。

### v1.1.5 (2026-03-11)

#### 调整
- **IV-Adjust.5** `ImageViewer` 改为固定全页浮层并提升层级；媒体壳层移除灰色背景，图片/视频在显示区域内按最大尺寸展示。

### v1.1.6 (2026-03-11)

#### 调整
- **IV-Adjust.6** 预览布局按屏幕边缘比例重新定义：媒体最大显示区域距屏幕边缘 `5%`，控制按钮距屏幕边缘 `3%`，并统一浮在媒体之上。

### v1.1.7 (2026-03-11)

#### 调整
- **IV-Adjust.7** 媒体显示区域改为通过统一 `5%` 容器内边距约束，确保上下左右边缘一致；同时新增点击媒体外区域关闭 Viewer 的交互。

### v1.1.8 (2026-03-11)

#### 调整
- **IV-Adjust.8** 预览层新增 `Esc` 关闭、左右方向键切换；点击关闭命中从整块媒体容器收口为背景层，避免媒体周围空白区无法关闭。

### v1.1.9 (2026-03-11)

#### 调整
- **IV-Adjust.9** 将 `5%` 视口框改为仅负责布局约束、不拦截指针事件；媒体壳层填满整个视口框，确保媒体完整落在 `5%` 安全边距内，同时点击媒体外区域稳定关闭 Viewer。

### v1.1.10 (2026-03-11)

#### 调整
- **IV-Adjust.10** 将媒体安全边距从 `5%` 调整为 `10%`；同时把阻止关闭的命中区域从整块媒体壳层收缩到媒体本体，修复点击媒体外空白区域仍无法关闭的问题。

### v1.1.11 (2026-03-11)

#### 调整
- **IV-Adjust.11** 将媒体本体改为直接占满 `10%` 安全框的宽高，再由 `object-fit: contain` 约束比例，确保 `10%` 屏幕边距成为稳定硬约束，而不是依赖媒体自然尺寸计算。

### v1.1.12 (2026-03-11)

#### 调整
- **IV-Adjust.12** 将 `10%` 安全边距从媒体节点自身收回到 `stage` 的 `padding`，同时恢复独立 `media-hitbox` 命中区域，确保既能稳定保持 `10%` 屏幕边距，也能继续点击媒体外空白区域关闭 Viewer。

### v1.1.13 (2026-03-11)

#### 调整
- **IV-Adjust.13** 参考成熟 modal/lightbox 结构，将关闭命中与媒体布局拆为独立 `backdrop` 与 `viewport` 两层：`backdrop` 单独负责点击关闭，`viewport` 单独负责 `10%` 安全边距与媒体居中显示。

### v1.1.14 (2026-03-11)

#### 调整
- **IV-Adjust.14** 为媒体壳层、媒体命中区和媒体本体同时增加 `80vw / 80vh` 视口上限，使“屏幕四边至少保留 `10%` 空间”不再只依赖父层布局链，而是由媒体自身直接受限。

### v1.1.15 (2026-03-11)

#### 调整
- **IV-Adjust.15** 将 `ImageViewer` 改为 portal 到 `document.body`：这样浮层不再受原页面祖先节点的 `transform / filter / contain` 影响，`fixed` 与 `10%` 屏幕边距才会真正相对整个视口生效。

### v1.1.1 (2026-03-11)

#### 调整
- **IV-Adjust.2** 页面级自动模式改为浏览器事件总线 + Viewer 本地状态，移除对全局 Svelte store 的运行时依赖，降低页面崩溃风险。

### v1.1.2 (2026-03-11)

#### 调整
- **IV-Adjust.3** 自动模式下不再复制打开请求中的 `items` 数组；Viewer 直接消费稳定列表引用，并为前后两张字符串图片做轻量预取。

### v1.1.3 (2026-03-11)

#### 调整
- **IV-Adjust.4** 前后项轻量预取增加 URL 去重缓存，同一轮预览中不会对同一字符串图片重复创建预取加载器。

### v1.1.0 (2026-03-10)

#### 新功能
- **IV-Feat.5** 新增页面级自动模式：省略 `open/items/index` 时，`ImageViewer` 自动接管页面中的 `Image` / `ImageGroup` 点击。

#### 调整
- **IV-Adjust.1** 页面中存在自动模式 `ImageViewer` 时，`Image` 默认通过 Viewer 打开；Viewer 不存在时由 `Image` 回退为新窗口打开。

### v1.0.2 (2026-03-10)

#### 新功能
- **IV-Feat.4** 新增字符串视频资源支持；Viewer 现在可直接预览 mp4/webm/ogg/mov。
- **IV-Behavior.1** 预览层中的视频默认自动播放，并使用 `muted + playsinline + loop` 保证浏览器可执行自动播放。

### v1.0.1 (2026-03-10)

#### 修复
- **IV-Fix.1** 修复 `resource-svelte` 图片在 Viewer 中未按放大尺寸显示的问题；预览层不再向资源组件传入错误的百分比 `width/height` props，改由 Viewer 自身样式负责放大展示。

### v1.0.0 (2026-03-10)

#### 新功能
- **IV-Feat.1** 新增独立的 ImageViewer 组件，承载图片预览态。
- **IV-Feat.2** 提供 `prev / next / close` 的宿主组合协议。
- **IV-Feat.3** 保持无动效切换，满足图片打开、切换、关闭的即时反馈要求。

### 共享遮罩

通过 `backdrop` 选择视觉，通过 `dismissMode` 选择点击关闭策略，两者独立。默认从旧的主题背景 92% 覆盖改为与 Dialog 相同的 opaque；背景覆盖变量仍兼容。实现边界见 backdrop。