https://github.com/XiongAmao/vue-easy-lightbox
A tiny lightbox component for Vue.js 3.0 :tada::tada: https://xiongamao.github.io/vue-easy-lightbox/
https://github.com/XiongAmao/vue-easy-lightbox
image images lightbox viewer vue
Last synced: 5 months ago
JSON representation
A tiny lightbox component for Vue.js 3.0 :tada::tada: https://xiongamao.github.io/vue-easy-lightbox/
- Host: GitHub
- URL: https://github.com/XiongAmao/vue-easy-lightbox
- Owner: XiongAmao
- License: mit
- Created: 2018-02-03T03:36:33.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-04-03T11:58:42.000Z (about 1 year ago)
- Last Synced: 2024-05-18T00:41:35.604Z (12 months ago)
- Topics: image, images, lightbox, viewer, vue
- Language: TypeScript
- Homepage:
- Size: 3.14 MB
- Stars: 392
- Watchers: 2
- Forks: 65
- Open Issues: 17
-
Metadata Files:
- Readme: README-CN.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# vue-easy-lightbox
> 基于Vue.js 3.0 与 TypeScript 构建的图片阅览插件， 提供了旋转、放大、拖拽功能。可自定义各种功能。
[](https://www.npmjs.com/package/vue-easy-lightbox)
[](https://www.npmjs.com/package/vue-easy-lightbox)
[](https://www.npmjs.com/package/vue-easy-lightbox)
简体中文 | [English](https://github.com/XiongAmao/vue-easy-lightbox) | [Homepage](https://xiongamao.github.io/vue-easy-lightbox/)
> `[email protected]` 只支持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
const app = Vue.createApp({
// ... 根组件选项
})
app.use(VueEasyLightbox) // 全局变量
app.mount('#app')
```
### 不同构建版本的区别
由于 `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
showImg(index)">
![]()
const { ref } = Vue
const app = Vue.createApp({
setup() {
const visibleRef = ref(false)
const indexRef = ref(0)
const imgs = [
'https://via.placeholder.com/450.png/',
'https://via.placeholder.com/300.png/',
'https://via.placeholder.com/150.png/',
{ src: 'https://via.placeholder.com/450.png/', title: 'this is title' }
]
const showImg = (index) => {
indexRef.value = index
visibleRef.value = true
}
const onHide = () => visibleRef.value = false
return {
visibleRef,
indexRef,
imgs,
showImg,
onHide
}
}
})
// 注册全局组件
app.use(VueEasyLightbox)
app.mount('#app')
```
### 注册VueApp组件
```javascript
import Vue from 'vue'
import VueEasyLightbox from 'vue-easy-lightbox'
const app = Vue.createApp({
// ... 根组件选项
})
app.use(VueEasyLightbox)
app.mount('#app')
```
#### 单文件组件中使用
```html
Show single picture.
Show a group of pictures.
// 如果VueApp已经注册组件，则这里不需要单独引入
import VueEasyLightbox from 'vue-easy-lightbox'
import { ref, defineComponent } from 'vue'
export default defineComponent({
components: {
VueEasyLightbox
},
setup() {
const visibleRef = ref(false)
const indexRef = ref(0) // default 0
const imgsRef = ref([])
// Img Url , string or Array of string
// ImgObj { src: '', title: '', alt: '' }
// 'src' 是必须值
// 允许混合
const onShow = () => {
visibleRef.value = true
}
const showSingle = () => {
imgsRef.value = 'http://via.placeholder.com/350x150'
// or
// imgsRef.value = {
// title: 'this is a placeholder',
// src: 'http://via.placeholder.com/350x150'
// }
onShow()
}
const showMultiple = () => {
imgsRef.value = [
'http://via.placeholder.com/350x150',
'http://via.placeholder.com/350x150'
]
// or
// imgsRef.value = [
// { title: 'test img', src: 'http://via.placeholder.com/350x150' },
// 'http://via.placeholder.com/350x150'
// ]
indexRef.value = 0 // 图片顺序索引
onShow()
}
const onHide = () => (visibleRef.value = false)
return {
visibleRef,
indexRef,
imgsRef,
showSingle,
showMultiple,
onHide
}
}
})
```
### 使用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
show
import { defineComponent } from 'vue'
import VueEasyLightbox, { useEasyLightbox } from 'vue-easy-lightbox'
export default defineComponent({
components: {
VueEasyLightbox
},
setup() {
const {
// methods
show, onHide, changeIndex,
// refs
visibleRef, indexRef, imgsRef
} = useEasyLightbox({
// src / src[]
imgs: [
'http://via.placeholder.com/250x150',
'http://via.placeholder.com/300x150',
'http://via.placeholder.com/350x150'
],
// initial index
initIndex: 0
})
return {
visibleRef,
indexRef,
imgsRef,
show,
onHide
}
}
})
```
#### 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)