vant/src/image-preview/README.md

ImagePreview

Intro

Used to zoom in and preview the picture, and it supports two methods: function call and component call.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { ImagePreview } from 'vant';

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

Usage

Basic Usage

ImagePreview([
  'https://img.yzcdn.cn/vant/apple-1.jpg',
  'https://img.yzcdn.cn/vant/apple-2.jpg',
]);

Set Start Position

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  startPosition: 1,
});

Show Close Icon

After setting the closeable attribute, the close icon will be displayed in the upper right corner of the pop-up layer, and the icon can be customized through the close-icon attribute, and the icon location can be customized by using the close-icon-position attribute.

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  closeable: true,
});

Close Event

import { Toast } from 'vant';

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  onClose() {
    Toast('closed');
  },
});

Before Close

const instance = ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  beforeClose: () => false,
});

setTimeout(() => {
  instance.close();
}, 2000);

Component Call

<van-image-preview
  v-model:show="state.show"
  :images="state.images"
  @change="onChange"
>
  <template v-slot:index>Page: {{ index }}</template>
</van-image-preview>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      show: false,
      index: 0,
    });
    const onChange = (index) => {
      state.index = index;
    };

    return {
      state,
      images: [
        'https://img.yzcdn.cn/vant/apple-1.jpg',
        'https://img.yzcdn.cn/vant/apple-2.jpg',
      ],
      onChange,
    };
  },
};

API

Options

Attribute	Description	Type	Default
images	Images URL list	string[]	[]
startPosition	Start position	number | string	0
showIndex	Whether to show index	boolean	true
showIndicators	Whether to show indicators	boolean	false
loop	Whether to enable loop	boolean	true
swipeDuration	Animation duration (ms)	number | string	300
onClose	Emitted when ImagePreview is closed	Function	-
onChange	Emitted when current image changed	Function	-
onScale	Emitted when scaling current image	Function	-
closeOnPopstate	Whether to close when popstate	boolean	true
beforeClose	Callback function before close	(action) => boolean | Promise	-
className	Custom className	string | Array | object	-
maxZoom	Max zoom	number | string	3
minZoom	Min zoom	number | string	1/3
closeable	Whether to show close icon	boolean	false
closeIcon	Close icon name	string	clear
closeIconPosition	Close icon position，can be set to top-left bottom-left bottom-right	string	top-right
transition v3.0.8	Transition, equivalent to name prop of transition	string	van-fade
overlay-style v3.0.8	Custom overlay style	object	-
teleport	Specifies a target element where ImagePreview will be mounted	string | Element	-

Props

Attribute	Description	Type	Default
v-model:show	Whether to show ImagePreview	boolean	false
images	Images URL list	string[]	[]
start-position	Start position	number | string	0
swipe-duration	Animation duration (ms)	number | string	300
show-index	Whether to show index	boolean	true
show-indicators	Whether to show indicators	boolean	false
loop	Whether to enable loop	boolean	true
before-close	Callback function before close	(action: number) => boolean | Promise<boolean>	-
close-on-popstate	Whether to close when popstate	boolean	true
class-name	Custom className	string | Array | object	-
max-zoom	Max zoom	number | string	3
min-zoom	Min zoom	number | string	1/3
closeable	Whether to show close icon	boolean	false
close-icon	Close icon name	string	clear
close-icon-position	Close icon position，can be set to top-left bottom-left bottom-right	string	top-right
transition v3.0.8	Transition, equivalent to name prop of transition	string	van-fade
overlay-style v3.0.8	Custom overlay style	object	-
teleport	Specifies a target element where ImagePreview will be mounted	string | Element	-

Events

Event	Description	Parameters
close	Emitted when closing ImagePreview	{ index, url }
closed	Emitted when ImagePreview is closed	-
change	Emitted when current image changed	index: index of current image
scale	Emitted when scaling current image	{ index: index of current image, scale: scale of current image}

Methods

Use ref to get ImagePreview instance and call instance methods.

Name	Description	Attribute	Return value
swipeTo 2.9.0	Swipe to target index	index: number, options?: SwipeToOptions	-

Types

Get the type definition of the ImagePreview instance through ImagePreviewInstance.

import { ref } from 'vue';
import type { ImagePreviewInstance } from 'vant';

const imagePreviewRef = ref<ImagePreviewInstance>();

imagePreviewRef.value?.swipeTo(1);

Slots

Name	Description	SlotProps
index	Custom index	{ index: index of current image }
cover	Custom content that covers the image preview	-

onClose Parameters

Attribute	Description	Type
url	Url of current image	number
index	Index of current image	number

onScale Parameters

Attribute	Description	Type
index	Index of current image	number
scale	scale of current image	number

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-image-preview-index-text-color	var(--van-white)	-
--van-image-preview-index-font-size	var(--van-font-size-md)	-
--van-image-preview-index-line-height	var(--van-line-height-md)	-
--van-image-preview-index-text-shadow	0 1px 1px var(--van-gray-8)	-
--van-image-preview-overlay-background-color	rgba(0, 0, 0, 0.9)	-
--van-image-preview-close-icon-size	22px	-
--van-image-preview-close-icon-color	var(--van-gray-5)	-
--van-image-preview-close-icon-active-color	var(--van-gray-6)	-
--van-image-preview-close-icon-margin	var(--van-padding-md)	-
--van-image-preview-close-icon-z-index	1	-