vuetify-image-viewer

v1.1.4

Published

23 days ago

A fullscreen image preview dialog component for Vuetify 3, with zoom, rotate, download and Ctrl+wheel support.

0High
0Medium
0Low

smeevil

vuetify image preview viewer zoom rotate vue component

vuetify-image-viewer

适用于 Vuetify 3 的全屏图片预览对话框组件，支持缩放、旋转、下载及 Ctrl+滚轮缩放。图标使用 @mdi/js SVG path 渲染，无需额外配置 Vuetify 图标别名。

A fullscreen image preview dialog component for Vuetify 3, with zoom, rotate, download, and Ctrl+wheel zoom support. Icons are rendered from @mdi/js SVG paths — no additional Vuetify icon alias configuration required.

安装 / Installation

npm install vuetify-image-viewer

对等依赖 / Peer Dependencies

vue ^3.3.0
vuetify ^3.0.0

前提条件 / Requirements

你的项目需要已经配置好 Vuetify 3（createVuetify() + app.use(vuetify)）。本组件内部已自行导入所需的 Vuetify 子组件，你不需要在 Vuetify 配置中手动注册任何组件。

Your project must have Vuetify 3 configured (createVuetify() + app.use(vuetify)). This component imports the required Vuetify sub-components internally — you don't need to manually register any components in Vuetify config.

import { createVuetify } from 'vuetify'

const app = createApp(App)
app.use(createVuetify()) // ✅ 必须，组件依赖 Vuetify 的主题/图标/指令等基础设施 / Required — component depends on Vuetify's theme/icons/directives infrastructure
app.mount('#app')

用法 / Usage

全局注册 / Global Registration

import { createApp } from 'vue'
import App from './App.vue'
import VuetifyImageViewer from 'vuetify-image-viewer'

const app = createApp(App)
app.use(VuetifyImageViewer)
app.mount('#app')

局部导入 / Local Import

<script setup lang="ts">
import { ImageViewer } from 'vuetify-image-viewer'
import type { ImageItem } from 'vuetify-image-viewer'
</script>

单图模式（向后兼容）/ Single Image Mode (Backward Compatible)

和 v1.0 用法完全一致，无需任何改动。Identical to v1.0 usage — no changes needed.

<template>
  <ImageViewer
    v-model:preview-dialog="show"
    :preview-src="url"
    header-text="图片标题 / Image Title"
    sub-header-text="副标题 / Subtitle"
    file-name="download.png"
  />
</template>

多图模式（v1.1.0 新增）/ Multi Image Mode (v1.1.0+)

传入 images 数组即可启用多图模式，对话框内会显示左右切换按钮和计数器。Pass an images array to enable multi-image mode. Left/right navigation buttons and a counter will appear in the dialog.

<script setup lang="ts">
import { ref } from 'vue'
import { ImageViewer } from 'vuetify-image-viewer'
import type { ImageItem } from 'vuetify-image-viewer'

const dialog = ref(false)
const currentIndex = ref(0)

const images: ImageItem[] = [
  { src: 'https://example.com/1.jpg', title: '风景一 / Scenery 1', subtitle: '1600 x 1067', fileName: 'scenic-1.jpg' },
  { src: 'https://example.com/2.jpg', title: '风景二 / Scenery 2', subtitle: '1200 x 800',  fileName: 'scenic-2.jpg' },
  { src: 'https://example.com/3.jpg', title: '风景三 / Scenery 3', subtitle: '800 x 600',   fileName: 'scenic-3.jpg' },
]

const openPreview = (index: number) => {
  currentIndex.value = index
  dialog.value = true
}
</script>

<template>
  <!-- 点击缩略图打开对应图片 / Click thumbnails to open the corresponding image -->
  <v-img
    v-for="(img, i) in images"
    :key="i"
    :src="img.src"
    @click="openPreview(i)"
  />

  <!-- 多图预览组件 / Multi-image preview component -->
  <ImageViewer
    v-model:preview-dialog="dialog"
    v-model:current-index="currentIndex"
    :images="images"
  />
</template>

ImageItem 类型定义 / Type Definition

interface ImageItem {
  src: string       // 图片 URL（必填）/ Image URL (required)
  title?: string    // 标题 / Title
  subtitle?: string // 副标题 / Subtitle
  fileName?: string // 下载文件名 / Download file name
}

Props

| Prop | 类型 / Type | 默认值 / Default | 描述 / Description | |---|---|---|---| | previewDialog | boolean | false | 对话框是否可见（v-model:preview-dialog）/ Dialog visibility | | previewSrc | string | '' | 图片 URL（单图模式）/ Image URL (single image mode) | | headerText | string | '图片预览' | 标题（单图模式 / 多图模式兜底值）/ Title (single image mode / fallback for multi-image mode) | | subHeaderText | string | '' | 副标题（单图模式 / 多图模式兜底值）/ Subtitle (single image mode / fallback for multi-image mode) | | fileName | string | '' | 下载文件名（单图模式）/ Download file name (single image mode) | | images | ImageItem[] | [] | 图片列表（多图模式），传入非空数组自动启用 / Image list (multi-image mode); passing a non-empty array enables it automatically | | currentIndex | number | 0 | 当前显示图片索引（v-model:current-index）/ Currently displayed image index | | icons | object | {} | 自定义图标 SVG path / Custom icon SVG paths (see below) |

图标 / Icons

可以通过 icons prop 覆盖任意按钮的 SVG 图标。You can override any button's SVG icon via the icons prop:

interface Icons {
  zoomIn?: string
  zoomOut?: string
  rotateLeft?: string
  rotateRight?: string
  reset?: string
  download?: string
  fullscreen?: string
  fullscreenExit?: string
  close?: string
  imageBroken?: string
  chevronLeft?: string   // v1.1.0 新增：左切换按钮 / v1.1.0+: left navigation button
  chevronRight?: string  // v1.1.0 新增：右切换按钮 / v1.1.0+: right navigation button
}

事件 / Events

| 事件 / Event | 载荷 / Payload | 描述 / Description | |---|---|---| | update:previewDialog | boolean | 对话框可见性变化 / Dialog visibility changed | | update:currentIndex | number | 当前图片索引变化（多图模式）/ Current image index changed (multi-image mode) |

功能特性 / Features

全屏对话框 / Fullscreen dialog
放大/缩小（按钮或 Ctrl+滚轮）/ Zoom in/out (buttons or Ctrl+wheel)
左/右旋转 / Rotate left/right
重置到初始状态 / Reset to initial state
下载图片 / Download image
小图片以原始像素尺寸显示 / Small images display at original pixel size
大图片缩小适应容器 / Large images scale down to fit the container
小于视口时居中显示 / Centered display when smaller than viewport
缩放后可滚动查看 / Scrollable when zoomed in
无需配置图标别名 — 所有图标均为内置 SVG path / No icon alias configuration required — all icons are built-in SVG paths
v1.1.0 多图模式，支持左右切换按钮 / Multi-image mode with left/right navigation buttons
v1.1.0 键盘左右方向键导航（← / →）/ Keyboard arrow key navigation
v1.1.0 图片计数器显示（1 / 5）/ Image counter display
v1.1.0 每张图片独立的标题、副标题和下载文件名 / Per-image title, subtitle, and download fileName

本地运行 Demo / Run Demo Locally

git clone <仓库地址 / repo-url>
cd vuetify-image-viewer
npm run demo

然后打开 http://localhost:5173 即可看到单图和多图模式的演示。Then open http://localhost:5173 to see single-image and multi-image mode demos.

更新日志 / Changelog

v1.1.0

新功能 / New Features:

新增 images prop，支持传入图片数组实现多图预览 / Added images prop to support multi-image preview via an image array
新增 currentIndex prop（支持 v-model:current-index），控制当前显示第几张 / Added currentIndex prop (supports v-model:current-index) to control the currently displayed image
新增 ImageItem 类型导出，包含 src / title / subtitle / fileName 四个字段 / Added export of ImageItem type with fields src / title / subtitle / fileName
多图模式下显示左右切换按钮（悬浮在图片区域两侧）/ Left/right navigation buttons visible on both sides of the image in multi-image mode
多图模式下 toolbar 显示图片计数器（如 2 / 5）/ Image counter displayed in toolbar in multi-image mode (e.g. 2 / 5)
支持键盘左右方向键切换图片 / Keyboard left/right arrow key navigation support
切换图片时自动重置缩放、旋转状态 / Auto-reset zoom and rotation when switching images
新增 chevronLeft / chevronRight 图标自定义 / Added chevronLeft / chevronRight icon customization

向后兼容 / Backward Compatibility:

所有 v1.0 的 props 和用法完全不变，无需任何改动即可升级 / All v1.0 props and usage remain unchanged — upgrade with no code changes required

v1.0.0

初始版本：全屏图片预览对话框，支持缩放、旋转、下载、Ctrl+滚轮 / Initial release: fullscreen image preview dialog with zoom, rotate, download, and Ctrl+wheel support

许可证 / License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vuetify-image-viewer

安装 / Installation

对等依赖 / Peer Dependencies

前提条件 / Requirements

用法 / Usage

全局注册 / Global Registration

局部导入 / Local Import

单图模式（向后兼容）/ Single Image Mode (Backward Compatible)

多图模式（v1.1.0 新增）/ Multi Image Mode (v1.1.0+)

ImageItem 类型定义 / Type Definition

Props

图标 / Icons

事件 / Events

功能特性 / Features

本地运行 Demo / Run Demo Locally

更新日志 / Changelog

v1.1.0

v1.0.0

许可证 / License