ImagePreview 图片预览 ​

介绍 ​

图片放大预览，支持组件调用和函数调用两种方式。

引入 ​

js
import { createApp } from 'vue';
import { ImagePreview } from '@szhn/dh-design-mobile';

const app = createApp();
app.use(ImagePreview);

代码演示 ​

基础用法 ​

直接传入图片数组即可展示图片预览。

js
import { showImagePreview } from '@szhn/dh-design-mobile';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-3.jpeg',
  ],
});

指定初始位置 ​

showImagePreview 支持传入配置对象，并通过 startPosition 选项指定图片的初始位置（索引值）。

js
showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-3.jpeg',
  ],
  startPosition: 1,
});

展示关闭按钮 ​

开启 closeable 选项后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用 close-icon-position 属性可以自定义图标位置。

js
showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  closeable: true,
  closeIcon: 'close',
  closeIconPosition: 'top-left',
});

监听关闭事件 ​

通过 onClose 选项监听图片预览的关闭事件。

js
showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  onClose() {
    console.log('closed');
  },
});

异步关闭 ​

通过 beforeClose 属性可以传入一个回调函数，在图片预览关闭前进行特定操作。

js
showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  beforeClose: () =>
    new Promise((resolve) => {
      setTimeout(() => resolve(true), 1000);
    }),
});

使用 ImagePreview 组件 ​

如果需要在 ImagePreview 内嵌入组件或其他自定义内容，可以直接使用 ImagePreview 组件，并使用 index 插槽进行定制。

html
<van-image-preview v-model:show="show" :images="images">
  <template #index="{ index }">第 {{ index + 1 }} 页</template>
</van-image-preview>

使用 image 插槽 ​

当以组件调用的方式使用 ImagePreview 时，可以通过 image 插槽来插入自定义的内容，比如展示一个视频内容。

html
<van-image-preview v-model:show="show" :images="images">
  <template #image="{ src }">
    <video style="width: 100%;" controls>
      <source :src="src" />
    </video>
  </template>
</van-image-preview>

API ​

方法 ​

方法名说明参数返回值
showImagePreview展示一个全屏的图片预览组件string[] | ImagePreviewOptionsImagePreview 实例

ImagePreviewOptions ​

调用 showImagePreview 方法时，支持传入以下选项：

参数名说明类型默认值
images需要预览的图片 URL 数组string[][]
startPosition图片预览起始位置索引number | string0
swipeDuration动画时长，单位为 msnumber | string300
showIndex是否显示页码booleantrue
showIndicators是否显示轮播指示器booleanfalse
loop是否开启循环播放booleantrue
doubleScale是否启用双击缩放手势，禁用后，点击时会立即关闭图片预览booleantrue
onClose关闭时的回调函数Function-
onChange切换图片时的回调函数，回调参数为当前索引Function-
onScale缩放图片时的回调函数，回调参数为当前索引和当前缩放值组成的对象Function-
beforeClose关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise(active: number) => boolean | Promise<boolean>-
closeOnPopstate是否在页面回退时自动关闭booleantrue
closeOnClickImage是否在点击图片后关闭图片预览booleantrue
closeOnClickOverlay是否在点击遮罩层后关闭图片预览booleantrue
vertical是否开启纵向手势滑动booleanfalse
className自定义类名 (应用在图片预览的弹出层)string | Array | object-
maxZoom手势缩放时，最大缩放比例number | string3
minZoom手势缩放时，最小缩放比例number | string1/3
closeable是否显示关闭图标booleanfalse
closeIcon关闭图标名称或图片链接stringclear
closeIconPosition关闭图标位置，可选值为 top-left bottom-left bottom-rightstringtop-right
transition动画类名，等价于 transition 的 name 属性stringvan-fade
overlayClass自定义遮罩层类名string | Array | object-
overlayStyle自定义遮罩层样式object-
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性string | Element-

Props ​

通过组件调用 ImagePreview 时，支持以下 Props：

参数说明类型默认值
v-model:show是否展示图片预览booleanfalse
images需要预览的图片 URL 数组string[][]
start-position图片预览起始位置索引number | string0
swipe-duration动画时长，单位为 msnumber | string300
show-index是否显示页码booleantrue
show-indicators是否显示轮播指示器booleanfalse
loop是否开启循环播放booleantrue
double-scale是否启用双击缩放手势，禁用后，点击时会立即关闭图片预览booleantrue
before-close关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise(active: number) => boolean | Promise<boolean>-
close-on-popstate是否在页面回退时自动关闭booleantrue
close-on-click-image是否在点击图片后关闭图片预览booleantrue
close-on-click-overlay是否在点击遮罩层后关闭图片预览booleantrue
vertical是否开启纵向手势滑动booleanfalse
class-name自定义类名string | Array | object-
max-zoom手势缩放时，最大缩放比例number | string3
min-zoom手势缩放时，最小缩放比例number | string1/3
closeable是否显示关闭图标booleanfalse
close-icon关闭图标名称或图片链接stringclear
close-icon-position关闭图标位置，可选值为 top-left bottom-left bottom-rightstringtop-right
transition动画类名，等价于 transition 的 name 属性stringvan-fade
overlay-class自定义遮罩层类名string | Array | object-
overlay-style自定义遮罩层样式object-
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性string | Element-

Events ​

通过组件调用 ImagePreview 时，支持以下事件：

事件名说明回调参数
close关闭时触发{ index: number, url: string }
closed关闭且且动画结束后触发-
change切换当前图片时触发index: number
scale缩放当前图片时触发{ index: number, scale: number }
long-press长按当前图片时触发{ index: number }

组件实例方法 ​

通过组件调用 ImagePreview 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法。

方法名说明参数返回值
resetScale重置当前图片的缩放比--
swipeTo切换到指定位置index: number, options?: SwipeToOptions-

Slots ​

通过组件调用 ImagePreview 时，支持以下插槽：

名称说明参数
index自定义页码内容{ index: 当前图片的索引 }
cover自定义覆盖在图片预览上方的内容-
image自定义图片内容{ src: 当前资源地址, onLoad: 加载图片函数, style: 当前图片样式 }

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-image-preview-index-text-colorvar(--van-white)页码文字颜色
--van-image-preview-index-font-sizevar(--van-font-size-md)页码字体大小
--van-image-preview-index-line-heightvar(--van-line-height-md)页码行高
--van-image-preview-index-text-shadow0 1px 1px var(--van-gray-8)页码文字阴影
--van-image-preview-overlay-backgroundrgba(0, 0, 0, 0.9)遮罩层背景色
--van-image-preview-close-icon-size22px关闭图标大小
--van-image-preview-close-icon-colorvar(--van-gray-5)关闭图标颜色
--van-image-preview-close-icon-marginvar(--van-padding-md)关闭图标外边距
--van-image-preview-close-icon-z-index1关闭图标层级