更新记录

1.1.0（2026-08-03）

新增

• 标题动画：titleOriginRect 有值时从源位置平滑飞到预览底栏落点，关闭时飞回
• 未提供 titleOriginRect 时标题仅透明度逐渐出现 / 消失（不位移）

平台兼容性

uni-app(5.01)

uni-app x(5.08)

自定义大图预览 · Image Preview Popup

替代 uni.previewImage：从点击位置飞入全屏，宽高同步渐变（不用 CSS scale），关闭时回缩；支持多图滑动、双指捏合缩放、下拉关闭。

普通授权：下载即用（市场加密保护）。源码授权：完整可读源码，便于二次开发与审计。
购买 / 试用请以 DCloud 插件市场 页面为准。

为什么选它

适用场景：商品详情轮播、活动奖品图、订单凭证、图文详情中的点击放大等。

平台兼容性

• 依赖：无（纯前端组件，不采集数据、无广告、无额外权限）
• 安装：放入项目 uni_modules/image-preview-popup，easycom 自动注册，无需 import

核心能力

1. 飞入 / 飞出：传入 originRect（缩略图视口坐标），打开与关闭均为位移动画
2. 标题联动：传 titleOriginRect 时标题从列表位置平滑飞到预览落点；不传则逐渐淡入（关闭同理）
3. 多图：urls + current（下标或 url），落地后横向 swiper
4. 双指缩放：以双指中点为锚点缩放（transform-origin: 0 0），可平移
5. 下拉关闭：1× 时下拉跟手，超过阈值松手退出；缩放态不误触
6. 系统返回：requestClose() 走关闭动画；isOpen() 判断是否拦截返回

快速上手（30 秒）

<template>
    <view>
        <image
            id="thumb"
            :src="urls[0]"
            mode="aspectFill"
            style="width:200rpx;height:200rpx"
            @click="openPreview"
        />
        <!-- 量 titleOriginRect 用；不需要标题飞入可去掉本节点并不传 title-origin-rect -->
        <text id="title" class="demo-title">{{ title }}</text>
        <image-preview-popup
            ref="preview"
            :visible="visible"
            :urls="urls"
            :current="current"
            :title="title"
            :origin-rect="originRect"
            :title-origin-rect="titleOriginRect"
            @close="visible = false"
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            visible: false,
            urls: [
                'https://via.placeholder.com/800',
                'https://via.placeholder.com/801'
            ],
            current: 0,
            title: '示例商品名',
            originRect: null,
            titleOriginRect: null
        }
    },
    methods: {
        openPreview() {
            const q = uni.createSelectorQuery().in(this)
            q.select('#thumb').boundingClientRect()
            q.select('#title').boundingClientRect()
            q.exec((res) => {
                const img = res && res[0]
                const tit = res && res[1]
                this.originRect =
                    img && img.width > 0
                        ? {
                            left: img.left,
                            top: img.top,
                            width: img.width,
                            height: img.height
                        }
                        : null
                // 有标题源位置 → 飞入；不传 / null → 标题仅淡入
                this.titleOriginRect =
                    tit && tit.width > 0
                        ? {
                            left: tit.left,
                            top: tit.top,
                            width: tit.width,
                            height: tit.height
                        }
                        : null
                this.current = 0
                this.visible = true
            })
        },
        /** 系统返回时调用 */
        closePreview() {
            const p = this.$refs.preview
            if (p && typeof p.requestClose === 'function') p.requestClose()
            else this.visible = false
        }
    }
}
</script>

无动画也能开

• 不传 originRect：图片淡入全屏
• 不传 titleOriginRect：标题逐渐出现（不位移）
  适合浮层内量点困难的场景。

系统返回拦截（强烈建议）

微信小程序

页面根层用单一 page-container：预览打开时 show=true，beforeleave 里调用 requestClose()，不要为预览再挂第二个 page-container。

App

onBackPress() {
    const p = this.$refs.preview
    if (p && p.isOpen && p.isOpen()) {
        p.requestClose()
        return true
    }
    return false
}

API

Props

Events

Methods（ref）

授权说明

• 本插件无广告、不采集用户数据、不申请系统权限
• 售出后请遵守 DCloud 插件市场付费插件规范
• 技术交流 QQ：1981308200

常见问题

Q：飞入起点不对？
A：在 visible = true 之前设好 originRect；用 createSelectorQuery().in(this) 量缩略图。量不到可传 null 走淡入。

Q：和页内全屏浮层一起用预览被挡住？
A：预览建议挂在页面上、在打开时再挂 root-portal（后创建压上层），避免嵌在已被裁切的浮层里。

Q：支持 Vue3 吗？
A：支持。easycom 引入即可；Options API 示例可直接用。

更新日志

见 changelog.md

版本

1.1.0 · 2026-08-03