Image 图片
除了拥有原生 img 的所有功能，还支持懒加载、自定义占位符、加载失败等。
基础用法
通过 `fit` 属性确定图片如何适应容器，同原生 object-fit
占位内容
通过 `slot = placeholder` 自定义图片未加载时的占位内容。
加载失败
通过 `slot = error` 可自定义图片加载失败时显示的内容。
懒加载
提示
自 2.2.3 版本起，已支持原生 `loading` 属性，您可以使用 `loading = "lazy"` 替代 `lazy = true`。
如果当前浏览器支持原生懒加载，则会优先使用原生懒加载，否则将通过滚动实现。
通过 `lazy = true` 开启懒加载。设置后，图片会在滚动到可视区域时才会加载。您可以通过 `scroll-container` 指定需要添加滚动监听的容器。如果未定义，则会是最近的 overflow 属性为 auto 或 scroll 的父容器。
图片预览
通过设置 `preview-src-list` 属性可以开启大图预览功能。您可以通过 `initial-index` 初始化第一张预览图片的位置。默认初始位置为 0。
手动开启预览 2.9.4
自定义工具栏 2.9.4
通过 `toolbar` 插槽自定义工具栏内容，从 2.9.7 版本开始，该插槽新增了 `setActiveItem` 函数，可以根据索引进行切换。
自定义进度条 2.9.4
通过设置 `show-progress` 属性来控制预览图片时是否显示进度条。在 2.9.8 版本之后，只要使用了 `progress` 插槽，进度条内容就会显示。
Image API
Image 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| src | 图片源，同原生。 | string | '' |
| fit | 确定图片如何适应容器框，同 object-fit。 | 枚举 | '' |
| hide-on-click-modal | 当开启预览时，是否可以通过点击遮罩层关闭预览。 | boolean | false |
| loading 2.2.3 | 指示浏览器应当如何加载该图片，同 原生。 | 枚举 | — |
| lazy | 是否开启懒加载。 | boolean | false |
| scroll-container | 开启懒加载后，监听 scroll 事件的容器。默认情况下，开启懒加载后，监听 scroll 事件的容器。 | string / object | — |
| alt | 原生属性 `alt`。 | string | — |
| referrerpolicy | 原生属性 referrerPolicy。 | string | — |
| crossorigin | 原生属性 crossorigin。 | 枚举 | — |
| preview-src-list | 开启图片预览功能。 | object | [] |
| z-index | 设置图片预览的 z-index。 | number | — |
| initial-index | 初始预览图像索引，小于 `url-list` 的长度。 | number | 0 |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Image Viewer。 | boolean | true |
| preview-teleported | image-viewer 是否插入至 body 元素上。 嵌套的父元素属性会影响该属性的使用。 | boolean | false |
| infinite | 是否可以无限循环预览。 | boolean | true |
| zoom-rate | 图片查看器缩放事件的缩放率。 | number | 1.2 |
| min-scale 2.4.0 | 图片查看器缩放事件的最小缩放比例。 | number | 0.2 |
| max-scale 2.4.0 | 图片查看器缩放事件的最大缩放比例。 | number | 7 |
| show-progress 2.9.4 | 是否显示预览图像的进度内容。 | boolean | false |
Image 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| load | 同原生 load。 | Function |
| error | 同原生 error。 | Function |
| switch | 切换图像时触发。 | Function |
| 关闭 | 当点击关闭按钮或当 `hide-on-click-modal` 启用时点击遮罩层时触发。 | Function |
| show | 当 viewer 显示时触发 | Function |
Image 插槽
| 名称 | 描述 | 类型 |
|---|---|---|
| 占位符 | 图片未加载时的自定义占位内容。 | - |
| error | 自定义图片加载失败内容。 | - |
| viewer | 图片预览时的自定义内容。 | - |
| progress 2.9.4 | 图片预览时的自定义进度内容。（优先级高于 `show-progress` 属性） | object |
| toolbar 2.9.4 | 图片预览时的自定义工具栏内容。 | object |
Image Exposes
| 名称 | 描述 | 类型 |
|---|---|---|
| showPreview 2.9.4 | 手动打开预览大图 | Function |
Image Viewer API
Image Viewer 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| url-list | 预览链接列表。 | object | [] |
| z-index | 预览遮罩层的 z-index。 | number / string | — |
| initial-index | 初始预览图像索引，小于等于 `url-list` 的长度。 | number | 0 |
| infinite | 预览是否可以无限循环。 | boolean | true |
| hide-on-click-modal | 用户点击遮罩层时是否可以触发 close 事件。 | boolean | false |
| teleported | 是否将图像本身附加到 body。嵌套的父元素属性 transform 应将此属性设置为 `true`。 | boolean | false |
| zoom-rate 2.2.27 | 图片查看器缩放事件的缩放率。 | number | 1.2 |
| min-scale 2.4.0 | 图片查看器缩放事件的最小缩放比例。 | number | 0.2 |
| max-scale 2.4.0 | 图片查看器缩放事件的最大缩放比例。 | number | 7 |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Image Viewer。 | boolean | true |
| show-progress 2.9.4 | 是否显示预览图像进度内容 | boolean | false |
Image Viewer 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| 关闭 | 当点击关闭按钮或当 `hide-on-click-modal` 启用时点击遮罩层时触发。 | Function |
| switch | 切换图像时触发。 | Function |
| rotate 2.3.13 | 旋转图像时触发。 | Function |
Image Viewer Exposes
| 名称 | 描述 | 类型 |
|---|---|---|
| setActiveItem | 手动切换图片 | Function |
类型声明
显示声明
ts
type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
enableTransition?: boolean
zoomRate?: number
rotateDeg?: number
}来源
贡献者
