Image Lightbox 图片预览
完整看图、放大细节，或按宽度阅读一张长截图。
用于阅读器、媒体列表与附件中的全屏看图。图片与操作保持清楚的层次，缩放后可以拖动到每个边角；长截图使用按宽度显示，保留从头到尾的阅读路径。
安装
pnpm dlx shadcn@4.22.1 add http://127.0.0.1:3040/r/v0.3.0/image-lightbox.json首次使用请先完成 Registry 与主题接入。
源码与 CSS module 一起安装。预览自身使用独立深色表面，不依赖宿主主题，也不改变页面的字体、主题或永久滚动规则。
Props 与默认行为
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | readonly ImageLightboxItem[] | 必填 | 每项提供稳定 id、src 与可选 alt；缺失地址显示不可用状态 |
open / onOpenChange | boolean / (open) => void | 必填 | 由宿主管理开关 |
initialIndex | number | 0 | 每次打开的初始图片；超出范围时取有效位置 |
fit | "contain" | "width" | "contain" | 完整显示，或按可用宽度阅读长截图 |
loop | boolean | true | 关闭后首尾停止切换，按钮正确禁用 |
finalFocus | Base UI Popup 的焦点目标 | 打开前的焦点 | 关闭后回到实际触发按钮 |
keyboardShortcuts | boolean | true | 内置方向键、+ / =、-；产品自带快捷键系统时设为 false |
labels | Partial<ImageLightboxLabels> | 中文 | 覆盖按钮、加载、失败与读屏文案，包括计数函数 |
onRetry | (item) => void | Promise<void> | — | 宿主刷新地址或重试权限；等待期间禁止重复点击，失败保留错误态 |
renderAction | ({ action, disabled, button }) => ReactNode | 原生提示 | 为现成按钮包装产品快捷键提示，保留事件、ref 与原生禁用语义 |
ref | Ref<ImageLightboxHandle> | — | 获取弹窗元素、切图/缩放/复位方法及实时可用状态 |
contain 的缩放范围为 1–4 倍，width 为 0.5–4 倍；按钮每次调整 0.5，捏合连续缩放。百分比相对于当前适配方式，点击比例可复位。重新打开、换图或地址更新时恢复初始视图。
键盘、触控与焦点
左右方向键切图，+ / = 放大，- 缩小。输入、输入法组合与修饰键不会触发内置图片快捷键。Escape 关闭预览；宿主接入快捷键提示时，第一次 Escape 先关闭提示。焦点始终留在模态中，关闭后返回触发位置。
图片画布可通过 Tab 聚焦。聚焦画布后，方向键滚动可溢出的图片，PageUp / PageDown 按页滚动，Home / End 到开头或结尾；工具栏和切图按钮仍可通过 Tab 操作。
双击或触屏双击切换 1 / 2 倍；放大后用拖动、滚轮或滚动条查看细节。触屏单指平移、双指捏合仅作用于图片视口。只在 contain 且 1 倍时识别明确的横向滑动；长图、纵向拖动、取消手势和多指手势不会误翻页。
数据更新与业务边界
重排保留当前 ID；当前项移除后显示原位置的相邻项，移除最后一项时选择前一项；集合清空时通知关闭。旧图片的迟到加载或失败事件不会污染当前图片。
鉴权、私有附件地址、桌面媒体代理和翻译均由宿主提供。组件只消费可呈现地址，不额外抓取、缓存或预加载私有附件。重试回调可以更新 src，组件会重新加载并隔离旧请求结果。
来源与版本
0.3.0 本地候选，提取自 Subtic 的内容图片预览与反馈附件预览。两种预览统一为一套交互；内容媒体映射、反馈权限、重试参数及用户快捷键偏好留在 Subtic。
查看由当前源码生成的类型参考
只展示 Kitseed 自身定义的属性，原生 HTML 与 Base UI 透传属性请参阅对应上游说明。
ImageLightbox
| 属性 | 类型 | 默认值 |
|---|---|---|
items | readonly ImageLightboxItem[] | — |
open | boolean | — |
onOpenChange | (open: boolean) => void | — |
initialIndex? | number | 0 |
finalFocus? | ComponentProps<typeof Dialog.Popup>["finalFocus"] | — |
loop? | boolean | true |
fit? | "contain" | "width" | "contain" |
keyboardShortcuts? | boolean | true |
ref? | Ref<ImageLightboxHandle> | — |
labels? | Partial<ImageLightboxLabels> | — |
onRetry? | (item: ImageLightboxItem) => void | Promise<void> | — |
renderAction? | (props: {
action: ImageLightboxAction;
disabled: boolean;
button: ReactElement;
}) => ReactNode | — |