更新记录

1.0.0（2026-11-02） 下载此版本

• 首次发布
• 支持九宫格缩略图与全屏图片预览
• 支持从缩略图/主图位置放大、缩小回位动画
• 支持商品规格/价格数据驱动展示
• 支持 header / footer 插槽与作用域插槽
• 兼容微信小程序、App-vue、H5/Web

平台兼容性

uni-app(5.34)

cs-peeview 图片九宫格放大预览

带缩略图九宫格与「从原图位置放大 / 缩小回位」动画的图片预览组件。
已验证平台：微信小程序、App-vue、H5/Web。

平台支持

网络图片请在对应端配置合法域名（小程序 download/request 合法域名、App 网络安全配置等）。

安装

1. 插件市场导入，或将本插件目录放到项目：

   uni_modules/cs-peeview/

2. 符合 easycom 规范，无需在 pages.json 注册，也无需手动 import。
3. 页面中直接使用标签：<cs-peeview />

手动引入（可选）：

import CsPeeview from '@/uni_modules/cs-peeview/components/cs-peeview/cs-peeview.vue'
export default {
  components: { CsPeeview }
}

快速开始（三端通用）

<template>
  <cs-peeview
    :list="list"
    @open="onOpen"
    @close="onClose"
    @change="onChange"
    @image="onImage"
  />
</template>

<script>
export default {
  data() {
    return {
      list: [
        { id: 1, src: 'https://example.com/1.jpg' },
        { id: 2, src: 'https://example.com/2.jpg' },
        // 也可直接传字符串 URL
        'https://example.com/3.jpg'
      ]
    }
  },
  methods: {
    onOpen(e) { console.log('打开', e.index) },
    onClose(e) { console.log('关闭', e.index) },
    onChange(e) { console.log('切换', e.index, e.current) },
    onImage(e) { console.log('点击大图', e.current.src) }
  }
}
</script>

点击九宫格缩略图即可打开预览；点击空白处关闭。

Props

list 单项字段

事件

事件回调参数统一为：

{
  index: Number,   // 当前下标
  current: Object, // 当前图片对象
  list: Array      // 规范化后的图片列表
}

方法（ref 调用）

this.$refs.pv.open(index)           // 打开指定下标
this.$refs.pv.close()               // 关闭
this.$refs.pv.isOpen()              // 是否处于预览中
this.$refs.pv.onThumbLoad(index, e) // 外部缩略图/主图 @load 时喂入真实宽高，避免变形

插槽

具名插槽

默认作用域插槽

传入默认插槽可完全自定义 UI，作用域参数包含：list、previewVisible、open、close、onThumbLoad 等。一般业务用内置 UI + header/footer 即可。

场景示例

1. 商品图（规格 / 价格）

<cs-peeview :list="goodsList" :show-indicator="true" :preview-width="0.85" />

goodsList: [
  { id: 'g1', src: '...', spec: '星空蓝 / 128GB', price: '5999' },
  { id: 'g2', src: '...', spec: '月光白 / 256GB', price: '6799' }
]

2. 自定义头部 / 底部

<cs-peeview ref="pv" :list="list" :show-indicator="false">
  <template #header>
    <view class="bar">
      <text @click="$refs.pv.close()">关闭</text>
    </view>
  </template>
  <template #footer>
    <view class="tip">长按可保存 · 点击空白关闭</view>
  </template>
</cs-peeview>

3. 主图预览（隐藏九宫格）

适用于详情页大图 + 缩略图条，从主图位置放大：

<template>
  <image
    id="detail-banner"
    :src="list[current].src"
    mode="aspectFill"
    @click="openPreview()"
    @load="onBannerLoad"
  />
  <image
    v-for="(item, i) in list"
    :key="item.id"
    :src="item.src"
    @click="openPreview(i)"
    @load="onThumbLoad(i, $event)"
  />

  <cs-peeview
    ref="pv"
    :list="list"
    :show-thumbs="false"
    origin-selector="#detail-banner"
    @close="onClose"
  />
</template>

<script>
export default {
  data() {
    return {
      current: 0,
      list: [/* ... */]
    }
  },
  methods: {
    openPreview(i) {
      const idx = typeof i === 'number' ? i : this.current
      this.current = idx
      this.$refs.pv.open(idx)
    },
    onBannerLoad(e) {
      this.$refs.pv && this.$refs.pv.onThumbLoad(this.current, e)
    },
    onThumbLoad(i, e) {
      this.$refs.pv && this.$refs.pv.onThumbLoad(i, e)
    },
    onClose(e) {
      this.current = e.index
    }
  }
}
</script>

各端注意事项

微信小程序

1. 远程图片域名需加入小程序后台「downloadFile / request 合法域名」。
2. origin-selector 使用页面级节点 id（如 #detail-banner），组件会用页面级 createSelectorQuery 查询。
3. 保存到相册需自行处理 scope.writePhotosAlbum 授权（组件本身不申请权限）。

App-vue

1. 与小程序用法相同；使用 vue 页面，勿用于 nvue。
2. Android 访问 http 图片时注意网络安全策略（cleartext）。

H5 / Web

1. 组件会将预览层移动到 body，避免被带 overflow/transform 的父节点裁切。
2. 浏览器端同样支持 origin-selector（document.querySelector）。
3. 跨域图片若需 canvas 处理/下载，请确保图片服务器 CORS 配置正确。

常见问题

Q: 预览图被压成正方形？
A: 在缩略图或主图 @load 时调用 onThumbLoad(index, e)，或在 list 里带上 width/height。

Q: 主图场景打不开或起点不对？
A: 确认 show-thumbs="false"、设置了正确的 origin-selector，并在打开前节点已渲染完成。

Q: 切换 Tab 后预览层还在？
A: 切换前调用 this.$refs.pv.close()，或用 isOpen() 判断后关闭。

目录结构

uni_modules/cs-peeview/
├── components/cs-peeview/cs-peeview.vue
├── package.json
├── readme.md
└── changelog.md