Vant3 ImagePreview 图片预览

介绍

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

实例演示

函数调用

ImagePreview 是一个函数，调用函数后会直接在页面中展示图片预览界面。

import { ImagePreview } from vant;

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

组件调用

通过组件调用 ImagePreview 时，可以通过下面的方式进行注册。

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

// 全局注册
const app = createApp();
app.use(ImagePreview);

// 局部注册
export default {
  components: {
    [ImagePreview.Component.name]: ImagePreview.Component,
  },
};

代码演示

基础用法

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

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

指定初始位置

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

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

展示关闭按钮

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

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

监听关闭事件

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

import { Toast } from vant;

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

异步关闭

通过 beforeClose 属性可以拦截关闭行为。

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

setTimeout(() => {
  // 调用实例上的 close 方法手动关闭图片预览
  instance.close();
}, 2000);

组件调用

如果需要在图片预览内嵌入组件或其他自定义内容，可以使用组件调用的方式，调用前需要通过 app.use 注册组件。

<van-image-preview
  v-model:show="state.show"
  :images="state.images"
  @change="onChange"
>
  <template v-slot:index>第{{ 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

通过函数调用 ImagePreview 时，支持传入以下选项：

Props

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

Events

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

方法

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

Slots

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

onClose 回调参数

onScale 回调参数

样式变量

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

常见问题

在桌面端无法操作组件？

参见桌面端适配。

在 JSX 中渲染 ImagePreview 组件无法展示？

请注意 ImagePreview 是一个函数，ImagePreview.Component 才是 ImagePreview 对应的组件。JSX 调用图片预览的正确姿势如下：

export default {
  setup() {
    const show = ref(false);
    return () => <ImagePreview.Component v-model={[show, show]} />;
  },
};