Installations
npm install imgpondDeveloper Guide
BETA
Typescript
No
Module System
CommonJS, ESM
Node Version
20.10.0
NPM Version
10.2.3
Score
46.1
Supply Chain
85.7
Quality
80.6
Maintenance
50
Vulnerability
97.6
License
Releases
Unable to fetch releases
Contributors
6
Love this project? Help keep it running — sponsor us today! 🚀
Download Statistics
Total Downloads
16,345
Last Day
2
Last Week
11
Last Month
171
Last Year
1,471
Bundle Size
316.02 kB
Minified
94.44 kB
Minified + Gzipped
Maintainers
6
Package Meta Information
Latest Version
0.14.4
Package Id
imgpond@0.14.4
Unpacked Size
3.94 MB
Size
0.97 MB
File Count
7
NPM Version
10.2.3
Node Version
20.10.0
Published on
Nov 25, 2023
Total Downloads
Cumulative downloads
Total Downloads
16,345
Last Day
100%
2
Compared to previous day
Last Week
450%
11
Compared to previous week
Last Month
510.7%
171
Compared to previous month
Last Year
-65.5%
1,471
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
3
Dev Dependencies
47
@antfu/eslint-config@commitlint/cli@commitlint/config-conventional@types/lodash-es@types/node@types/validator@vitejs/plugin-vue2@vueuse/coreawait-to-jsaxiosaxios-shortcutcase-policecropperjscross-spawndelelement-uieslintesnoimgpondjson-editor-vuekikimorekoloristlint-stagedlodash-esonly-allowopenpic-viewerpromptssasssemversimple-git-hookssortablejssweetalert2sweetalert2-presettypescriptunocssunplugin-auto-importunplugin-vue-componentsupng-jsvalidatorvanilla-jsoneditorvitevite-plugin-css-injected-by-jsvite-plugin-dtsvuevue-global-configzhlint
ImgPond 
图片上传一站式解决方案。
⚠ DEPRECATED
Warning
ImgPond 已推出 Element Plus (Vue 3) & Element UI (Vue 2.7/2.6) 一体通用版本
特性
- 数据双向绑定
v-model，支持任意绑定值类型 - 数据源
- 用户选择本地文件 (File)
- 编程式提供数据源 (File/Blob/Base64/URL/object URL)
- 编辑图片
- 格式转换
- 尺寸指定
- 品质调节
- 自由裁剪 & 锁定比例裁剪
- 翻转、缩放、无级角度旋转
- 限制图片
- 格式筛选
- 尺寸或尺寸范围 (间接限制宽高比例)
- 大小上限、下限
- 数量上限、下限
- 自定义校验
- 多选
- 拖拉拽排序
- 预览图片 (pic-viewer 提供技术支持)
- 局部注册并传参，或全局注册并传参 (vue-global-config 提供技术支持)
安装
1npm i imgpond
外置依赖
- vue@2
- element-ui
- pic-viewer
局部注册
1<script> 2import Vue from 'vue' 3import PicViewer from 'pic-viewer' 4import ImgPond from 'imgpond' 5 6Vue.use(PicViewer, { 7 // 全局配置 8}) 9 10export default { 11 components: { ImgPond }, 12} 13</script> 14 15<template> 16 <ImgPond 17 v-model="value" 18 v-bind="{/* 局部配置 */}" 19 /> 20</template>
全局注册
1import PicViewer from 'pic-viewer' 2import ImgPond from 'imgpond' 3 4Vue.use(PicViewer, { 5 // 全局配置 6}) 7Vue.use(ImgPond, { 8 // 全局配置 9})
CDN + ESM
⚠ 暂不支持 (ElementUI 未提供 ESM 导出)
CDN + IIFE
1<!DOCTYPE html> 2<html lang="en"> 3 4<head> 5 <meta charset="UTF-8" /> 6 <link 7 rel="stylesheet" 8 href="https://cdn.jsdelivr.net/npm/element-ui/lib/theme-chalk/index.css" 9 > 10</head> 11 12<body> 13 <div id="app"> 14 <img-pond v-model="value"></img-pond> 15 </div> 16 <script src="https://cdn.jsdelivr.net/npm/vue@2"></script> 17 <script src="https://cdn.jsdelivr.net/npm/element-ui/lib/index.js"></script> 18 <script src="https://cdn.jsdelivr.net/npm/pic-viewer@0.11"></script> 19 <script src="https://cdn.jsdelivr.net/npm/imgpond@0.14"></script> 20 <script> 21 Vue.use(PicViewer) 22 Vue.use(ImgPond) 23 24 new Vue({ 25 data() { 26 return { 27 value: undefined, 28 } 29 }, 30 }).$mount('#app') 31 </script> 32</body> 33 34</html>
属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value / v-model | 绑定值 | any | |
| arrayed | 绑定值是否为数组类型，默认自动 | boolean | |
| srcAt | 图片链接的位置 | string / symbol / (value: any) => any | |
| upload | 调用接口上传图片，返回图片链接 | (output: File | Blob) => Promise<string | object> | string | object | void | |
| count | 数量限制 | number / [number?, number?] | |
| size | 大小限制 (MB) | number / [number?, number?] | |
| accept | 图片格式筛选 | string | 'image/*' |
| outputType | 图片输出格式 (编辑后)，默认原格式 | string | |
| validator | 自定义数据源校验器 | (source: File | Blob | string) => boolean | |
| disabled | 禁用状态 | boolean | false |
| editable | 是否开启编辑功能 | boolean | true |
| width | 宽度或宽度范围 (像素) | number / [number?, number?] | |
| height | 高度或高度范围 (像素) | number / [number?, number?] | |
| aspectRatioTolerance | 锁定裁剪比例的公差 | number | 0 |
arrayed
如果数量上限和图片数量均不超过 1，则处于单选状态，否则为多选
默认情况下，在单选时输出的绑定值形如：item，多选时输出的绑定值形如：[item，item]
item 具体是什么格式？
未配置 srcAt 时，会提取图片链接作为 item，配置了则不会
如果将 arrayed 设置为 true 则强制输出数组类型，无论单选还是多选
如果将 arrayed 设置为 false 则强制输出非数组类型，如果此时图片数量为多个，则会执行 JSON.stringify
srcAt
用于定位 value 和 upload 返回值中的图片链接，适用于绑定值非图片链接本身的情况
- 支持属性名，如
'url' - 支持属性路径，如
'data[0].url' - 支持 symbol 类型的属性名
- 支持 Function，如
value => value.url
upload
开启编辑功能时，会在编辑完成后调用，未开启编辑功能时，会在选择图片后调用
未配置或函数返回值为空时，绑定值将输出二进制文件
参数为编辑产物：
用户选择本地文件、编程式提供 File 类型的数据源时，编辑产物的类型为 File
编程式提供非 File 类型的数据源且编辑了图片时，编辑产物的类型为 Blob
未开启编辑功能或未编辑时，编辑产物即输入值
编程式提供 string 类型的数据源且未编辑时，不需要上传，该方法不会被调用
返回值类型为 Promise<object> 或 object 时需要配置 srcAt
count
10：限制数量上限为 10 张[1]：限制数量下限为 1 张[, 10]：限制数量上限为 10 张[1, 10]：限制数量下限为 1 张，且上限为 10 张
size
10：限制大小上限为 10 MB[1]：限制大小下限为 1 MB[, 10]：限制大小上限为 10 MB[1, 10]：限制大小下限为 1 MB，且上限为 10 MB
width
100：限制宽度为 100 像素[100]：限制宽度下限为 100 像素[, 200]：限制宽度上限为 200 像素[100, 200]：限制宽度下限 100 像素，且上限为 200 像素
height
100：限制高度为 100 像素[100]：限制高度下限为 100 像素[, 200]：限制高度上限为 200 像素[100, 200]：限制高度下限 100 像素，且上限为 200 像素
accept
通过文件对话框选择图片时，优先展示指定类型的文件，同原生 input 的 accept
⚠ 用户仍可以选择其它类型，文件类型校验应使用 validator
可选值：
- 文件扩展名，不区分大小写，如
'.jpg.jpeg.png' - MIME type，如
'image/jpeg,image/png'
outputType
开启编辑模式时，可以指定输出的图片格式，可选值参考 MIME type
插槽
同 el-upload
事件
| 名称 | 说明 | 回调参数 |
|---|---|---|
| size-error | 未开启编辑模式，且图片大小不符合要求时触发 | 图片体积 (Byte) |
| width-error | 未开启编辑模式，且图片宽度不符合要求时触发 | 图片宽度 (像素) |
| height-error | 未开启编辑模式，且图片高度不符合要求时触发 | 图片高度 (像素) |
| ... | el-upload 的事件 (Function 类型的属性，去掉 on 前缀) |
1<ImgPond 2 @remove="onRemove" 3 @beforeUpload="onBeforeUpload" 4/>
方法
| 名称 | 说明 | 参数 |
|---|---|---|
| openEditor | 打开图片编辑对话框 | (source: File | Blob | string | File[] | Blob[] | string[]) => void |
参数为输入的数据源，支持的数据类型有：
- File
- Blob
- Base64
- URL：需要跨域支持
- object URL：需要在当前
document创建
如果没有编辑图片，则输出值类型不变 (与输入值一致)
如果编辑了图片，输入类型为 File 时，输出类型也为 File，其它情况均输出 Blob 类型
如果未开启编辑模式，且限制了图片大小或宽高，则需要 await openEditor(...)
编程式提供数据源
1<!-- 示例: 输入图片链接进行编辑 --> 2<!-- 如果需要附加图片名称，可以先转换为 File 类型再输入 --> 3 4<script setup> 5const imgPondRef = ref() 6 7async function urlToFile(url, fileName) { 8 const blob = await (await fetch(url)).blob() 9 return new File([blob], fileName, { type: blob.type }) 10} 11 12async function openEditor() { 13 const file = urlToFile('https://picsum.photos/100', '100x100.jpg') 14 await imgPondRef.value.openEditor(file) 15} 16 17function upload(file) { 18 return POST.upload(import.meta.env.VITE_APP_UPLOAD_API, { 19 file, 20 }).then(res => res.data.data) 21} 22</script> 23 24<template> 25 <ImgPond 26 v-show="false" 27 ref="imgPondRef" 28 :upload="upload" 29 /> 30 31 <el-button @click="openEditor"> 32 编辑图片 33 </el-button> 34</template>
校验文件扩展名
1<script setup> 2const accept = '.jpg,.jpeg,.png' 3const extension = accept.split(',') 4 5function validator(source) { 6 let valid = true 7 if (source instanceof File) { 8 valid = extension.includes(source.name.replace(/.+\./, '.').toLowerCase()) 9 if (!valid) { 10 alert(`"${source.name}" 的格式不在可支持范围: ${accept}`) 11 } 12 } 13 return valid 14} 15</script> 16 17<template> 18 <ImgPond 19 :accept="accept" 20 :validator="validator" 21 /> 22</template>
输出体积
图片经过编辑后，输出的体积与以下因素相关：
- 原图体积
- 配置或用户设置的图片宽度
- 配置或用户设置的图片高度
- 配置的图片格式
- 用户设置的品质系数
上传状态
1<script setup> 2const imgPondRef = ref() 3 4console.log(imgPondRef.value.uploading) 5</script> 6 7<template> 8 <ImgPond ref="imgPondRef" /> 9</template>
自定义上传时机
- 不配置 upload，绑定值得到二进制文件
- 将 srcAt 配置为
'url'，使图片能够正常预览 - 在适当时机自行上传
自定义 trigger
1<template> 2 <ImgPond 3 class="custom-trigger" 4 list-type="text" 5 mb="8px" 6 > 7 <el-button>自定义 trigger</el-button> 8 </ImgPond> 9</template> 10 11<style lang="scss" scoped> 12.custom-trigger { 13 14 :deep(.pic-viewer), 15 :deep(.el-upload-list), 16 :deep(.el-upload__tip), 17 :deep(.el-upload__text) { 18 display: none; 19 } 20} 21</style>
自定义 tip
1<ImgPond 2 :width="200" 3 :height="100" 4 :size="10" 5 :count="1" 6> 7 <template #tip="{ count, size, dimension, accept }"> 8 <div>{{ count }}</div> 9 <div>{{ size }}</div> 10 <div>{{ dimension }}</div> 11 <div>{{ accept }}</div> 12 </template> 13</ImgPond>
嵌套在表格中
以宽高 50px 为例，修改为如下样式：
1:deep(.pic-viewer li) { 2 margin: 0 !important; // 如果允许多张，则去掉这行 3 4 img { 5 height: 50px !important; 6 } 7} 8 9:deep(.el-upload-list__item) { 10 width: 50px; 11 height: 50px; 12 margin: 0; // 如果允许多张，则去掉这行 13 14 &>.el-upload-list__item-status-label { 15 width: 34px; 16 height: 18px; 17 18 &>i { 19 margin-top: 0; 20 } 21 } 22 23 .el-upload-list__item-actions { 24 line-height: 50px; 25 font-size: 16px; 26 27 &>span+span { 28 margin-left: 4px; 29 } 30 } 31} 32 33:deep(.el-upload) { 34 width: 50px; 35 height: 50px; 36 line-height: 50px; 37 margin: 0; 38 39 &>.el-icon-plus { 40 font-size: initial; 41 } 42 43 &>.el-upload__text { 44 display: none; 45 } 46}
更新日志
各版本详细改动请参考 release notes
No vulnerabilities found.
No security vulnerabilities found.