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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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>

点击查看

点击图片可预览大图

点击查看

点击图片会触发 imageClick 事件

<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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
  getLandscapeImage,
} 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 { ref } from 'vue';
import { ImageDisplay } from '@coffic/cosy-ui/vue';
import {
  getExampleImage,
  getAvatarImage,
  getProductImage,
} 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 clickedImages = ref<string[]>([]);

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