# vue-easy-lightbox > 基于Vue.js 3.0 与 TypeScript 构建的图片阅览插件，提供了旋转、放大、拖拽功能。可自定义各种功能。 [![npm](https://img.shields.io/npm/v/vue-easy-lightbox.svg)](https://www.npmjs.com/package/vue-easy-lightbox) [![npm](https://img.shields.io/npm/l/vue-easy-lightbox.svg)](https://www.npmjs.com/package/vue-easy-lightbox) [![npm](https://img.badgesize.io/https://unpkg.com/vue-easy-lightbox@next/dist/vue-easy-lightbox.esm.min.js?compression=gzip&style=flat-square&label=gzip%20size&color=#4fc08d)](https://www.npmjs.com/package/vue-easy-lightbox) 简体中文 | [English](https://github.com/XiongAmao/vue-easy-lightbox) | [Homepage](https://xiongamao.github.io/vue-easy-lightbox/) > `Vue-easy-lightbox@1.x` 只支持Vue.js 3, 如果你需要使用Vue.js 2版本，请点击[这里](https://github.com/XiongAmao/vue-easy-lightbox/tree/vue2.x)查看. ## 安装 ### 包管理器 ```shell $ npm install --save vue-easy-lightbox@next # OR $ yarn add vue-easy-lightbox@next ``` ### 直接下载在html中直接引入CDN链接文件。 ```html ``` ### 不同构建版本的区别由于 `Vue 3.x` 使用 `ES2015` ([docs faq](https://staging-cn.vuejs.org/about/faq.html#what-browsers-does-vue-support)), 不再需要构建`ES5`版本，`1.6.0`版本开始不再提供`ES5`构建包.

Module	Filename
UMD(for browsers)	vue-easy-lightbox.umd.min.js
CommonJS	vue-easy-lightbox.common.min.js (pkg.main)
ES Module(for bundlers)	vue-easy-lightbox.esm.min.js (pkg.module)

### 单独导入CSS文件 > Added in: `v1.2.3` 默认情况下， CSS被包含在了 `dist/*.min.js`. 在一些特殊情况，你可能需要单独引入CSS文件来避免一些问题 ([CSP Violation](https://github.com/XiongAmao/vue-easy-lightbox/issues/75)). 你可以从`dist/external-css/`导入不包含CSS的构建文件和单独的样式文件. ```js // in this path vue-easy-lightbox/dist/external-css/*.js import VueEasyLightbox from 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js' // or import VueEasyLightbox from 'vue-easy-lightbox/external-css' // it defines in `package.json` `exports` // 单独引入组件样式 import 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.css' // or import 'vue-easy-lightbox/external-css/vue-easy-lightbox.css' ``` #### TypeScript Checking error: 如果你使用TypeScript，并遇到了以下报错： > `Could not find the declaration file for module 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'` 这里有两种办法解决这个问题方法 1: 项目本地添加 `d.ts`，补充模块信息: ```ts declare module 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js' { import VueEasyLightbox from 'vue-easy-lightbox' export * from 'vue-easy-lightbox' export default VueEasyLightbox } ``` 方法 2: 如果你使用的是Webpack工程，参考以下方法: [webpack alias docs](https://webpack.js.org/configuration/resolve/#resolvealias) ```js // wepback.config.js module.exports = { //... resolve: { alias: { 'vue-easy-lightbox$': 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js', }, }, }; // in your component import VueEasyLightbox from 'vue-easy-lightbox' // work ``` or vitejs: [vitejs alias](https://cn.vitejs.dev/config/shared-options.html#resolve-alias) ```js // vite.config.js import { defineConfig } from 'vite' export default defineConfig({ resolve: { alias: { 'vue-easy-lightbox': 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js' } } }) ``` ## 使用方式 ### HTML中使用 `UMD` 包导入 ```html

``` ### 注册VueApp组件 ```javascript import Vue from 'vue' import VueEasyLightbox from 'vue-easy-lightbox' const app = Vue.createApp({ // ... 根组件选项 }) app.use(VueEasyLightbox) app.mount('#app') ``` #### 单文件组件中使用 ```html ``` ### 使用slot定制你的按钮或者工具栏 ```html ``` 参考：[插槽 - Vue.js](https://staging-cn.vuejs.org/guide/components/slots.html) ### 组合式函数 Composables > Added in `v1.7.0` `useEasyLightbox` 提供了一些简单的方法和state，方便你使用`setup()`。这个composable是可选的。你可以自定义自己的状态和方法。 Usage: ```html ``` #### Type declaration ```ts export interface Img { src?: string title?: string alt?: string } export interface UseEasyLightboxOptions { /** * image src/Img or list of images src/Img * @default '' */ imgs: Img | string | (Img | string)[]; /** * initial index of imgList * @default 0 */ initIndex?: number; } export declare const useEasyLightbox: (options: UseEasyLightboxOptions) => { imgsRef: Ref; indexRef: Ref; visibleRef: Ref; show: (index?: Ref | number | Event) => void; onHide: () => void; changeIndex: (index?: number) => void; }; ``` ## 配置项 Props

属性	类型	默认值	说明
visible	Boolean	required	控制组件的显示
imgs	String/String[]/ImgObject:{ src: string, title?: string, alt?: string }/ImgObject[]	required	图片的src字符串或图片对象(地址和标题) { src, title?, alt? }，传入数组则可以轮播显示
index	Number	0	打开图片组时，展示索引位置的图片
loop	Boolean	false	允许循环切换图片
scrollDisabled (scroll-disabled)	Boolean	true	传true时，禁用背景滚动
escDisabled (esc-disabled)	Boolean	false	默认情况下，展示时按下esc键关闭Modal
moveDisabled (move-disabled)	Boolean	false	传true时，禁用拖动图片功能，并启用swipe功能
rotateDisabled (rotate-disabled)	Boolean	false	传true时，禁用图片旋转功能
zoomDisabled (zoom-disabled)	Boolean	false	传true时，禁用图片缩放功能
pinchDisabled (pinch-disabled)	Boolean	false	传true时，禁用双指触摸缩放功能
maskClosable (mask-closable)	Boolean	true	控制点击蒙板关闭预览.
teleport	string \| Element	-	指定挂载的节点
swipeTolerance (swipe-tolerance)	Number	50	指定swipe距离，单位为px
zoomScale	Number	0.12	指定缩放步进的比例
maxZoom	Number	3	指定图片最大缩放比例
minZoom	Number	0.1	指定图片最小缩放比例.
rtl	Boolean	false	指定RTL布局

Event

事件名	说明	返回值
hide	当点击遮罩或者关闭按钮时，会触发该事件	-
on-error	图片加载错误，触发error事件	event (event.target 不是实际展示的图片)
on-prev / on-prev-click	切换上一张图片时触发	(oldIndex, newIndex)
on-next / on-next-click	切换下一张图片时触发	(oldIndex, newIndex)
on-index-change	当图片索引被改变时触发，比如点击或更改传给组件index	(oldIndex, newIndex)
on-rotate	当图片旋转时触发事件	deg: number (顺时针角度)

Slot & Scoped Slot

名称	slot props	slot props 类型	说明
prev-btn	prev	Function	当点击时显示上一页
next-btn	next	Function	当点击时显示下一页
close-btn	close	Function	当点击时关闭弹窗
toolbar	toolbarMethods: { zoomIn, zoomOut, rotate(rotateLeft), rotateLeft, rotateRight }	{ Function }	放大、缩小、逆时针/顺时针旋转
loading	-	-	加载图标
onerror	-	-	图片加载错误占位图

## License [MIT](http://opensource.org/licenses/MIT)