giovan-webgl-image

giovan-webgl-image

Vue 3 全屏 WebGL 图片查看器，提供高清图渐进加载、缩放、拖拽、键盘翻页和 ThumbHash 占位能力。

安装

pnpm add giovan-webgl-image

使用

<script setup lang="ts">
import { ref } from 'vue'
import { FullscreenImageViewer } from 'giovan-webgl-image'
import 'giovan-webgl-image/style'

const visible = ref(false)
const images = [
  {
    id: 'waterfall',
    src: 'https://example.com/photos/waterfall.jpeg',
    thumbnailSrc: 'https://example.com/photos/waterfall.webp',
    thumbhash: '4ecNHQJYh3+Hd5bHeIpnd3dwdwY3',
    alt: '瀑布',
  },
]
</script>

<template>
  <button type="button" @click="visible = true">查看图片</button>

  <FullscreenImageViewer
    v-model="visible"
    :images="images"
  />
</template>

FullscreenImageViewer

Props

属性	类型	默认值	说明
v-model	boolean	-	是否显示查看器
images	FullscreenImage[]	-	图片列表
initial-index	number	0	初始展示图片的索引

图片数据

interface FullscreenImage {
  id: string | number
  src: string
  thumbnailSrc?: string
  thumbhash?: string
  alt?: string
}

查看器优先显示 thumbnailSrc；没有缩略图时使用 thumbhash 作为模糊占位。高清 src 加载完成后会淡入替换占位图。

事件

事件	参数	说明
update:modelValue	boolean	关闭查看器时触发
index-change	number	切换当前图片时触发
image-error	FullscreenImage	高清图片加载失败时触发

方法

<script setup lang="ts">
import { ref } from 'vue'
import type { FullscreenImageViewerRef } from 'giovan-webgl-image'

const viewerRef = ref<FullscreenImageViewerRef>()

viewerRef.value?.previous()
viewerRef.value?.next()
viewerRef.value?.close()
</script>

交互

• Esc 关闭查看器
• 左右方向键切换图片
• 双击或鼠标滚轮缩放
• 拖拽平移已缩放的图片
• 触控设备支持捏合缩放
• 未缩放时单指左右滑动切换图片

跨域图片

组件会通过 XHR 下载高清图片，再交给 WebGL 渲染。图片服务器必须允许调用页面的来源，例如：

Access-Control-Allow-Origin: https://your-site.example

开发环境的 localhost 也需要包含在允许来源中；否则浏览器会阻止图片加载。