TUI

Image 图片组件
提供图片的渲染多种效果,支持 SSR 友好懒加载与错误态占位。
基础用法
支持图片加载失败的占位展示及默认样式。
根本没请求接口
示例代码
vue
不同大小
通过 width / height 精确控制尺寸,单侧传入将镜像另一侧。头像等固定尺寸场景请改用 Avatar 组件。
示例代码
vue
图片 Fit 效果
支持原生 covercontainfill 效果。
示例代码
vue
拓展用法
自定义默认背景色、懒加载(SSR 友好)。占位图可通过 placeholder 指定。
示例代码
vue
离屏预加载 preloadMode
开启后会使用离屏预加载,加载成功再渲染真实 img,避免失败闪烁。关闭时回退到原生 onload / onerror 行为。
示例代码
vue
迁移指南(从 size 到 width/height)
尺寸:移除 size 数值控制,用 width / height 。仅传一侧会自动镜像另一侧。
头像:固定头像尺寸请使用 TsAvatarsize (支持命名/数值)。
事件:图片预览使用 @preview 事件,开关仍由 previewable 控制。
属性 Props
属性名
说明
类型
可选值
默认值
版本说明
src
图片地址
string
-
-
width
宽度(仅传 width 时,高度会镜像为同值)
string | number
-
0.3.2 新增(镜像逻辑)
height
高度(仅传 height 时,宽度会镜像为同值)
string | number
-
0.3.2 新增(镜像逻辑)
shape
图片形状
string
-
circle
deprecated 0.3.2
borderRadius
图片圆角
string | number
-
0
-
bg
图片背景色
string
-
-
placeholder
占位图地址(懒加载时 SSR/首屏阶段渲染占位)
string
-
1x1 transparent gif
0.3.2 新增
preloadMode
是否开启离屏预加载(成功后才渲染真实 img,避免失败闪烁)
boolean
-
true
0.3.2 新增
previewable
是否预览
boolean
-
false
deprecated 0.5.1
deletable
是否可删除
boolean
-
false
deprecated 0.5.1
errorText
加载失败文本
string
-
加载失败
deprecated 0.5.1
fallback
加载失败文本
string
-
added 0.5.2
error
是否加载失败(控制错误态,建议仅用于受控场景)
boolean
-
false
0.3.2 变更
lazy
是否懒加载(SSR 友好)
boolean | string | null
-
false
0.3.2(优化SSR兼容)
cursor
鼠标样式
string
-
deprecated 0.5.1
fit
图片填充方式, 原生属性
string
-
cover
-
alt
图片alt, 原生属性
string
-
-
draggable
是否可拖拽, 原生属性
boolean
-
true
-
事件 Events
事件名
说明
回调参数
版本说明
load
图片加载结果
true / false
error
图片加载失败, native error (可选)
true
preview
预览图片
deprecated 0.5.1
delete
删除图片
deprecated 0.5.1
插槽 Slots
插槽名
说明
版本说明
fallback
加载失败内容
added 0.5.2
基础用法
不同大小
图片 Fit 效果
拓展用法
离屏预加载 preloadMode
迁移指南(从 size 到 width/height)
属性 Props
事件 Events
插槽 Slots