pic-viewer
Version:
Picture viewer.
245 lines (185 loc) • 6.51 kB
Markdown
<h1 align="center">Pic Viewer</h1>
<p align="center">
图片画廊。
</p>
<p align="center">
<a href="https://bundlephobia.com/package/pic-viewer"><img alt="minzipped size" src="https://img.shields.io/bundlephobia/minzip/pic-viewer"></a>
<a href="https://rome.tools"><img alt="code style" src="https://img.shields.io/badge/code_style-Rome-FFC905.svg?logo=rome"></a>
<a href="https://conventionalcommits.org"><img alt="conventional commits" src="https://img.shields.io/badge/commits-Conventional-FE5196.svg?logo=conventionalcommits&logoColor=white"></a>
</p>
<br>
## 特性
- [Viewer.js](https://github.com/fengyuanchen/viewerjs) + [Swiper](https://swiperjs.com) + [node-qrcode](https://github.com/soldair/node-qrcode) 组合拳
- 多样的展示形式：文档流/瀑布流/轮播图/表格嵌套
- 灵活的数据类型：URL/Base64/二维码/[object URL](https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications#example_using_object_urls_to_display_images)
- 任意绑定值类型
<br>
## 安装
### 外置依赖
- vue@2
### 局部注册
```shell
npm i pic-viewer
```
```vue
<template>
<PicViewer v-bind="{/* 局部配置 */}" />
</template>
<script>
import PicViewer from 'pic-viewer'
export default {
components: { PicViewer },
}
</script>
```
### 全局注册
```shell
npm i pic-viewer
```
```ts
import PicViewer from 'pic-viewer'
Vue.use(PicViewer, {
// 全局配置
})
```
### CDN + ESM
```html
<html lang="en">
<head>
<meta charset="UTF-8" />
</head>
<body>
<div id="app">
<pic-viewer
value="xxx"
qrcode
></pic-viewer>
</div>
<script type="importmap">
{
"imports": {
"vue": "https://unpkg.com/vue@2/dist/vue.esm.browser.min.js",
"pic-viewer": "https://unpkg.com/pic-viewer@0.10/dist/pic-viewer.mjs"
}
}
</script>
<script type="module">
import Vue from 'vue'
import PicViewer from 'pic-viewer'
new Vue({
components: { PicViewer },
}).$mount('#app')
</script>
</body>
</html>
```
### CDN + IIFE
```html
<html lang="en">
<head>
<meta charset="UTF-8" />
</head>
<body>
<div id="app">
<pic-viewer
value="xxx"
qrcode
></pic-viewer>
</div>
<script src="https://unpkg.com/vue@2"></script>
<script src="https://unpkg.com/pic-viewer@0.10"></script>
<script>
new Vue({
components: { PicViewer },
}).$mount('#app')
</script>
</body>
</html>
```
<br>
## 属性
| 名称 | 说明 | 类型 | 默认值 |
| ------------- | ------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
| value | 绑定值 | any | |
| pattern | 展示模式（`'waterfall'`, `'swiper'` 或 `'table-cell'`） | string | `undefined`（即文档流） |
| srcAt | 图片 `src` 的位置 | string / symbol / (value: any) => any | |
| viewerjs | 是否启用 Viewer.js | boolean | `true` |
| viewerjsProps | Viewer.js 的参数 | object | `{ zIndex: 5000, zoomRatio: 0.4 }` |
| swiperProps | Swiper 的参数 | object | `{ observer: true }` |
| qrcode | 是否将 `value` 转换为二维码 | boolean / `'auto'` | `false` |
| qrcodeProps | node-qrcode 的参数 | object | `{ margin: 0, errorCorrectionLevel: 'L', width: 444, height: 444 }` |
### qrcode
如果将 `qrcode` 设为 `'auto'`，PicViewer 会自动判断是否需要转换 (`value` 为 Base64 或 URL 时不会转换)。
### srcAt
用于定位 `value` 中的图片 `src`，适用于绑定值非 `src` 本身的情况。
- 支持属性名，如 `'url'`
- 支持属性路径，如 `'data[0].url'`
- 支持 symbol 类型的属性名
- 支持 Function，如 `({ url }) => url`
<br>
## 事件
| 名称 | 说明 | 回调参数 |
| ----- | -------------- | ---------------------------- |
| click | 点击图片后触发 | (src: string, index: number) |
<br>
## 插槽
| 名称 | 说明 |
| -------- | ----------------- |
| 默认插槽 | 自定义 `img` 标签 |
```html
<PicViewer>
<template #default="{ src, index }">
<img :src="src">
<div>第{{ index + 1 }}张</div>
</template>
</PicViewer>
```
<br/>
## 获取 Viewer.js 实例
`picViewerRef.value.viewer.view()`
<br>
## 获取 Swiper 实例
```vue
<template>
<PicViewer
ref="picViewerRef"
pattern="swiper"
:swiperProps="{
on: {
init: () => {
$nextTick(() => {
console.log(picViewerRef.swiper)
})
},
},
}"
/>
</template>
<script setup>
import PicViewer from 'pic-viewer'
const picViewerRef = ref()
</script>
```
<br>
## 二维码清晰度
默认的图片 CSS 高度为 148px (与 `el-upload` 保持一致)，默认的二维码分辨率为 444 × 444 (三倍图)，如果你增大了图片的 CSS 尺寸，将导致图片变模糊。
解决方式：将二维码分辨率设置为展示尺寸的三倍。
```vue
<template>
<PicViewer
:qrcodeProps="{
width: 900,
height: 900,
}"
/>
</template>
<style scoped>
:deep(.pic-viewer) img {
width: 300px;
height: 300px;
}
</style>
```
<br>