---
url: /components/image-preview.md
---
# ImagePreview 图片预览

`EvImagePreview` 全屏灯箱预览：遮罩 + 居中大图，支持左右箭头与键盘 ← → 切换、
Esc / 点击遮罩关闭、打开期间锁定页面滚动，多图时右下角显示计数。
通常配合 [ImageWall 图片墙](./image-wall) 使用，也可独立受控调用。

## 独立受控用法


\<EvButton @click="previewVisible = true">打开图片预览

```vue
<EvImagePreview v-model="visible" v-model:index="index" :images="images" />
<EvButton @click="visible = true">打开图片预览</EvButton>
```

## 磨砂预览背景


\<EvButton @click="glassPreviewVisible = true">打开磨砂预览

```vue
<EvImagePreview v-model="visible" glass :images="images" />
```

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| modelValue (v-model) | 可见性 | boolean | `false` |
| images | 图片列表：url 字符串或 `{ src, alt }` | array | `[]` |
| index (v-model:index) | 当前下标 | number | `0` |
| esc-close | Esc 关闭 | boolean | `true` |
| glass | 磨砂预览背景；缺省跟随全局（ConfigProvider glass） | boolean | — |
| blur | 磨砂强度（px），内联覆盖 `--ev-glass-blur` | string / number | — |
| saturate | 磨砂饱和度（倍数），内联覆盖 `--ev-glass-saturate` | string / number | — |
| tint | 磨砂底色浓度（%），内联覆盖 `--ev-glass-bg` | string / number | — |

### 事件

| 事件 | 说明 |
| --- | --- |
| update:modelValue / update:index | 双向绑定 |
| open / close | 打开 / 关闭时触发 |
| change | 切换图片时触发，参数为新下标 |