Tui

Image 图片组件

提供图片的渲染多种效果，支持 SSR 友好懒加载与错误态占位。

基础用法

支持图片加载失败的占位展示及默认样式

示例代码

vue

<template>
  <TsImage />
  <TsImage shape="square" />
  <TsImage :error="true" />
  <TsImage src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e5bcpng.png" />
  <TsImage src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
</template>

不同大小

通过 width/height 精确控制尺寸，单侧传入将镜像另一侧。头像等固定尺寸场景请改用 Avatar 组件。

示例代码

vue

<template>
  <TsImage shape="square" :width="60" />
  <TsImage shape="square" :width="120" :height="80" :error="true" />
  <TsImage shape="square" border-radius="5px" :width="128" :height="128" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
</template>

图片 Fit 效果

支持原生 cover、contain、fill

示例代码

vue

<template>
  <TsImage shape="square" :width="80" :height="80" fit="cover" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
  <TsImage shape="square" :width="80" :height="80" fit="contain" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
  <TsImage shape="square" :width="80" :height="80" fit="fill" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
</template>

拓展用法

自定义默认背景色、开启预览、删除回调、懒加载（SSR 友好）。占位图可通过 placeholder 指定。

示例代码

vue

<template>
  <TsImage shape="square" :width="80" :height="80" bg="black" />
  <TsImage shape="square" :width="80" :height="80" :previewable="true" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
  <TsImage shape="square" :width="80" :height="80" :previewable="true" :deletable="true" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
  <TsImage shape="square" :width="80" :height="80" lazy placeholder="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
</template>

离屏预加载 preloadMode

开启后会使用离屏预加载，加载成功再渲染真实 img，避免失败闪烁。关闭时回退到原生 onload/onerror 行为。

示例代码

vue

<template>
  <!-- 默认开启离屏预加载（preloadMode=true） -->
  <TsImage shape="square" :width="80" :height="80" src="https://example.invalid/not-found.jpg" />
  <!-- 关闭离屏预加载对比 -->
  <TsImage shape="square" :width="80" :height="80" :preloadMode="false" src="https://example.invalid/not-found.jpg" />
  <!-- 正常图片（成功后再渲染真实 img） -->
  <TsImage shape="square" :width="80" :height="80" src="https://www.timeszit.cn/tms/file?filename=articleCover2025-06-27-14-11-34evOCu.jpeg" />
</template>

迁移指南（从 size 到 width/height）

尺寸：移除 size 数值控制，用 width / height 。仅传一侧会自动镜像另一侧。

头像：固定头像尺寸请使用 TsAvatar 的 size （支持命名/数值）。

事件：图片预览使用 @preview 事件，开关仍由 previewable 控制。

属性 Props

src

图片地址

string

width

宽度（仅传 width 时，高度会镜像为同值）

string | number

0.3.2 新增（镜像逻辑）

height

高度（仅传 height 时，宽度会镜像为同值）

string | number

0.3.2 新增（镜像逻辑）

shape

图片形状

string

circle

borderRadius

图片圆角

string | number

图片背景色

string

placeholder

占位图地址（懒加载时 SSR/首屏阶段渲染占位）

string

1x1 transparent gif

0.3.2 新增

preloadMode

是否开启离屏预加载（成功后才渲染真实 img，避免失败闪烁）

boolean

true

0.3.2 新增

previewable

是否预览

boolean

false

deletable

是否可删除

boolean

false

0.3.2 （变更默认值)

errorText

加载失败文本

string

加载失败

0.3.2 （变更默认值）

error

是否加载失败（控制错误态，建议仅用于受控场景）

boolean

false

0.3.2 变更

lazy

是否懒加载（SSR 友好）

boolean | string | null

false

0.3.2（优化SSR兼容）

cursor

鼠标样式

string

fit

图片填充方式, 原生属性

string

cover

alt

图片alt, 原生属性

string

draggable

是否可拖拽, 原生属性

boolean

true

事件 Events

preview

预览图片

null

delete

删除图片

null

load

图片加载结果

true / false

error

图片加载失败

native error (可选)