Image 图片
新粗野主义风格的图片展示组件，支持 IntersectionObserver 懒加载、加载失败备用图、大图预览模态框（含放大/缩小/旋转/翻转/拖拽），以及粗边框硬阴影搭配斜线噪点的占位背景。
预览
基础用法
大图预览（点击放大）
多图预览（左右切换）
懒加载
加载失败 + Fallback
安装
pnpm dlx brutx-vue@latest add image用法
基础用法
传入 src 和 alt 即可使用，通过 fit 控制图片填充模式：
<script setup>
import { Image } from 'brutx-ui-vue'
</script>
<template>
<Image src="/photo.jpg" alt="示例图片" fit="cover" class="w-64 h-48" />
</template>懒加载
设置 loading="lazy" 后，组件会通过 IntersectionObserver 监听元素是否进入视口，仅在可见时才加载图片：
<template>
<Image src="/large-photo.jpg" alt="懒加载图片" loading="lazy" class="w-full h-64" />
</template>备用图
当主图加载失败时，自动切换到 fallback 指定的备用图片：
<template>
<Image
src="/broken-url.jpg"
alt="测试备用图"
fallback="/fallback.jpg"
class="w-64 h-48"
/>
</template>大图预览
启用 preview 并传入 previewSrcList，点击图片即可打开全屏预览模态框：
<script setup>
import { Image } from 'brutx-ui-vue'
const images = ['/photo1.jpg', '/photo2.jpg', '/photo3.jpg']
</script>
<template>
<div class="flex gap-4">
<Image
v-for="img in images"
:key="img"
:src="img"
:alt="img"
:preview="true"
:preview-src-list="images"
class="w-32 h-32"
/>
</div>
</template>预览模态框内支持以下操作：
- 放大/缩小（通过工具栏按钮，倍率受
zoomRate控制） - 向左/向右旋转 90°
- 水平翻转
- 鼠标拖拽移动图片
ArrowLeft/ArrowRight切换上/下一张Escape关闭预览- 设置
hideOnClickModal为true可点击遮罩关闭
自定义占位和错误插槽
通过 placeholder 和 error 插槽自定义加载中和加载失败的展示内容：
<template>
<Image src="/photo.jpg" alt="自定义插槽示例" class="w-64 h-48">
<template #placeholder>
<div class="absolute inset-0 flex items-center justify-center bg-brutal-muted">
<span class="font-bold">正在加载...</span>
</div>
</template>
<template #error>
<div class="absolute inset-0 flex items-center justify-center bg-brutal-destructive/10">
<span class="text-brutal-destructive font-bold">图片加载失败</span>
</div>
</template>
</Image>
</template>数据类型
type ImageFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'| 值 | 说明 |
|---|---|
'fill' | 拉伸填满容器，不保持宽高比 |
'contain' | 保持宽高比缩放，确保图片完整显示 |
'cover' | 保持宽高比缩放，填满容器（可能裁剪） |
'none' | 保持原始尺寸 |
'scale-down' | 类似 contain，但不会放大超过原始尺寸 |
API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src必填 | string | — | 必填的主图片 URL；预览列表为空时也作为预览器的唯一图片。 |
详情 | |||
alt | string | undefined | "" | 传递给原生 img 的替代文本；应说明图片内容以供辅助技术读取。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/image/Image.vue | |||
fit | "fill" | "none" | "cover" | "contain" | "scale-down" | undefined | "cover" | 设置图片的 CSS object-fit 填充模式。 |
详情声明类型"fill" | "none" | "cover" | "contain" | "scale-down" | undefined 字面量
默认值详情
来源packages/ui/src/components/image/Image.vue | |||
previewSrcList | string[] | undefined | []按实例调用工厂函数 | 设置预览器可切换的图片 URL 列表；包含多个地址时会显示上一张和下一张操作。 |
详情声明类型string[] | undefined 默认值详情
来源packages/ui/src/components/image/Image.vue | |||
initialIndex | number | undefined | 0 | 设置打开预览器时选中的列表索引。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/image/Image.vue | |||
hideOnClickModal | boolean | undefined | false | 启用后，点击预览遮罩关闭预览；关闭时焦点会归还到打开预览前的元素。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/image/Image.vue | |||
zoomRate | number | undefined | 1.2 | 设置每次放大或缩小操作所用的缩放倍率。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/image/Image.vue | |||
preview | boolean | undefined | false | 启用图片预览器及其缩放、拖拽和多图切换交互。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/image/Image.vue | |||
fallback | string | undefined | undefined | 主图片加载失败后尝试加载的备用图片 URL；备用图片也失败时才进入错误状态并发出 error。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/image/Image.vue | |||
loading | "eager" | "lazy" | undefined | "eager" | 选择 eager 立即加载或 lazy 在元素接近视口时通过 IntersectionObserver 延迟加载。 |
详情声明类型"eager" | "lazy" | undefined 字面量
默认值详情
来源packages/ui/src/components/image/Image.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@close | [] | 预览器关闭时发出；关闭时组件会尝试将焦点恢复到打开预览前的活动元素。 |
详情声明类型[] 来源packages/ui/src/components/image/Image.vue | ||
@error | [event: Event] | 主图片加载失败且备用图片也未能加载时，携带最后一次原生图片错误事件发出。 |
详情声明类型[event: Event] 来源packages/ui/src/components/image/Image.vue | ||
@load | [event: Event] | 图片成功加载时携带原生图片事件发出；备用图片加载成功也会触发。 |
详情声明类型[event: Event] 来源packages/ui/src/components/image/Image.vue | ||
@show | [] | 预览器打开时发出。 |
详情声明类型[] 来源packages/ui/src/components/image/Image.vue | ||
@switch | [index: number] | 预览器切换到另一张图片后，携带新的图片列表索引发出。 |
详情声明类型[index: number] 来源packages/ui/src/components/image/Image.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#placeholder | {} | 图片加载期间渲染自定义占位内容；未提供时显示组件内置的加载占位。 |
详情声明类型{}来源packages/ui/src/components/image/Image.vue | ||
#error | {} | 图片及备用图片加载失败后渲染自定义错误内容；未提供时显示组件内置的失败占位。 |
详情声明类型{}来源packages/ui/src/components/image/Image.vue | ||
可访问性
- 键盘操作：预览模态框支持
Escape关闭、ArrowLeft/ArrowRight切换图片 - ARIA 属性：预览模态框中的关闭、上一张、下一张按钮均带有
aria-label属性；始终建议提供有意义的alt文本，以便屏幕阅读器和图片加载失败时使用 - 焦点管理：预览模态框使用 reka-ui 的
FocusScope组件，启用trapped和loop模式，确保焦点不会逃逸到模态框之外
常见问题
Q: 设置 loading="lazy" 后图片不显示？
A: 懒加载依赖 IntersectionObserver，需要确保组件容器有确定的尺寸（通过 class 或父容器设定宽高）。如果容器尺寸为零，IntersectionObserver 不会触发回调。
Q: 点击预览后如何切换图片？
A: 需要同时传入 previewSrcList 数组。在预览模态框中，可通过左右箭头按钮、键盘方向键切换图片。如果 previewSrcList 只有一张或为空，切换按钮不会显示。
Q: fallback 图片也加载失败会怎样？
A: 当备用图也加载失败时，组件会进入错误状态，显示 error 插槽的内容（或默认的错误占位），并触发 error 事件。