Vue

ImageDisplay

简介

ImageDisplay 组件是一个功能丰富的图片展示组件，支持图片网格布局、点击预览、错误处理等功能。适用于需要展示多张图片的场景，如相册、产品图片展示、用户头像列表等。组件支持多种尺寸配置，提供流畅的交互体验和优雅的错误处理。

案例

点击查看

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="4"
      @image-click="handleImageClick"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	// 使用固定的随机种子，确保服务端和客户端一致
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	// 使用固定的标签，确保一致性
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	// 头像使用固定种子
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	// 产品图片使用固定标签
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	// 机器人头像使用固定种子
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	// 占位符图片使用固定文本
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];

const handleImageClick = (imageUrl: string) => {
	console.log("点击了图片:", imageUrl);
};
</script>

Props

images

图片URL数组，必填属性。

点击查看

<template>
  <div>
    <ImageDisplay
      :images="fewImages"
      size="md"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const fewImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable2",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="mediumImages"
      size="md"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const mediumImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="manyImages"
      size="md"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const manyImages = [
	// 使用不同的图片服务提供商，但保持稳定的随机种子
	...Array.from({ length: 3 }, (_, i) =>
		getExampleImage({
			width: 200,
			height: 200,
			provider: "picsum",
			randomSeed: `stable-picsum-${i + 1}`,
		}),
	),
	...Array.from({ length: 3 }, (_, i) =>
		getExampleImage({
			width: 200,
			height: 200,
			provider: "picsum",
			tag: ["nature", "city", "food"][i],
			randomSeed: `stable-picsum-${i + 1}`,
		}),
	),
	...Array.from({ length: 3 }, (_, i) =>
		getAvatarImage({ width: 200, height: 200, randomSeed: `user${i + 1}` }),
	),
	...Array.from({ length: 3 }, (_, i) =>
		getProductImage({
			width: 200,
			height: 200,
			tag: ["tech", "fashion", "home"][i],
			randomSeed: `stable-product-${i + 1}`,
		}),
	),
];
</script>

maxDisplay

最大显示图片数量，超出部分会显示 “+N 更多” 提示。

点击查看

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="3"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="4"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

showPreview

是否显示预览功能，设置为 false 时点击图片会触发 imageClick 事件。

点击查看

点击图片可预览大图

点击查看

点击图片会触发 imageClick 事件

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="4"
      @image-click="handleImageClick"
    />
    <p class="text-xs text-gray-500 mt-1">点击图片可预览大图</p>
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable2",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable3",
	}),
];

const handleImageClick = (imageUrl: string) => {
	console.log("点击了图片:", imageUrl);
	alert(`点击了图片: ${imageUrl}`);
};
</script>

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="false"
      :max-display="4"
      @image-click="handleImageClick"
    />
    <p class="text-xs text-gray-500 mt-1">点击图片会触发 imageClick 事件</p>
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable2",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable3",
	}),
];

const handleImageClick = (imageUrl: string) => {
	console.log("点击了图片:", imageUrl);
	alert(`点击了图片: ${imageUrl}`);
};
</script>

size

图片尺寸大小，支持 sm、md、lg 三种尺寸。

点击查看

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="sm"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="md"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

<template>
  <div>
    <ImageDisplay
      :images="sampleImages"
      size="lg"
      :show-preview="true"
      :max-display="6"
    />
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getLandscapeImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable2",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable3",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "robohash",
		randomSeed: "robot1",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "placeholder",
		tag: "Image 6",
		randomSeed: "stable4",
	}),
];
</script>

Events

imageClick

图片点击事件，当 showPreview 为 false 时触发。

事件处理示例

点击查看

点击图片查看控制台输出

<template>
  <div class="space-y-4">
    <div>
      <h4 class="text-sm font-medium mb-2">事件处理示例</h4>
      <ImageDisplay
        :images="sampleImages"
        size="md"
        :show-preview="false"
        :max-display="4"
        @image-click="handleImageClick"
      />
      <p class="text-xs text-gray-500 mt-1">点击图片查看控制台输出</p>
    </div>

    <div v-if="clickedImages.length > 0">
      <h4 class="text-sm font-medium mb-2">已点击的图片:</h4>
      <div class="space-y-2">
        <div
          v-for="(image, index) in clickedImages"
          :key="index"
          class="flex items-center space-x-2 p-2 bg-gray-100 rounded"
        >
          <img
            :src="image"
            alt="点击的图片"
            class="w-8 h-8 object-cover rounded"
          />
          <span class="text-sm">{{ image }}</span>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { 
	getAvatarImage,
	getExampleImage,
	getProductImage,ImageDisplay, } from "@coffic/cosy-ui/vue";
import { ref } from "vue";

// 使用稳定的图片URL，避免水合不匹配
const sampleImages = [
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		randomSeed: "stable1",
	}),
	getAvatarImage({ width: 200, height: 200, randomSeed: "user1" }),
	getProductImage({
		width: 200,
		height: 200,
		tag: "tech",
		randomSeed: "stable2",
	}),
	getExampleImage({
		width: 200,
		height: 200,
		provider: "picsum",
		tag: "nature",
		randomSeed: "stable3",
	}),
];

const clickedImages = ref<string[]>([]);

const handleImageClick = (imageUrl: string) => {
	console.log("点击了图片:", imageUrl);
	clickedImages.value.push(imageUrl);
};
</script>