ImagePreview 图片预览

通用布局能力：RenderImagePreviewOptions 继承 RenderBoxOptions，可直接配置尺寸、min/max、margin 和槽位对齐；size 是同时提供默认宽高的便捷参数，不是可直接改写的布局结果。详见组件通用布局属性。

RenderImagePreview 是轻量图片展示控件，用于头像、缩略图、列表图片、空状态占位和业务卡片中的图片预览。它负责加载 URL 或接收已有 CanvasImageSource，并按 fit 与 shape 绘制到自身矩形内。

它不是完整图片查看器：不内置缩放、拖拽、旋转、裁剪、手势平移、工具栏或大图浏览状态。需要大图查看、标注或缩放交互时，应在页面或弹窗中组合专门的查看器能力，而不是把 ImagePreview 当作重型编辑控件。

API 总览

import {  RenderImagePreview,  type IconName,  type ImagePreviewDebugState,  type ImagePreviewFit,  type ImagePreviewLoadState,  type ImagePreviewShape,  type ImagePreviewSource,} from 'ds-ui'

最小装配顺序是：传入 src 或 source，同时给定稳定 size 或 width/height。列表和表格中应优先使用缩略图和固定尺寸，避免图片加载后改变行高。

适用场景

• 用户头像、医生头像、科室图标、患者缩略图。
• 图片附件、报告截图、扫码图片的列表预览。
• 卡片、表格行、树节点详情中的固定尺寸图片。
• 图片为空、加载中或加载失败时显示统一占位。

不适合：

• 影像阅片、报告大图、可拖拽缩放的图片查看。
• 图片裁剪、涂鸦、标注、旋转和保存。
• 大量原图直接铺满列表。列表仍应使用外层虚拟滚动，并尽量提供缩略图资源。

基本用法

const avatar = new RenderImagePreview({  src: '/assets/avatar.png',  size: 48,  shape: 'circle',  placeholderText: 'HL',})

src 是 URL 的便捷写法。也可以使用 source 传入 URL、HTMLCanvasElement、HTMLImageElement、ImageBitmap 等 CanvasImageSource。

const canvas = document.createElement('canvas')const preview = new RenderImagePreview({  source: canvas,  width: 160,  height: 96,  fit: 'contain',  shape: 'rounded',  borderWidth: 1,})

动态切换图片时，使用 setSource() 或 source 属性。旧 URL 图片的事件回调会被清理，迟到的 load/error 不会污染当前图片状态。

const preview = new RenderImagePreview({  size: 56,  placeholderIcon: 'window',}) preview.setSource('/assets/report-thumb.png')preview.setSource(null)

构造参数

类型

ImagePreviewSource：

string | CanvasImageSource | null | undefined

ImagePreviewFit：

ImagePreviewShape：

ImagePreviewLoadState：

属性和方法

debugState() 返回结构：

{
  sourceType: 'none' | 'url' | 'canvas'
  loadState: 'empty' | 'loading' | 'loaded' | 'error'
  fit: 'cover' | 'contain' | 'fill' | 'none'
  shape: 'rectangle' | 'rounded' | 'circle'
  displayRect: { x: number; y: number; width: number; height: number }
  imageSize: Size | null
}

尺寸和布局规则

RenderImagePreview 是 RenderBox，最终尺寸受父布局约束影响。

• 同时传 width 和 height：控件优先使用这两个尺寸。
• 传 size：相当于同时给默认 width 和 height，适合固定方形。
• 不传尺寸：默认使用 40 x 40。
• 只传 width 或只传 height：图片自然尺寸未知前，另一边先按默认值计算；URL 图片加载完成并拿到自然尺寸后，可能按图片比例重新布局。
• shape: 'circle' 不会强制控件变成正方形，只会按当前矩形内的最大圆绘制。头像应显式给等宽高。

列表、表格、树节点和虚拟滚动场景中，建议总是给固定 size 或固定 width/height，避免 URL 图片加载完成后触发行高变化。

绘制顺序

绘制顺序固定为：

1. 背景。圆形绘制圆形背景，矩形/圆角绘制对应矩形背景。
2. 图片或占位。图片会被裁剪到当前 shape。
3. 边框。borderWidth > 0 时绘制。

empty、loading、error 都使用占位绘制。当前没有内置 loading spinner 或错误图标；如果业务需要区分加载中和失败，可以通过外层状态、不同 placeholderText 或自定义组合控件表达。

URL 加载和生命周期

URL 图片通过浏览器 Image 对象异步加载：

• crossOrigin 会在设置 URL 前写入。
• 每次切换 source 都会递增加载 token，旧图片迟到的 load/error 会被忽略。
• 切换 source 或 dispose() 时会清空旧 Image.onload/onerror。
• 控件不维护全局图片缓存；浏览器自身缓存是否命中由浏览器和服务端缓存头决定。
• 传入 CanvasImageSource 时，控件只引用并绘制它，不拥有外部 canvas、image、video 或 bitmap 的生命周期。

交互边界

ImagePreview 自身没有点击、键盘、焦点、拖拽或选择行为。需要点击打开大图、右键菜单、复制图片地址、删除附件时，应该用外层容器或按钮组合。

const preview = new RenderImagePreview({  src: '/assets/report-thumb.png',  width: 120,  height: 80,  fit: 'contain',})

上例只负责绘制缩略图；“点击打开报告图片”应由包裹它的行、卡片或按钮处理。

性能建议

• 大列表中使用固定尺寸，避免图片加载后反复布局。
• 给列表或表格使用外层虚拟滚动，不要一次创建和绘制大量图片控件。
• 尽量提供缩略图 URL，而不是把原始大图交给每个预览控件缩放。
• 对频繁切换的图片，业务层应控制 source 更新频率，避免每帧创建新的 URL 图片。
• CanvasImageSource 由业务层复用时，要明确其生命周期；控件销毁不会释放外部资源。

常见问题

为什么传了 src 但显示空白？

URL 图片加载失败时会进入 error 状态并显示占位。可以通过 debugState().loadState 确认。跨域图片如果后续需要读取像素或导出，应正确设置 crossOrigin 和服务端 CORS。

为什么图片加载后控件尺寸变了？

通常是只设置了 width 或只设置了 height。图片加载前自然尺寸未知，另一边会用默认值；加载后会按自然比例重新计算。列表中建议同时设置宽高或使用 size。

source 和 src 同时传时谁生效？

构造时使用 source ?? src ?? null。也就是说 source 不是 null/undefined 时优先生效；否则使用 src。运行时清空图片请调用 setSource(null) 或设置 source = null。

可以做缩放拖拽吗？

不可以。RenderImagePreview 的职责是轻量预览和占位绘制。缩放拖拽应由专门图片查看器或页面组合实现。

相关文档

• Barcode / QRCode 条码二维码
• DataGrid 数据表格
• ListView 列表
• Card / Section / PageHeader
• Popup 基础设施