SepImage 图片
覆盖 SepImage 全部配置项：src/alt/尺寸、填充模式、加载/错误态、预览灯箱、懒加载 + 自动化断言
0. HTML 声明式标签 — SepBase.autoInit() 自动驱动
HTML 声明式标签
1. 基础显示 — src / alt / 尺寸
HTML 声明式标签
JS API 初始化
2. 填充模式 — object-fit
JS API 初始化
3. 加载态 / 错误态 / fallback
JS API 初始化
4. 样式装饰 — radius / bordered / draggable
JS API 初始化
4b. 形状 — circle / rounded / square
JS API 初始化
圆形适合头像、方形适合列表缩略图、圆角适合卡片图
4c. 焦点位置 — objectPosition
JS API 初始化
fit=cover 时控制裁剪焦点，商品图顶部对齐等场景
4d. 响应式图片 — srcset / sizes
JS API 初始化
根据设备 DPR 和视口宽度自动选择最合适的图片，高清屏更清晰，普通屏省流量
5. 预览灯箱 — preview
JS API 初始化
hover 显示放大图标遮罩，点击打开通用灯箱（缩放/旋转/下载）
5e. 缩略图 + 高清大图 — preview.src
JS API 初始化
组件展示缩略图（src），点击灯箱打开高清大图（preview.src），列表省流量、详情看高清
5f. 多图预览组 — previewList
JS API 初始化
previewList 传入图片数组，点击打开灯箱后可切换全部图片（←→ 键或按钮）；initialIndex 指定起始图
5g. 标题与描述 — title / description
JS API 初始化
title 显示在灯箱顶部（替代文件名），description 显示在图片底部描述条
5h. 自定义懒加载根容器 — lazyRoot
JS API 初始化
lazyRoot 指定 IntersectionObserver 的根容器，图片滚动进入该容器可视区时才加载
5i. 灯箱交互选项 — previewLoop / previewCloseOnMask / previewShowThumbs
JS API 初始化
控制灯箱翻页是否循环、点击遮罩是否关闭、是否显示底部缩略图导航条
5j. 加载失败重试 — retryable
JS API 初始化
retryable=true 时加载失败可点击错误图标重新加载，错误文案变为"加载失败，点击重试"
5k. 灯箱工具栏按钮显隐
JS API 初始化
previewShowClose / previewShowDownload / previewShowZoom / previewShowRotate / previewShowFlip 单独控制灯箱工具栏各按钮显隐
5l. 灯箱事件回调 — onPreviewOpen / onPreviewClose / onPreviewChange
JS API 初始化
打开 / 关闭 / 切换图片时触发回调，回调参数含当前索引与总数；下方日志区实时展示回调触发情况
5m. 预览遮罩延迟 — previewDelay
JS API 初始化
previewDelay 设置 hover 后遮罩延迟显示（毫秒），避免快速划过时频繁闪烁
4e. 宽高比 — aspectRatio
JS API 初始化
aspectRatio 固定宽高比，图片加载前即占位，防止 CLS 布局抖动；支持数字（1.5）、分数（'16/9'）、比例（'4:3'）
4f. 渐进式加载 — progressive + blurDataURL
JS API 初始化
blurDataURL 低清缩略图先展示，主图加载完成后去模糊过渡，体验更顺滑
4g. 图片元素自定义 — imageClass / imageStyle
JS API 初始化
imageClass 附加 class 到 img，imageStyle 附加内联样式，便于深度定制图片渲染
4h. 灯箱交互增强 — 鼠标中心缩放 / 移动端手势 / 下载文件名
JS API 初始化
滚轮缩放以鼠标位置为中心、双击放大定位到点击处；移动端支持双指捏合缩放、单指左右滑动切换、下滑关闭； previewDownloadName 自定义下载文件名。
6. 懒加载 — lazy
JS API 初始化
设置 loading="lazy"，图片仅在接近视口时加载
详细说明
SepImage 通用图片展示组件，含加载过渡动画（opacity 0→1）、失败兜底+fallback 容错、预览灯箱（对接 SepBase.Lightbox 通用灯箱，支持缩放/旋转/下载）、懒加载，适用于商品图、用户头像、证件照、内容插图等场景。
Props 配置项
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| src | string | null | 图片地址 |
| srcset | string | null | 响应式图片候选列表，如 'img-1x.jpg 1x, img-2x.jpg 2x' |
| sizes | string | null | 图片显示尺寸提示，如 '(max-width:600px) 100px, 200px' |
| alt | string | '' | 替代文本（加载失败/无障碍时显示） |
| title | string | '' | 图片标题，灯箱顶部信息栏显示（替代文件名） |
| description | string | '' | 图片描述，灯箱图片底部毛玻璃描述条显示 |
| width | number | string | null | 宽度，number 自动加 px，string 原样使用 |
| height | number | string | null | 高度，同上规则 |
| fit | 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' | 'cover' | CSS object-fit 填充模式 |
| objectPosition | string | null | CSS object-position 裁剪焦点，如 'top center' |
| shape | 'default' | 'circle' | 'rounded' | 'square' | 'default' | 外观形状，圆形/圆角方形/方形 |
| fallback | string | null | 加载失败兜底图地址，原图失败后自动切换 |
| placeholder | boolean | true | 加载前显示骨架占位（CSS Skeleton 动画） |
| loadingIcon | string | HTML | null | 自定义加载态图标内容；以 '<' 开头视为 HTML，否则视为图片 URL |
| loadingProgress | boolean | 'exact' | true | 加载进度反馈；true=原生加载+滑动进度条（高性能逐张显示），'exact'=XHR精确百分比（适合大图），false=关闭 |
| errorIcon | string | HTML | null | 自定义错误态图标内容；规则同上 |
| mask | string | HTML | null | 自定义 hover 预览遮罩内容；规则同上 |
| progressive | boolean | false | 开启渐进式加载，配合 blurDataURL 使用缩略图先展示再模糊过渡 |
| blurDataURL | string | null | 渐进式加载的低清缩略图（base64 / data URL） |
| aspectRatio | number | string | null | 宽高比，如 16/9、1.5、'4:3'，防止 CLS 布局抖动 |
| lazy | boolean | false | 开启原生 loading="lazy" 懒加载 |
| lazyRoot | string | Element | null | 自定义懒加载根容器（CSS 选择器或 DOM 元素），配合 lazy 使用，基于 IntersectionObserver |
| lazyRootMargin | string | '100px 0px' | 懒加载提前检测范围，CSS rootMargin 格式（如 '200px 0px'、'50%'），大列表可设更大值减少白屏 |
| radius | number | string | 0 | 圆角，number 自动加 px |
| bordered | boolean | false | 显示 1px 边框 |
| crossOrigin | 'anonymous' | 'use-credentials' | null | 图片 crossorigin 属性 |
| referrerPolicy | string | null | Referrer 策略 |
| decoding | 'auto' | 'sync' | 'async' | null | 图片解码模式，'async' 可提升首帧性能 |
| draggable | boolean | false | 图片是否可拖拽 |
| imageClass | string | '' | 附加到 img 元素的 CSS class |
| imageStyle | object | string | null | 附加到 img 元素的内联样式（对象键值或 cssText 字符串） |
| onClick | (event, inst) => void | null | 点击图片回调，第二参数为组件实例 |
| preview | boolean | { src: string } | false | 点击打开通用灯箱预览；传 { src } 时组件展示 src 缩略图，灯箱展示 preview.src 高清大图 |
| previewList | Array<string | { src, previewSrc, alt, name }> | null | 多图预览组，点击打开灯箱后可切换全部图片；字符串项直接作为高清图地址 |
| initialIndex | number | 0 | 多图预览组的起始索引，从 0 开始 |
| previewLoop | boolean | true | 灯箱多图翻页是否循环，false 时到首尾停止 |
| previewCloseOnMask | boolean | true | 点击灯箱遮罩是否关闭，false 时只能点关闭按钮或 Esc |
| previewCloseOnEsc | boolean | true | 按 Esc 键是否关闭灯箱 |
| previewDelay | number | 0 | hover 预览遮罩延迟显示（毫秒） |
| previewContainer | string | Element | null | 灯箱挂载容器，null 时挂载到 body |
| previewDownloadName | string | null | 灯箱下载时自定义文件名，null 时使用图片原始名称 |
| previewShowThumbs | boolean | true | 多图时是否显示底部缩略图导航条 |
| previewShowClose | boolean | true | 灯箱是否显示关闭按钮 |
| previewShowDownload | boolean | true | 灯箱是否显示下载按钮 |
| previewShowZoom | boolean | true | 灯箱是否显示缩放按钮 |
| previewShowRotate | boolean | true | 灯箱是否显示旋转按钮 |
| previewShowReset | boolean | true | 灯箱是否显示重置按钮（一键还原缩放/旋转/翻转/平移） |
| previewShowFlip | boolean | true | 灯箱是否显示翻转按钮 |
| previewZIndex | number | null | 灯箱 z-index 层级，null 时使用 CSS 默认值 9999 |
| retryable | boolean | false | 加载失败时是否允许点击错误图标重新加载 |
| onLoad | (src, img) => void | null | 图片加载成功回调 |
| onError | (src, img) => void | null | 图片加载失败回调（含 fallback 最终失败） |
| onPreviewOpen | ({ index, total }) => void | null | 灯箱打开回调 |
| onPreviewClose | () => void | null | 灯箱关闭回调 |
| onPreviewChange | ({ index, total, image }) => void | null | 灯箱切换图片回调 |
| key | string | '' | 表单注册 key，用于 SepForm 集成 |
| className | string | '' | 附加到容器元素的 CSS class |
Methods 方法
| 方法 | 参数 | 返回 | 说明 |
|---|---|---|---|
| setSrc(v) | string | void | 设置图片地址 |
| getSrc() | - | string | 获取当前图片地址 |
| setSrcset(v) | string | null | void | 设置响应式图片候选列表 |
| getSrcset() | - | string | null | 获取当前 srcset |
| setSizes(v) | string | null | void | 设置图片尺寸提示 |
| getSizes() | - | string | null | 获取当前 sizes |
| setFallback(v) | string | void | 设置兜底图地址 |
| getFallback() | - | string | 获取兜底图地址 |
| setTitle(v) | string | void | 设置灯箱标题 |
| getTitle() | - | string | 获取灯箱标题 |
| setDescription(v) | string | void | 设置灯箱图片描述 |
| getDescription() | - | string | 获取灯箱图片描述 |
| setFit(v) | string | void | 设置填充模式（cover/contain/fill/none/scale-down） |
| getFit() | - | string | 获取当前填充模式 |
| setObjectPosition(v) | string | null | void | 设置裁剪焦点 |
| getObjectPosition() | - | string | null | 获取当前裁剪焦点 |
| setShape(v) | string | void | 设置形状（circle/rounded/square/default） |
| getShape() | - | string | 获取当前形状 |
| setRadius(v) | number | string | void | 设置圆角 |
| setWidth(v) | number | string | void | 设置宽度 |
| setHeight(v) | number | string | void | 设置高度 |
| setBordered(v) | boolean | void | 设置边框显示/隐藏 |
| isBordered() | - | boolean | 是否显示边框 |
| setPreview(v) | boolean | { src: string } | void | 设置预览灯箱开关；传 { src } 同时设置高清预览图 |
| isPreview() | - | boolean | 是否已启用预览 |
| setPreviewSrc(v) | string | null | void | 设置高清预览图地址（自动开启预览） |
| getPreviewSrc() | - | string | null | 获取高清预览图地址 |
| setPreviewList(v) | Array | void | 设置多图预览组（自动开启预览） |
| getPreviewList() | - | Array | 获取规范化后的预览组列表 |
| setInitialIndex(v) | number | void | 设置多图预览起始索引 |
| getInitialIndex() | - | number | 获取多图预览起始索引 |
| setPreviewLoop(v) | boolean | void | 设置灯箱翻页是否循环 |
| isPreviewLoop() | - | boolean | 灯箱翻页是否循环 |
| setPreviewCloseOnMask(v) | boolean | void | 设置点击遮罩是否关闭灯箱 |
| isPreviewCloseOnMask() | - | boolean | 点击遮罩是否关闭灯箱 |
| setPreviewCloseOnEsc(v) | boolean | void | 设置按 Esc 是否关闭灯箱 |
| isPreviewCloseOnEsc() | - | boolean | 按 Esc 是否关闭灯箱 |
| setPreviewDelay(v) | number | void | 设置 hover 预览遮罩延迟（毫秒） |
| getPreviewDelay() | - | number | 获取 hover 预览遮罩延迟 |
| setPreviewContainer(v) | string | Element | null | void | 设置灯箱挂载容器 |
| getPreviewContainer() | - | string | Element | null | 获取灯箱挂载容器 |
| setPreviewDownloadName(v) | string | null | void | 设置灯箱下载自定义文件名 |
| getPreviewDownloadName() | - | string | null | 获取灯箱下载自定义文件名 |
| setPreviewShowThumbs(v) | boolean | void | 设置是否显示底部缩略图导航条 |
| isPreviewShowThumbs() | - | boolean | 是否显示底部缩略图导航条 |
| setPreviewShowClose(v) | boolean | void | 设置是否显示关闭按钮 |
| isPreviewShowClose() | - | boolean | 是否显示关闭按钮 |
| setPreviewShowDownload(v) | boolean | void | 设置是否显示下载按钮 |
| isPreviewShowDownload() | - | boolean | 是否显示下载按钮 |
| setPreviewShowZoom(v) | boolean | void | 设置是否显示缩放按钮 |
| isPreviewShowZoom() | - | boolean | 是否显示缩放按钮 |
| setPreviewShowRotate(v) | boolean | void | 设置是否显示旋转按钮 |
| isPreviewShowRotate() | - | boolean | 是否显示旋转按钮 |
| setPreviewShowReset(v) | boolean | void | 设置是否显示重置按钮 |
| isPreviewShowReset() | - | boolean | 是否显示重置按钮 |
| setPreviewShowFlip(v) | boolean | void | 设置是否显示翻转按钮 |
| isPreviewShowFlip() | - | boolean | 是否显示翻转按钮 |
| setPreviewZIndex(v) | number | void | 设置灯箱 z-index 层级，null 恢复 CSS 默认 |
| getPreviewZIndex() | - | number | null | 获取灯箱 z-index 层级 |
| setRetryable(v) | boolean | void | 设置加载失败是否可点击重试 |
| isRetryable() | - | boolean | 是否允许失败重试 |
| retry() | - | void | 手动触发重新加载当前图片 |
| setCrossOrigin(v) | 'anonymous' | 'use-credentials' | void | 设置跨域策略 |
| setLazy(v) | boolean | void | 设置懒加载 |
| isLazy() | - | boolean | 是否已启用懒加载 |
| setLazyRoot(v) | string | Element | null | void | 设置自定义懒加载根容器 |
| getLazyRoot() | - | string | Element | null | 获取懒加载根容器 |
| setLazyRootMargin(v) | string | void | 设置懒加载提前检测范围（CSS rootMargin 格式） |
| getLazyRootMargin() | - | string | 获取懒加载提前检测范围 |
| setDraggable(v) | boolean | void | 设置可拖拽 |
| isDraggable() | - | boolean | 是否可拖拽 |
| setImageClass(v) | string | void | 设置 img 元素的附加 class |
| getImageClass() | - | string | 获取 img 元素的附加 class |
| setImageStyle(v) | object | string | void | 设置 img 元素的内联样式 |
| getImageStyle() | - | object | string | null | 获取 img 元素的内联样式 |
| setLoadingIcon(v) | string | HTML | void | 设置自定义加载态图标 |
| getLoadingIcon() | - | string | HTML | 获取自定义加载态图标 |
| setLoadingProgress(v) | boolean | void | 设置是否显示加载进度条 |
| isLoadingProgress() | - | boolean | 是否显示加载进度条 |
| setErrorIcon(v) | string | HTML | void | 设置自定义错误态图标 |
| getErrorIcon() | - | string | HTML | 获取自定义错误态图标 |
| setMask(v) | string | HTML | void | 设置自定义 hover 预览遮罩 |
| getMask() | - | string | HTML | 获取自定义 hover 预览遮罩 |
| setProgressive(v) | boolean | void | 设置是否开启渐进式加载 |
| isProgressive() | - | boolean | 是否开启渐进式加载 |
| setBlurDataURL(v) | string | void | 设置渐进式加载缩略图 |
| getBlurDataURL() | - | string | 获取渐进式加载缩略图 |
| setAspectRatio(v) | number | string | void | 设置宽高比 |
| getAspectRatio() | - | number | string | null | 获取宽高比 |
| setDecoding(v) | 'auto' | 'sync' | 'async' | void | 设置图片解码模式 |
| getDecoding() | - | string | null | 获取当前解码模式 |
| isLoaded() | - | boolean | 图片是否已加载完成 |
| isErrored() | - | boolean | 图片是否加载失败 |
| getState() | - | object | 获取完整状态快照 |
| setValue(k, v) | string, any | void | 设置单项状态值，触发视图更新 |
| getValue(k) | string | any | 获取单项状态值，不传 key 返回完整 state |
| subscribe(fn) | (state) => void | function | 订阅状态变更，返回取消订阅函数 |
| destroy() | - | void | 销毁实例，移除 DOM 与事件监听 |
Events 事件
| 事件 | 回调参数 | 说明 |
|---|---|---|
| onLoad | (src: string, img: HTMLImageElement) | 图片加载成功时触发 |
| onError | (src: string, img: HTMLImageElement) | 原图 + fallback 均加载失败时触发 |
| onClick | (event: MouseEvent, inst: SepImage) | 点击图片时触发，第二参数为组件实例 |
| onPreviewOpen | ({ index, total }) | 灯箱打开时触发 |
| onPreviewClose | () | 灯箱关闭时触发 |
| onPreviewChange | ({ index, total, image }) | 灯箱切换图片时触发 |
代码测试 / API / 断言
断言输出