Image 图片
用于展示图片资源，支持可选预览能力。
基础用法
基础图片
适应方式
object-fit 变体
cover（裁切填充）
contain（完整显示）
通过 fit 设置 object-fit，再配合 ::part(image) 固定图片容器尺寸实现裁切效果。
占位与兜底
加载占位
设置 placeholder 后，图片加载完成前显示浅灰占位；加载完成后自动切换为图片。
加载失败兜底
默认失败占位
自定义兜底图
图片加载失败时默认显示「图片加载失败」占位；提供 fallback 属性可指定兜底图片地址，兜底图也失败时回退到占位文案。
懒加载
懒加载长列表（滚动逐图加载）
设置 lazy 后图片进入视口才发起加载；配合 placeholder 展示「加载中」占位。向下滚动列表，观察占位 → 加载的过渡（视口内图片立即加载）。
预览
点击预览（内置浮层）
点击图片打开全屏预览浮层：工具栏支持放大/缩小/旋转/水平翻转/垂直翻转/下载，放大后可拖拽平移、滚动滚轮缩放；触屏支持双指捏合缩放（锚定双指中点，中点移动自带平移）与单指拖拽平移；Esc 或点击遮罩关闭；打开时聚焦关闭按钮，关闭后还原焦点。派发 oas-preview 事件（detail 含 src）。
预览浮层打开时挂载到 document.body（portal），规避组件位于 transform/filter 祖先内时 position: fixed 失效的问题；portal 期间 ::part(preview-*) 无法从宿主穿透，定制请走 CSS 变量。
图集预览
图集预览（多图翻页）
设置 preview-src-list（JSON URL 数组）进入图集模式：点击后可用两侧箭头、工具栏翻页按钮或键盘 ←→ 翻页，页码指示「n/total」；某张加载失败显示失败占位（复用 error 插槽内容）而非空白。
无限循环（infinite）
加 infinite 后翻页首尾循环：最后一张再「下一张」回到第一张，第一张再「上一张」跳到最后一张。
缩略图与原图分离
preview-src（缩略图与原图分离）
列表内显示 src 缩略图，点开预览时加载 preview-src 指定的高清原图（下载地址同步指向原图）。
受控预览
受控预览（preview-open + openPreview()）
外部按钮调 openPreview() 方法打开；preview-open 属性在场时受控当前开合态——内部开合（点击/Esc/关闭按钮）会反射回该属性并派发 oas-preview-change（detail { open }），外部增删该属性同样驱动开合（双向同步）。
自定义工具栏
自定义工具栏（slot=toolbar + oas-toolbar-render）
提供 template[slot="toolbar"] 后，模板内容被克隆进预览浮层工具栏区并替换默认按钮组（原模板保留在 light DOM；无模板时维持默认工具栏）。克隆完成与每次打开预览都会派发 oas-toolbar-render：在事件回调里用 detail 的 element（工具栏容器）与 actions（查看器命令）把自定义按钮接到预览命令即可，上图按钮均已接线可直接点击。
oas-toolbar-render 的 detail 为 { element, actions }：element 是克隆后的工具栏容器（宿主在其上绑定按钮事件，重复绑定幂等）；actions 命令集合如下（图集模式下 prev/next 有效，单图模式为 no-op）：
| 命令 | 说明 |
|---|---|
zoomIn / zoomOut | 放大 / 缩小一档（与滚轮、默认按钮同一份 transform 状态机） |
rotateLeft / rotateRight | 逆时针 / 顺时针旋转 90° |
flipX / flipY | 水平 / 垂直翻转 |
download | 触发当前预览图下载 |
close | 关闭预览浮层（等价 Esc / 点遮罩） |
prev / next | 图集上一张 / 下一张（受 infinite 边界约束，同默认翻页） |
宿主接线示例：
el.addEventListener('oas-toolbar-render', (e) => {
const { element, actions } = e.detail
element.querySelector('#my-zoom-in').onclick = actions.zoomIn
})oas-image-group 共享预览同样支持：把 template[slot="toolbar"] 直接放在组图内即可透传到共享浮层。自定义工具栏的按钮自动获得 token 化基础样式（light/dark 可读），并参与 Tab 焦点陷阱。
加载事件
加载事件（oas-load / oas-error）
加载成功 → oas-load
加载失败 → oas-error
主图加载成功派发 oas-load、最终失败派发 oas-error（detail 均含 src）；fallback 重试期间不派发 oas-error，兜底图也失败时才派发（detail.src 为兜底图地址）。
自定义占位与失败插槽
自定义 placeholder / error 插槽
slot="placeholder"
slot="error"
template[slot="placeholder"] / template[slot="error"]（或任意带同名 slot 属性的元素）会被克隆进对应占位区，优先于内置文案；图集预览中某张加载失败也复用 error 插槽内容。
翻转
翻转（flipX / flipY）
工具栏提供「水平翻转」「垂直翻转」，与缩放、旋转、拖拽平移串接为同一份 transform 状态机，互不打断。
拖拽与滚轮缩放
拖拽平移 + 滚轮缩放（大图/长图）
放大后在预览图上按住拖拽平移（超出可视范围的部分按边界自动收敛），在预览区滚动滚轮缩放（已阻断页面滚动）。缩放步进与上下限可经 CSS 变量覆盖（见下表）。
相册墙组合
相册墙（多图各自进图集）
网格排布多张缩略图，点击任意一张从该张开始进入同一图集翻页（主图 src 命中列表时按该张起开）。
图集容器（oas-image-group）
图集容器（声明式图片墙 → 共享预览）
把多个 oas-image 放进 oas-image-group，容器自动收集为共享图集：点击任一图片从该张起打开预览，两侧箭头 / 键盘 ←→ 在整组图间翻页（页码 n/total）。子图带 preview 时点击同样被容器接管为组图集，不再需要各自配置 preview-src-list。
子图动态增删（或修改 src）图集自动同步；current 可选受控当前索引——属性在场时点击按 current 起开、内部翻页反射回该属性，缺席时不造属性、仅派发 oas-change（detail { current, prev }，演示见上方消息反馈）；infinite 透传共享预览。
与 preview-src-list 的关系：preview-src-list 适合「数据数组驱动」的单点图集入口（一张缩略图代表整组）；oas-image-group 适合「声明式图片墙」——每张子图天然是图集成员，DOM 里加图即入集。两者共享同一份预览浮层能力（缩放/旋转/翻转/下载/Esc/遮罩/焦点陷阱）；组内子图仍可用 preview-src 指定预览原图、用 preview-src-list 把单张子图展平为多张。组图默认 flex 换行排列，间距可经 CSS 变量 --oas-image-group-gap 覆盖。
预览缩放 CSS 变量
| CSS 变量 | 默认值 | 说明 |
|---|---|---|
--oas-image-zoom-step | 0.5 | 每次放大/缩小的步进（工具栏按钮与滚轮共用） |
--oas-image-zoom-min | 0.5 | 缩放下限 |
--oas-image-zoom-max | 3 | 缩放上限 |
在宿主元素或主题层覆盖即生效，例如 style="--oas-image-zoom-max: 5"。
显式尺寸与 Referrer 策略
width / height 显式尺寸：数字按 px，也接受任意 CSS 尺寸串（如 50%），写在内层 img 上（max-width: 100% 响应式约束保留）；空值清除恢复 auto 布局。referrerpolicy 透传内层 img 控制隐私策略（如 no-referrer），空值回落浏览器默认。
显式尺寸 width / height
referrerpolicy 透传
API
oas-image
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
alt | 替代文本 | — | — |
fallback | 加载失败时切换的兜底图地址；未设置则显示「图片加载失败」占位 | string | — |
fit | object-fit 值 | string | — |
height | 显式高度（同 width 规则） | string | — |
infinite | 图集首尾循环切换 | boolean | — |
lazy | 懒加载：图片进入视口才发起加载（IntersectionObserver）；已位于视口内立即加载；环境不支持时退化为立即加载 | boolean | — |
placeholder | 加载完成前显示浅灰占位 | boolean | — |
preview | 开启内置预览：点击放大 + 缩放/旋转/下载 + Esc 关闭 + 焦点陷阱 | boolean | — |
preview-open | 受控预览开合（属性在场受控，配合 oas-preview-change 双向；另见 openPreview() 方法） | boolean | — |
preview-src | 预览原图 URL（缩略图与原图分离；缺省用 src） | string | — |
preview-src-list | 图集预览：URL JSON 数组，点开后 prev/next 翻页 + 页码 + 键盘 ←→ | string | — |
referrerpolicy | 透传内层 img 的 Referrer 策略 | string | — |
src | 图片地址 | string | — |
width | 显式宽度（数字按 px，CSS 尺寸串原样透传，空值恢复 auto） | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-error | 图片最终失败（回退链耗尽），detail: { src } |
oas-load | 图片加载成功，detail: { src } |
oas-preview | 打开预览浮层，detail: { src }；浮层关闭不派发事件 |
oas-preview-change | 预览开合变化，detail: { open } |
oas-preview-nav | 图集翻页/跳转，detail: { index, src }；供 oas-image-group 容器接管索引 |
oas-toolbar-render | 自定义工具栏渲染通知（克隆完成与每次打开预览均派发，宿主重复绑定幂等），detail { element, actions }：element 为克隆后的工具栏容器，actions 为查看器命令集合 |
插槽
| 名称 | 说明 |
|---|---|
template[slot="error"] | 自定义失败占位内容（主图与图集预览失败位复用） |
template[slot="placeholder"] | 自定义加载占位内容（缺省为浅灰占位 + 文案） |
template[slot="toolbar"] | 自定义预览工具栏内容：克隆进浮层工具栏区并替换默认按钮组（缺席维持默认）；克隆完成与每次打开预览派发 oas-toolbar-render（detail { element, actions }），actions 命令：zoomIn/zoomOut/rotateLeft/rotateRight/flipX/flipY/download/close/prev/next（单图模式 prev/next 无效） |
oas-image-group
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
current | 当前图集索引（可选受控）：属性在场时受控——点击按 current 起开、内部翻页反射回该属性、外部改属性驱动预览跳图；缺席时不造属性，仅派发 oas-change | — | — |
infinite | 翻页首尾循环（透传共享预览宿主） | boolean | — |
事件
| 事件 | 说明 |
|---|---|
oas-change | 图集切换，detail: { current, prev } |
oas-preview | 打开共享预览浮层，detail: { src }（src 为当前张地址） |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 图集成员（oas-image） |
template[slot="toolbar"] | 透传共享预览宿主：自定义共享预览浮层的工具栏（克隆替换默认按钮组 + oas-toolbar-render 命令通道，同 oas-image） |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-image-group-gap | var(--oas-space-3) |