vue-easy-lightbox

Um componente lightbox de visualização de imagens escrito com Vue.js 3 e Typescript, fornecendo funções de rotação, slide de imagens, zoom e redução.

vue-easy-lightbox@1.x suporta apenas ao Vue.js 3, se você precisar da versão em Vue.js 2, verifique aquiopen in new window.

Instalação

Usando com npm ou yarn

$ npm install --save vue-easy-lightbox@next

$ yarn add vue-easy-lightbox@next

Importando direto no navegador

Adicione a tag script em seu navegador e use a variável global VueEasyLightbox.

<script src="https://unpkg.com/vue@next"></script>
<script src="https://unpkg.com/vue-easy-lightbox@next/dist/vue-easy-lightbox.umd.min.js"></script>
<script>
  const app = Vue.createApp({
    // ... Opções de componentes de raiz
  })
  app.use(VueEasyLightbox) // variável global
  app.mount('#app')
</script>

Diferentes compilações

Como o Vue 3.x utiliza ES2015, não há necessidade de construir o pacote ES5, e o ES5 build é removido da versão 1.6.0.

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)

External CSS Build

Added in: v1.2.3

By default, CSS is included in dist/*.min.js. In some special cases you may want to import CSS individually to avoid some problems (CSP Violationopen in new window). You can import builds without CSS and individual .css file from dist/external-css/.

import VueEasyLightbox from 'vue-easy-lightbox/external-css'
// or
import VueEasyLightbox from 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'

// you need to import css file
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:

If your project is TypeScript project and you get this error message:

Could not find the declaration file for module 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'

Here are two ways to solve it.

Way 1: add d.ts locally:

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
}

Way 2:

If you're using webpack: webpack alias docsopen in new window

// 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 aliasopen in new window

// 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'
    }
  }
})

Uso

Using `UMD` in browser

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <script src="https://unpkg.com/vue@next"></script>
    <script src="https://unpkg.com/vue-easy-lightbox@next/dist/vue-easy-lightbox.umd.min.js"></script>
  </head>
  <body>
    <div id="app">
      <div class="">
        <div v-for="(src, index) in imgs" :key="index" class="pic" @click="() => showImg(index)">
          <img :src="src" />
        </div>
      </div>
      <vue-easy-lightbox :visible="visibleRef" :imgs="imgs" :index="indexRef" @hide="onHide"></vue-easy-lightbox>
    </div>
    <script>
      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
          }
        }
      })
      // Registering VueEasyLightbox for your VueApp.
      app.use(VueEasyLightbox)
      app.mount('#app')
    </script>
  </body>
</html>

Componente de arquivo único `.vue`

1. Registrando componente VueApp

O Vue.js 3 não fornece mais uma instância compartilhada global do Vue, registre o componente vue-easy-lightbox para cada VueApp que você usar. Documentação sobre isso aquiopen in new window

import Vue from 'vue'
import VueEasyLightbox from 'vue-easy-lightbox'

const app = Vue.createApp({
  // ... root component options
})
app.use(VueEasyLightbox)
app.mount('#app')

2. Uso do componente

<template>
  <div>
    <button @click="showSingle">Show single picture.</button>
    <button @click="showMultiple">Show a group of pictures.</button>

    <vue-easy-lightbox
      :visible="visibleRef"
      :imgs="imgsRef"
      :index="indexRef"
      @hide="onHide"
    ></vue-easy-lightbox>
  </div>
</template>

<script>
// If VueApp is already registered with VueEasyLightbox, there is no need to register it here.
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' is required
    // allow mixing

    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 // index of imgList
      onShow()
    }
    const onHide = () => (visibleRef.value = false)

    return {
      visibleRef,
      indexRef,
      imgsRef,
      showSingle,
      showMultiple,
      onHide
    }
  }
})
</script>

Botões personalizados ou barra de ferramentas

<vue-easy-lightbox ...>
  <template v-slot:prev-btn="{ prev }">
    <button @click="prev">Mostrar o anterior</button>
  </template>

  <template v-slot:next-btn="{ next }">
    <button @click="next">Mostrar o próximo</button>
  </template>

  <template v-slot:close-btn="{ close }">
    <button @click="close">Fechar lightbox</button>
  </template>

  <template v-slot:toolbar="{ toolbarMethods }">
    <button @click="toolbarMethods.zoomIn">Mais zoom</button>
    <button @click="toolbarMethods.zoomOut">Menos zoom</button>
    <button @click="toolbarMethods.rotateLeft">Rotação no anti-horário</button>
    <button @click="toolbarMethods.rotateRight">Rotação no sentido horário</button>
  </template>
</vue-easy-lightbox>

Referência: Slots-Vue.jsopen in new window

Composables

Added in v1.7.0

O useEasyLightbox fornece alguns métodos e estados simples para ajudá-lo a utilizar o setup(). Isto é opcional. Você pode personalizar seu estado.

Usage:

<template>
  <div>
    <button @click="show">show</button>
    <vue-easy-lightbox
      :visible="visibleRef"
      :imgs="imgsRef"
      :index="indexRef"
      @hide="onHide"
    />
  </div>
</template>

<script>
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
    }
  }
})
</script>

Type declaration

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<Img | string | (Img | string)[]>;
  indexRef: Ref<number | undefined>;
  visibleRef: Ref<boolean>;
  show: (index?: Ref<number> | number | Event) => void;
  onHide: () => void;
  changeIndex: (index?: number) => void;
};

Opções

Props

Nome	Tipo	Padrão	Descrição
visible	Boolean	requerido	Controlar a exibição do lightbox
imgs	String/String[]/ImgObject:{ src: string, title?: string, alt?: string }/ImgObject[]	requerido	Src das imagens / array do src / ImgObject:{ src, title?, alt? } / array do ImgObject / array do ImgObject.
index	Number	0	Index do imgList
loop	Boolean	false	Passe verdadeiro para permitir o modo de loop contínuo.
scrollDisabled (scroll-disabled)	Boolean	true	Passe verdadeiro para desactivar a rolagem quando o modal é visível.
escDisabled (esc-disabled)	Boolean	false	Por padrão, pressione a tecla `esc` para fechar o Modal durante a apresentação.
moveDisabled (move-disabled)	Boolean	false	Passe verdadeiro para desativar o movimento da imagem e permitir `swipe`.
rotateDisabled (rotate-disabled)	Boolean	false	Passe verdadeiro para desativar a rotação da imagem.
zoomDisabled (zoom-disabled)	Boolean	false	Passe verdadeiro para desativar o zoom da imagem.
pinchDisabled (pinch-disabled)	Boolean	false	Pass true to disable pinching.
maskClosable (mask-closable)	Boolean	true	Habilite ou desabilite a máscara de clique para fechar a `vue-easy-lightbox`.
dblclickDisabled (dblclick-closable)	Boolean	false	Enable or disable double-click on img to zoom in/out.
teleport	string \| Element	-	Especificar o nó de montagem para `vue-easy-lightbox'.
swipeTolerance (swipe-tolerance)	Number	50	Especifique o número de píxeis que tem de `swipe`.
zoomScale	Number	0.12	Specify the step between zoom levels.
maxZoom	Number	3	Specify the maximum level of zoom scale.
minZoom	Number	0.1	Specify the minimum level of zoom scale.
rtl	Boolean	false	suporta os idiomas RTL (da direita para a esquerda)

Referência: Teleportopen in new window

Event

Nome	Descrição	Valor de retorno
hide	Quando você clica no overlay do modal ou no botão fechar, o componente irá emitir este evento	-
on-error	Erro de carregamento de imagem	event (event.target não é a imagem a ser exibida)
on-prev / on-prev-click	Emite quando o botão anterior for clicado	(oldIndex, newIndex)
on-next / on-next-click	Emite quando o próximo botão for clicado ou quando o utilizador deslizar para a esquerda	(oldIndex, newIndex)
on-index-change	Emite quando o index de imgs é alterado ou quando o utilizador desliza para a direita	(oldIndex, newIndex)
on-rotate	Emit when image rotate	deg: number (clockwise angle deg)

Slot

Nome do Slot	Slot Props	Tipo do Slot Props	Descrição
prev-btn	prev	Function	Mostrar a imagem anterior
next-btn	next	Function	Mostrar a próxima imagem
close-btn	close	Function	Fechar modal
toolbar	toolbarMethods: { zoomIn, zoomOut, rotate(rotateLeft), rotateLeft, rotateRight }	{ Function }	ZoomIn, zoomOut, rotate(rotateLeft), rotateLeft, rotateRight
loading	-	-	Ícone de carregamento
onerror	-	-	Error Placeholder

# vue-easy-lightbox

# Instalação

# Usando com npm ou yarn

# Importando direto no navegador

# Diferentes compilações

# External CSS Build

# TypeScript Checking error:

# Uso

# Using UMD in browser

# Componente de arquivo único .vue

# 1. Registrando componente VueApp

# 2. Uso do componente

# Botões personalizados ou barra de ferramentas

# Composables

# Type declaration

# Opções

# Props

# Event

# Slot