Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mirari/vue3-viewer

Image viewer component for vue 3.x, supports rotation, scale, zoom and so on, based on viewer.js
https://github.com/mirari/vue3-viewer

Last synced: 3 months ago
JSON representation

Image viewer component for vue 3.x, supports rotation, scale, zoom and so on, based on viewer.js

Awesome Lists containing this project

README

        

# v-viewer

Image viewer component for vue, supports rotation, scale, zoom and so on, based on [viewer.js](https://github.com/fengyuanchen/viewerjs)

[![npm version](https://img.shields.io/npm/v/v-viewer.svg)](https://www.npmjs.com/package/v-viewer)
[![language](https://img.shields.io/badge/language-Vue3-brightgreen.svg)](https://www.npmjs.com/package/v-viewer)

[![npm version](https://img.shields.io/npm/v/v-viewer/legacy.svg)](https://www.npmjs.com/package/v-viewer)
[![language](https://img.shields.io/badge/language-Vue2-brightgreen.svg)](https://www.npmjs.com/package/v-viewer)

[![npm download](https://img.shields.io/npm/dw/v-viewer.svg)](https://www.npmjs.com/package/v-viewer)
[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://mit-license.org/)

## [v-viewer for vue2](https://github.com/mirari/v-viewer/tree/v2)

## [Live demo](https://mirari.github.io/vue3-viewer/)

## Quick Example

- [directive](https://codepen.io/mirari/pen/yLMPPWy)
- [component](https://codepen.io/mirari/pen/ZEeaaWZ)
- [api](https://codepen.io/mirari/pen/qBrVpNV)
- [thumbnail & source](https://codepen.io/mirari/pen/Vwpryax)
- [viewer callback](https://codepen.io/mirari/pen/eYveypz)
- [custom toolbar](https://codepen.io/mirari/pen/ZEXqyPq)
- [filter images](https://codepen.io/mirari/pen/mdWqpwa)
- [change images](https://codepen.io/mirari/pen/ExWbovw)

## [中文文档](https://mirari.cc/posts/vue3-viewer)

## Installation

Install from NPM

```bash
npm install v-viewer viewerjs
```

## Usage

To use `v-viewer`, simply import it and the `css` file, and call `app.use()` to install.

The component, directive and api will be installed together in the global.

Two different API styles are both supported: **Options API** and **Composition API**.

```ts
import { createApp } from 'vue'
import App from './App.vue'
import 'viewerjs/dist/viewer.css'
import VueViewer from 'v-viewer'
const app = createApp(App)
app.use(VueViewer)
app.mount('#app')
```

```vue











Click to show

import { defineComponent } from 'vue'
export default defineComponent({
data() {
return {
images: [
"https://picsum.photos/200/200",
"https://picsum.photos/300/200",
"https://picsum.photos/250/200"
]
}
},
methods: {
show() {
this.$viewerApi({
images: this.images
})
}
}
})

```

### Support UMD

#### Browser

```html

app.use(VueViewer.default)

```

#### CommonJS

```javascript
var VueViewer = require('VueViewer')
```

#### AMD

```javascript
require(['VueViewer'], function (VueViewer) {});
```

### Usage of directive

Just add the directive `v-viewer` to any element, then all `img` elements in it will be handled by `viewer`.

You can set the options like this: `v-viewer="{inline: true}"`

Get the element by selector and then use `el.$viewer` to get the `viewer` instance if you need.

```vue





Show

import { defineComponent } from 'vue'
import 'viewerjs/dist/viewer.css'
import { directive as viewer } from "v-viewer"
export default defineComponent({
directives: {
viewer: viewer({
debug: true
})
},
data() {
return {
images: [
"https://picsum.photos/200/200",
"https://picsum.photos/300/200",
"https://picsum.photos/250/200"
]
}
},
methods: {
show () {
const viewer = this.$el.querySelector('.images').$viewer
viewer.show()
}
}
})

```

#### Directive modifiers

##### static

The `viewer` instance will be created only once after the directive binded.

If you're sure the images inside this element won't change again, use it to avoid unnecessary re-render.

```vue




```

##### rebuild

The `viewer` instance will be updated by `update` method when the source images changed (added, removed or sorted) by default.

If you encounter any display problems, try rebuilding instead of updating.

```vue




```

### Usage of component

You can simply import the component and register it locally too.

```vue





{{scope.options}}


Show

import { defineComponent } from 'vue'
import 'viewerjs/dist/viewer.css'
import { component as Viewer } from "v-viewer"
export default defineComponent({
components: {
Viewer,
},
data() {
return {
images: [
"https://picsum.photos/200/200",
"https://picsum.photos/300/200",
"https://picsum.photos/250/200"
]
}
},
methods: {
inited (viewer) {
this.$viewer = viewer
},
show () {
this.$viewer.show()
}
}
})

```

#### Component props

##### images

- Type: `Array`

##### trigger

- Type: `Object`

You can replace `images` with `trigger`, to accept any type of prop.
when the `trigger` changes, the component will re-render the viewer.

```vue

```

##### rebuild

- Type: `Boolean`
- Default: `false`

The viewer instance will be updated by `update` method when the source images changed (added, removed or sorted) by default.

If you encounter any display problems, try rebuilding instead of updating.

```vue



{{scope.options}}

```

#### Component events

##### inited

- viewer: `Viewer`

Listen for the `inited` event to get the `viewer` instance, or use `this.refs.xxx.$viewer`.

### Usage of api

> Only available in modal mode.

You can call the function: `this.$viewerApi({options: {}, images: []})` to show gallery without rendering the `img` elements yourself.

The function returns the current viewer instance.

```vue


URL Array
Img-Object Array

import { defineComponent } from 'vue'
import 'viewerjs/dist/viewer.css'
import { api as viewerApi } from "v-viewer"
export default defineComponent({
data() {
return {
sourceImageURLs: [
'https://picsum.photos/200/200?random=1',
'https://picsum.photos/200/200?random=2'
],
sourceImageObjects: [
{
'src': 'https://picsum.photos/200/200?random=3',
'data-source': 'https://picsum.photos/800/800?random=3'
},
{
'src': 'https://picsum.photos/200/200?random=4',
'data-source': 'https://picsum.photos/800/800?random=4'
}
]
}
},
methods: {
previewURL () {
// If you use the `app.use` full installation, you can use `this.$viewerApi` directly like this
const $viewer = this.$viewerApi({
images: this.sourceImageURLs
})
},
previewImgObject () {
// Or you can just import the api method and call it.
const $viewer = viewerApi({
options: {
toolbar: true,
url: 'data-source',
initialViewIndex: 1
},
images: this.sourceImageObjects
})
}
}
})

```

## Options & Methods of Viewer

Refer to [viewer.js](https://github.com/fengyuanchen/viewerjs).

## Plugin options

### name

- Type: `String`
- Default: `viewer`

If you need to avoid name conflict, you can import it like this:
```ts
import { createApp } from 'vue'
import 'viewerjs/dist/viewer.css'
import VueViewer from 'v-viewer'
import App from './App.vue'

export const app = createApp(App)
app.use(VueViewer, {
name: 'vuer',
debug: true,
})
app.mount('#app')

```

```vue






Show




import { defineComponent } from 'vue'
export default defineComponent({
data() {
return {
images: [
"https://picsum.photos/200/200",
"https://picsum.photos/300/200",
"https://picsum.photos/250/200"
]
};
},
methods: {
show () {
// viewerjs instance name
const vuer = this.$el.querySelector('.images').$vuer
vuer.show()
// api name
this.$vuerApi({
images: this.images
})
}
}
})

import { api as vuerApi } from 'v-viewer'
const images = [
"https://picsum.photos/200/200",
"https://picsum.photos/300/200",
"https://picsum.photos/250/200"
]
const show = () => {
// viewerjs instance name
const vuer = document.querySelector('.images').$vuer
vuer.show()
// api name
vuerApi({
images
})
}

```

### defaultOptions

- Type: `Object`
- Default: `undefined`

If you need to set the viewer default options, you can import it like this:

```ts
import { createApp } from 'vue'
import 'viewerjs/dist/viewer.css'
import VueViewer from 'v-viewer'
import App from './App.vue'

export const app = createApp(App)
app.use(VueViewer, {
defaultOptions: {
zIndex: 9999
}
})
app.mount('#app')
```

And you can reset the default options at any other time:

```javascript
import VueViewer from 'v-viewer'

VueViewer.setDefaults({
zIndexInline: 2021,
})
```