Image 图片

图片容器,在保留所有原生 img 的特性下,支持懒加载,自定义占位、加载失败等

基础用法

可通过fit确定图片如何适应到容器框,同原生 object-fit

fill
contain
cover
none
scale-down

占位内容

可通过slot = placeholder可自定义占位内容

Default
Custom
Loading...

加载失败

可通过slot = error可自定义加载失败内容

Default
Custom

懒加载

TIP

浏览器原生支持的 loading属性在 2.2.3版本加入。 您可以使用 loading="lazy" 替换之前的lazy= true

如果当前浏览器支持原生图片延迟加载,则先使用原生能力,否则将使用滚动监听实现相同效果。

可通过lazy开启懒加载功能, 当图片滚动到可视范围内才会加载。 可通过 scroll-container 来设置滚动容器, 若未定义,则为最近一个 overflow 值为 auto 或 scroll 的父元素。

图片预览

可通过 previewSrcList 开启预览大图的功能。 你可以通过 initial-index 初始化第一张预览图片的位置。 默认初始位置为 0。

手动打开预览 2.9.4

允许通过调用 showPreview 来触发大图预览。

自定义工具栏2.9.4

通过 slot = toolbar 自定义工具栏内容

Image API

属性

属性名说明类型默认值
src图片源地址,同原生属性一致string''
fit确定图片如何适应容器框,同原生 object-fitenum''
hide-on-click-modal当开启 preview 功能时,是否可以通过点击遮罩层关闭 previewbooleanfalse
loading 2.2.3浏览器加载图像的策略,和 浏览器原生能力一致enum
lazy是否使用懒加载booleanfalse
scroll-container开启懒加载功能后,监听 scroll 事件的容器 默认情况下,开启懒加载功能后,监听 scroll 事件的容器string / object
alt原生属性 altstring
referrerpolicy原生属性 referrerPolicystring
crossorigin原生属性 crossoriginenum
preview-src-list开启图片预览功能object[]
z-index设置图片预览的 z-indexnumber
initial-index初始预览图像索引,小于 url-list 的长度number0
close-on-press-escape是否可以通过按下 ESC 关闭 Image Viewerbooleantrue
preview-teleportedimage-viewer 是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 truebooleanfalse
infinite是否可以无限循环预览booleantrue
zoom-rate图像查看器缩放事件的缩放速率。number1.2
min-scale 2.4.0图像查看器缩放事件的最小缩放比例number0.2
max-scale 2.4.0图像查看器缩放事件的最大缩放比例number7

事件

事件名说明类型
load图片加载成功触发Function
error图片加载失败触发Function
switch切换图像时触发。Function
close当点击 X 按钮或者在hide-on-click-modal为 true 时点击遮罩层时触发Function
show当 Viewer 显示时触发Function

插槽

插槽名说明类型
placeholder当图像尚未加载时,自定义的占位符内容-
error自定义图像加载失败的内容-
viewer当图像预览时自定义内容-
progress 2.9.4图片预览时自定义进度条内容object
toolbar 2.9.4当图像预览时,自定义工具栏内容object

对外暴露的方法

属性名说明类型
showPreview 2.9.4手动打开大图预览Function

Image Viewer API

属性

事件名说明Type默认值
url-list用于预览的图片链接列表object[]
z-index预览时遮罩层的 z-indexnumber / string
initial-index初始预览图像索引,小于 url-list 的长度number0
infinite是否可以无限循环预览booleantrue
hide-on-click-modal是否可以通过点击遮罩层关闭预览booleanfalse
teleportedimage 自身是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 truebooleanfalse
zoom-rate 2.2.27图像查看器缩放事件的缩放速率。number1.2
min-scale 2.4.0图像查看器缩放事件的最小缩放比例number0.2
max-scale 2.4.0图像查看器缩放事件的最大缩放比例number7
close-on-press-escape是否可以通过按下 ESC 关闭 Image Viewerbooleantrue
show-progress 2.9.4是否显示预览图片的进度条内容booleanfalse

事件

Name说明类型
close当点击 X 按钮或者在hide-on-click-modal为 true 时点击遮罩层时触发Function
switch切换图像时触发。Function
rotate 2.3.13旋转图像时触发。Function

对外暴露的方法

名称详情类型
setActiveItem手动切换图片Function

类型声明

显示类型声明
ts
type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
  enableTransition?: boolean
  zoomRate?: number
  rotateDeg?: number
}

源代码

组件样式文档

贡献者