ImageViewer 图片预览

可点击放大的图片与预览组

何时使用

  • 需要放大预览图片时。

导入

import { Image, PreviewGroup, ImageViewer } from "@reglow/reui";

加载失败提示等文案默认跟随全局语言（zh-CN / zh-TW / en-US）。

基础用法

预览图片

单击图像可以放大显示。

<script setup>
import { Image } from "@reglow/reui";
</script>

<template>
  <Image
    :width="200"
    height="200"
    src="https://example.com/image.jpg"
    alt="图片描述"
  />
</template>

渐进加载

通过 placeholder 属性设置占位符。设为 true 时显示进度动画。

<script setup>
import { ref } from "vue";
import { Image } from "@reglow/reui";

const timestamp = ref("");
</script>

<template>
  <Image
    :src="`/big-image.png?${timestamp}`"
    :width="300"
    :height="200"
    :placeholder="true"
  />
  <button @click="timestamp = Date.now()">重新加载</button>
</template>

自定义占位

传入自定义 VNode 作为占位符。

<script setup>
import { h } from "vue";
import { Image } from "@reglow/reui";
import { Loader2 } from "lucide-vue-next";

const placeholder = h(Loader2, {
  class: "size-6 animate-spin text-muted-foreground",
});
</script>

<template>
  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :placeholder="placeholder"
  />
</template>

容错处理

加载失败显示图像占位符，可通过 fallback 设置容错图片地址。

<template>
  <!-- 默认失败占位 -->
  <Image src="/error.jpg" :width="200" :height="200" />

  <!-- 自定义容错地址 -->
  <Image src="/error.jpg" fallback="/fallback.png" :width="200" :height="200" />
</template>

多张图片预览

使用 PreviewGroup 包裹 Image，点击可预览多张图片。

<script setup>
import { Image, PreviewGroup } from "@reglow/reui";

const srcList = ["/image1.jpg", "/image2.jpg", "/image3.jpg"];
</script>

<template>
  <PreviewGroup>
    <div class="flex gap-2">
      <Image
        v-for="src in srcList"
        :key="src"
        :src="src"
        :width="200"
        :height="200"
      />
    </div>
  </PreviewGroup>
</template>

相册模式（items）

通过 items 属性直接传入图片数组。

<script setup>
import { Image, PreviewGroup } from "@reglow/reui";

const items = ["/image1.jpg", "/image2.jpg", "/image3.jpg", "/image4.jpg"];
</script>

<template>
  <PreviewGroup :items="items" :preview="{ current: 0 }">
    <Image :src="items[0]" :width="200" :height="200" />
  </PreviewGroup>
</template>

自定义预览图片

通过 preview.src 设置不同的预览大图。

<template>
  <Image
    src="/thumbnail.jpeg"
    :width="300"
    :height="200"
    :preview="{ src: '/full-size.png' }"
  />
</template>

受控的预览

通过 preview.open 和 preview.onOpenChange 控制预览。

<script setup>
import { ref } from "vue";
import { Image } from "@reglow/reui";

const open = ref(false);
</script>

<template>
  <button @click="open = true">打开预览</button>
  <button @click="open = false">关闭预览</button>

  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :preview="{
      open: open,
      onOpenChange: (val) => (open = val),
    }"
  />
</template>

缩放步长

通过 preview.scaleStep 设置缩放步长。

<template>
  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :preview="{
      scaleStep: 0.2,
      minScale: 1,
      maxScale: 10,
    }"
  />
</template>

预览遮罩

通过 preview.mask 设置预览遮罩效果。

<template>
  <!-- 默认遮罩 -->
  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :preview="{ mask: true }"
  />

  <!-- 模糊遮罩 -->
  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :preview="{ mask: { blur: true, closable: true } }"
  />

  <!-- 无遮罩 -->
  <Image
    src="/image.jpg"
    :width="200"
    :height="200"
    :preview="{ mask: false }"
  />
</template>

禁用预览

设置 preview 为 false 禁用预览。

<template>
  <Image src="/image.jpg" :width="200" :height="200" :preview="false" />
</template>

预览组件单独使用

ImageViewer 可单独使用。

<script setup>
import { ref } from "vue";
import { ImageViewer } from "@reglow/reui";

const open = ref(false);
const srcList = ["/image1.jpg", "/image2.jpg", "/image3.jpg"];
</script>

<template>
  <button @click="open = true">预览</button>

  <ImageViewer v-model:open="open" :src="srcList" :default-current="0" />
</template>

受控的 PreviewGroup

通过 preview 对象的 open 与 current 控制。

<script setup>
import { ref } from "vue";
import { Image, PreviewGroup } from "@reglow/reui";

const open = ref(false);
const current = ref(0);
</script>

<template>
  <button @click="open = true">打开预览</button>

  <PreviewGroup
    :preview="{
      open,
      current,
      onOpenChange: (val) => (open = val),
      onChange: (val) => (current = val),
    }"
    :items="['/image1.jpg', '/image2.jpg']"
  >
    <Image src="/image1.jpg" :width="200" :height="200" />
  </PreviewGroup>
</template>

API

Image Props

参数说明类型默认值
src图片地址string-
alt图像描述string-
width图像宽度string | number-
height图像高度string | number-
fallback加载失败容错地址string-
placeholder加载占位VNode | boolean-
preview预览参数，为 false 时禁用boolean | PreviewTypetrue
previewMask是否显示预览遮罩booleantrue
crossOrigincrossoriginanonymous | use-credentials-
class附加类名string-

Image Events

事件说明回调参数
error加载错误回调(event: Event)

PreviewGroup Props

参数说明类型默认值
items预览数组string[] | ImagePreviewItem[][]
preview预览参数，为 false 时禁用boolean | PreviewGroupTypetrue
fallback加载失败容错地址string-

PreviewGroup Events

事件说明回调参数
update:open显示状态变化(open: boolean)
update:current当前图片变化(current: number)
openChange预览打开状态变化(open: boolean, info: { current: number })
change切换预览图(current: number, prevCurrent: number)

PreviewType

参数说明类型默认值
src自定义预览 srcstring-
open是否显示预览boolean-
onOpenChange预览打开状态变化回调(open: boolean) => void-
scaleStep缩放步长number0.5
minScale最小缩放倍数number1
maxScale最大缩放倍数number50
movable是否可移动booleantrue
mask遮罩效果boolean | { enabled?: boolean; blur?: boolean; closable?: boolean }true
getContainer指定预览挂载节点string | HTMLElement | (() => HTMLElement) | false-
closeIcon自定义关闭 IconVNode-
actionsRender自定义工具栏(originalNode, info) => VNode-
imageRender自定义预览内容(originalNode, info) => VNode-

PreviewGroupType

继承 PreviewType，额外支持：

参数说明类型默认值
current当前预览图 indexnumber-
onChange切换预览图回调(current: number, prevCurrent: number) => void-
countRender自定义计数内容(current: number, total: number) => VNode-

键盘快捷键

按键功能
ESC关闭预览
←上一张
→下一张
+ / =放大
-缩小
R右旋转
滚轮缩放
双击重置变换
拖拽移动图片
HoverCard 悬浮卡片
悬停时展示的预览卡片
Popover 气泡卡片
基于 reka-ui 的浮层容器，用于承载自定义内容（表单、详情、操作列表等）。