# 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 import VueEasyLightbox from 'vue-easy-lightbox/external-css' // or import VueEasyLightbox from 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js' // 单独引入组件样式 import 'vue-easy-lightbox/external-css/vue-easy-lightbox.css' // or import 'vue-easy-lightbox/dist/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 控制点击蒙板关闭预览.
dblclickDisabled (dblclick-closable) Boolean false 控制双击缩放功能.
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)