vue-previewable-image/README.md

A previewable image Vue component based on viewerjs.

<p align="center">
  <a href="https://www.npmjs.org/package/vue-previewable-image">
    <img src="https://img.shields.io/npm/v/vue-previewable-image.svg">
  </a>
  <a href="https://npmcharts.com/compare/vue-previewable-image?minimal=true">
    <img src="https://img.shields.io/npm/dm/vue-previewable-image.svg">
  </a>
  <br>
</p>

# vue-previewable-image

A **previewable** image Vue component based on <a href="https://github.com/fengyuanchen/viewerjs" target="_blank">viewerjs</a>.

> :warning: TIPS: Current `vue-previewable-image` needs **Vue** verison to `3.2.0+`. For **vue2**, please use [1.x](https://github.com/yisibell/vue-previewable-image/tree/1.x).

- See [example](https://hongwenqing.com/vue-previewable-image/) here.
- [Release Notes](./CHANGELOG.md).

# Features

- :heavy_check_mark: Support preview image via `viewerjs`.
- :heavy_check_mark: Support image lazy load.
- :heavy_check_mark: Support using image viewer as a component via [ImageViewer](./docs/image-viewer-component.md).

# Package

| Version | Support Vue version | Docs |
| :---: | :---: | :---: |
| `^1.7.0+` | `^2.7.14` | See [v1](https://github.com/yisibell/vue-previewable-image/tree/1.x) |
| `^2.1.2+` | `^3.2.0` and above | See [v2](https://github.com/yisibell/vue-previewable-image) |

# Installation

```bash
# pnpm
$ pnpm add vue-previewable-image

# yarn
$ yarn add vue-previewable-image

# npm
$ npm i vue-previewable-image
```

# Usage

> Do not forgot to import the style `vue-previewable-image/dist/style.css`

```vue
<template>
  <main>
    <PreviewableImage
      v-model:current-preview-index="currentIndex"
      :src="src"
      :preview-src-list="srcList"
      :viewer-title="viewerTitle"
      width="100px"
      @switch="handleSwitch"
    />
  </main>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { PreviewableImage } from 'vue-previewable-image'
import type { CustomViewerTitle, ViewerSwitchEvent } from 'vue-previewable-image'

const src =
  'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg'

const srcList = [
  'https://fuss10.elemecdn.com/8/27/f01c15bb73e1ef3793e64e6b7bbccjpeg.jpeg',
  'https://fuss10.elemecdn.com/1/8e/aeffeb4de74e2fde4bd74fc7b4486jpeg.jpeg',
]

const viewerTitle: CustomViewerTitle = (img, { index, total }) => {
  console.log('img:', img)
  return `${img.alt} (${index + 1}/${total})`
}

const handleSwitch: ViewerSwitchEvent = (index, viewer) => {
  console.log('on switch:', index, viewer)
}

const currentIndex = ref(0)
</script>

```

You also can use `viewerjs` from this package, This is equal to `import Viewer from 'viewerjs'`.

```ts
import { Viewer } from 'vue-previewable-image'
```

Or, you can using image viewer as a component, See [ImageViewer](./docs/image-viewer-component.md).


## Using via Vue plugin

```ts
// main.ts

import { createApp } from 'vue'
import App from './App.vue'
import PreviewableImage from 'vue-previewable-image'
import type { PreviewableImageOptions } from 'vue-previewable-image'

const app = createApp(App)

app.use(PreviewableImage, {
  // set global component name
  componentName: 'PreviewableImage',

  // set Viewer default options
  defaultViewerOptions: {
    // ...
  }

} as PreviewableImageOptions).mount('#app')

```

# Attributes

| Prop name | Description | Type | Available value  | Default value |
| :----: | :----: | :----: | :----: | :----: |
| `width` | The **img** container `width` | `string` | - | `undefined` |
| `height` | The **img** container `height` | `string` | - | `undefined` |
| `src` | The `src` of **img** | `string` | - | `undefined` |
| `alt` | The `alt` of **img** | `string` | - | `undefined` |
| `referrerPolicy` | The `referrerPolicy` of **img** | `string` | - | `undefined` |
| `lazy` | Whether to enable image lazy load | `boolean` | - | `true` |
| `zIndex` | Define the CSS `z-index` value of the viewer in modal mode | `number` or `string` | - | `2015` |
| `fit` | The `object-fit` of **img** | `string` | `fill / contain / cover / none / scale-down` | `fill` |
| `previewSrcList` | Define your previewable image list  | `string[]` or `{ src: string; alt: string}[]` | - | `[]` |
| `currentPreviewIndex` | Current preview image shown index, support `v-model`  | `number` | - | `0` |
| `viewerOptions` | Define [viewerjs Options](https://github.com/fengyuanchen/viewerjs) | - | - | `{}` |
| `viewerTitle`| Define viewer title. First argument is `HTMLImageElement` which is generated by `previewSrcList`, second argument is a object `{ index: number; total: number }` which record **current viewer index** and **previewable image count** | `Function` | - | `undefined` |


# Events

| Event name | Description | Callback arguments |
| :---: | :---: | :---: |
| `switch` | Emit when preview image switch. | `(index: number, viewer: Viewer) => void` |
| `load` | Emit when image load success. | `(e: Event) => void` |
| `error` | Emit when image load error. | `(e: Event) => void` |


# Slots

| Name | Description |
| :----: | :----: |
| `placeholder` | Define the placeholder content to display when image is not loaded |
| `error` |  Define the content to display when image load error |