Cube-UI 图片预览组件 ImagePreview 使用指南

Cube-UI 图片预览组件 ImagePreview 使用指南

【免费下载链接】cube-ui :large_orange_diamond: A fantastic mobile ui lib implement by Vue 项目地址: https://gitcode.com/gh_mirrors/cu/cube-ui

什么是 ImagePreview 组件

ImagePreview 是 Cube-UI 提供的一个功能强大的图片预览组件，它可以帮助开发者快速实现移动端常见的图片浏览功能。该组件支持以下核心特性：

1. 多图浏览：支持一组图片的展示和切换
2. 手势操作：支持左右滑动切换图片
3. 缩放功能：支持双指缩放查看图片细节
4. 自定义配置：提供多种配置选项满足不同场景需求

基础使用

基本用法

要使用 ImagePreview 组件，首先需要准备一个图片 URL 数组，然后通过 $createImagePreview 方法创建实例并调用 show() 方法显示：

<template>
  <cube-button @click="showImagePreview">显示图片预览</cube-button>
</template>

<script>
export default {
  data() {
    return {
      imgs: [
        'https://example.com/image1.jpg',
        'https://example.com/image2.jpg',
        'https://example.com/image3.jpg'
      ]
    }
  },
  methods: {
    showImagePreview() {
      if (!this.imagePreview) {
        this.imagePreview = this.$createImagePreview({
          imgs: this.imgs
        })
      }
      this.imagePreview.show()
    }
  }
}
</script>

注意事项

ImagePreview 组件使用了 Cube-UI 的 create-api 机制创建，因此在使用前需要确保已经正确配置了 create-api。这种机制的优势在于可以动态创建组件实例，而不需要预先在模板中声明。

高级配置

自定义参数

ImagePreview 提供了丰富的配置选项，可以满足各种定制化需求：

this.customImagePreview = this.$createImagePreview({
  imgs: this.imgs,
  initialIndex: 1, // 初始显示第2张图片
  loop: false,     // 禁用循环滑动
  speed: 500,      // 切换动画时间为500ms
  onChange: (i) => { // 切换回调
    console.log('当前图片索引:', i)
  },
  onHide: () => {   // 隐藏回调
    console.log('预览已关闭')
  }
})

自定义头部和底部

通过 render 函数可以自定义预览界面的头部和底部内容：

this.$createImagePreview({
  // 配置参数...
}, (h) => {
  return h('div', {
    class: 'custom-header',
    slot: 'header'
  }, '自定义头部内容')
})

多图点击预览场景

在实际应用中，经常会有点击缩略图查看大图的需求。ImagePreview 可以很好地支持这种场景：

<template>
  <div class="thumbnail-container">
    <img 
      v-for="(img, index) in imgs"
      :key="index"
      :src="img"
      @click="showPreview(index)">
  </div>
</template>

<script>
export default {
  methods: {
    showPreview(index) {
      this.$createImagePreview({
        imgs: this.imgs,
        initialIndex: index,
        loop: false
      }).show()
    }
  }
}
</script>

配置项详解

ImagePreview 组件提供了以下可配置属性：

属性名	说明	类型	可选值	默认值
imgs	图片URL数组	Array	-	[]
initialIndex	初始显示的图片索引	Number	-	0
loop	是否循环滑动	Boolean	true/false	true
speed	切换动画速度(ms)	Number	-	400
zIndex	组件z-index值	Number	-	100
preventDefault	是否阻止默认事件	Boolean	true/false	true

插槽与事件

插槽

ImagePreview 提供了两个插槽用于自定义内容：

1. header - 头部内容插槽
2. footer - 底部内容插槽

这两个插槽都会接收当前图片索引作为作用域参数。

事件

组件提供了两个主要事件：

1. change - 当切换图片时触发，参数为当前图片索引
2. hide - 当预览关闭时触发

最佳实践

1. 性能优化：对于大量图片，建议使用懒加载技术
2. 错误处理：为图片添加错误处理，避免因图片加载失败影响用户体验
3. 手势优化：在移动端，合理配置 preventDefault 属性以获得更好的手势体验
4. 内存管理：长时间不使用的预览实例应该及时销毁

通过合理配置和使用 ImagePreview 组件，开发者可以快速实现专业级的图片浏览功能，提升应用的用户体验。

【免费下载链接】cube-ui :large_orange_diamond: A fantastic mobile ui lib implement by Vue 项目地址: https://gitcode.com/gh_mirrors/cu/cube-ui