Image
图片：加载态机（loading 骨架/自定义占位 → success → error 降级图/自定义/默认破图），success 且 preview 时 hover 蒙层 + 点击进全屏预览。预览浮层（ImagePreview）对齐 Semi：底部工具栏含上一张/页码/下一张、缩放 Slider、放大/缩小、原始尺寸↔适应页面切换、旋转、下载，支持鼠标滚轮以指针为锚缩放、超出容器拖拽平移、无限循环、预加载、无操作自动隐藏工具栏、renderHeader/renderPreviewMenu(menuItems)/renderCloseIcon/renderLeftIcon/renderRightIcon 自定义槽。ImagePreview 既可包裹多个 <Image> 做组预览，也可独立传 src 编程式控制。
如何引入
import { Image, ImagePreview } from '@chenzy-design/svelte';基础用法
通过 src 指定图片路径，width/height 指定宽高，默认可点击预览。
加载失败占位
通过 fallback 自定义加载失败的占位图（string 降级图或默认破图）。
默认破图占位 
自定义降级图
渐进加载
大图通过 placeholder 实现渐进加载，先展示模糊小图再淡入主图。
自定义预览图
缩略图与预览图分离：src 用小图，preview.src 指定高清预览图源。
多图预览
用 ImagePreview 包裹多个 Image 即可实现多图片预览，可左右切换。
单独使用预览组件
ImagePreview 可独立使用，通过 visible/onVisibleChange 与 src 编程式控制。
渲染在指定容器
通过 getPopupContainer 指定预览浮层父级 DOM（需 position:relative）。
自定义预览底部操作区
用 renderPreviewMenu 拿到 MenuProps 完全自定义底部操作区域。
基于默认按钮自定义
renderPreviewMenu 的 menuItems 为默认按钮 Snippet 数组，可自由重组。
自定义预览顶部展示区
通过 renderHeader 自定义预览顶部信息，入参为当前图 previewTitle。
API 参考
Image
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
src | 图片获取地址 | string | undefined |
alt | 图像描述 | string | '' |
width | 图片显示宽度，number 视为 px | number|string | undefined |
height | 图片显示高度，number 视为 px | number|string | undefined |
placeholder | 加载中占位内容（不传用 SkeletonImage 骨架） | Snippet | undefined |
fallback | 加载失败：string=降级图 src；Snippet=自定义内容；不传=默认破图 icon | string|Snippet | undefined |
preview | 预览：false 禁用；true 开启；对象=预览参数（含 src 覆盖预览图、visible 受控等） | boolean|PreviewProps | true |
crossorigin | 透传给原生 img 的 crossorigin | 'anonymous'|'use-credentials' | undefined |
imgCls | 透传给 img 节点的自定义类名（对齐 Semi imgCls） | string | undefined |
imgStyle | 透传给 img 节点的自定义内联样式（对齐 Semi imgStyle） | string | undefined |
setDownloadName | 设置预览下载文件名 | (src: string) => string | undefined |
onClick | 点击图片回调 | (e: MouseEvent) => void | undefined |
onError | 加载错误回调 | (e: Event) => void | undefined |
onLoad | 加载成功回调 | (e: Event) => void | undefined |
class | 根类名透传 | string | '' |
style | 根内联样式透传 | string | '' |
Slots
| 名称 | 说明 |
|---|---|
placeholder | 加载中自定义占位内容 |
fallback | 加载失败自定义内容（fallback 为 Snippet 时） |
ImagePreview
预览组 / 独立可编程预览：包裹多个 <Image> 做组预览可左右切换；或独立传 src=string|string[] + visible/onVisibleChange 编程式控制。
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
src | 预览图源列表（独立用法） | string|string[] | undefined |
visible | 受控：是否预览（不回写，仅 onVisibleChange） | boolean | undefined |
defaultVisible | 首次是否开启预览 | boolean | false |
currentIndex | 受控：当前预览图下标（不回写，仅 onChange） | number | undefined |
defaultCurrentIndex | 首次展示图片下标 | number | 0 |
maskClosable | 点击遮罩是否可关闭 | boolean | true |
closable | 是否显示关闭按钮 | boolean | true |
closeOnEsc | 点击 esc 关闭预览 | boolean | true |
infinite | 是否无限循环切换 | boolean | false |
zoomStep | 每次缩小/放大比例 | number | 0.1 |
maxZoom | 最大缩放比例 | number | 5 |
minZoom | 最小缩放比例 | number | 0.1 |
initialZoom | 初始缩放比例（每图首帧生效一次，受 min/maxZoom 限制） | number | undefined |
lazyLoad | 组内子图是否懒加载（IntersectionObserver） | boolean | true |
lazyLoadMargin | observer rootMargin | string | '0px 100px 100px 0px' |
preLoad | 是否预加载相邻图片 | boolean | true |
preLoadGap | 预加载步长 | number | 2 |
showTooltip | 是否展示底部操作区 Tooltip 提示 | boolean | false |
disableDownload | 禁用下载（含右键） | boolean | false |
viewerVisibleDelay | 隐藏操作按钮前的无操作时长(ms) | number | 10000 |
zIndex | 预览层层级 | number | 1070 |
getPopupContainer | 指定预览浮层父级 DOM（需 position:relative） | () => HTMLElement | undefined |
setDownloadName | 设置下载文件名 | (src: string) => string | undefined |
prevTip / nextTip / zoomInTip / zoomOutTip / rotateTip / downloadTip / adaptiveTip / originTip | 各操作按钮 Tooltip 文案（缺省走 locale） | string | locale |
renderHeader | 自定义预览顶部区（收到当前 title） | Snippet<[title]> | undefined |
renderPreviewMenu | 自定义底部菜单（MenuProps.menuItems 为默认按钮 Snippet 数组） | Snippet<[MenuProps]> | undefined |
renderCloseIcon / renderLeftIcon / renderRightIcon | 自定义关闭/左切换/右切换图标 | Snippet | undefined |
onVisibleChange | 预览开关变化 | (visible: boolean) => void | undefined |
onChange | 切换图片 | (index: number) => void | undefined |
onClose | 关闭回调 | () => void | undefined |
onPrev / onNext | 向前/向后切换回调 | (index: number) => void | undefined |
onZoomIn / onZoomOut | 放大/缩小回调 | (zoom: number) => void | undefined |
onRotateLeft | 旋转回调 | (angle: number) => void | undefined |
onRatioChange | 原始尺寸/适应切换回调 | (type: "adaptation"|"realSize") => void | undefined |
onDownload | 下载回调 | (src, index) => void | undefined |
onDownloadError | 下载失败回调 | (src) => void | undefined |
Accessibility
| ARIA role | img |
| 键盘交互 | EscapeArrowLeftArrowRight |
- img 必传 alt 语义；默认破图占位用 role=img + aria-label
- 预览遮罩 role=dialog、aria-modal=true，portal 到 getPopupContainer/body；useFocusTrap 锁定焦点、Esc 关闭、useScrollLock 锁背景滚动
- 组/独立预览左右切换：中部 ← → 按钮 + 键盘左右箭头（到边界按钮隐藏，infinite 时循环）
- 翻页经 LiveAnnouncer polite 播报「第 m 张，共 n 张」
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-image-bg | var(--cd-color-fill-0) | 图片占位背景 |
--cd-image-header-close-bg | rgba(0, 0, 0, 0.75) | $color-image_header_close-bg：header 关闭 icon hover 背景（Semi 明暗一致） |
--cd-image-mask-bg | var(--cd-color-overlay-bg) | $color-image_mask-bg：图片 hover 预览蒙层背景 |
--cd-image-mask-color | var(--cd-color-white) | 图片操作遮罩文字颜色 |
--cd-image-mask-hover-bg | rgba(255, 255, 255, 0.15) | 预览工具条/切换按钮 hover 时的浅色高亮叠层（浮在深色遮罩上） |
--cd-image-mask-info-text | var(--cd-color-white) | $color-image_mask_info_text：蒙层「预览」文字颜色 |
--cd-image-placeholder-color | var(--cd-color-text-3) | 图片占位/错误文字颜色 |
--cd-image-preview-bg | var(--cd-color-overlay-bg) | $color-image_preview-bg：预览浮层遮罩背景 |
--cd-image-preview-disabled-color | rgba(249, 249, 249, 0.35) | $color-image_preview_disabled：禁用 icon 颜色（Semi 明暗一致） |
--cd-image-preview-divider-bg | rgba(255, 255, 255, 0.5) | $color-image-preview_divider-bg：footer 分割线颜色（Semi 明暗一致） |