ImgPond

图片上传一站式解决方案。

特性

数据双向绑定 v-model，支持任意绑定值类型
数据源
- 用户选择本地文件 (File)
- 编程式提供数据源 (File/Blob/Base64/URL/object URL)
编辑图片
- 自由裁剪
- 锁定比例裁剪 (支持设置具体的值及其公差，也支持设置一个范围)
- 翻转、缩放、无级角度旋转
- 输出品质调节
限制图片
- 数量上限、下限
- 体积上限、下限
- 格式筛选
- 自定义校验
拖拉拽排序
预览图片 (pic-viewer 提供技术支持)
局部注册并传参，或全局注册并传参 (vue-global-config 提供技术支持)

规划

支持 Vue 3
i18n

安装

npm i imgpond

外置依赖

vue@2
element-ui
pic-viewer

局部注册

<template>
  <ImgPond
    v-model="value"
    v-bind="{/* 局部配置 */}"
  />
</template>

<script>
import PicViewer from 'pic-viewer'
import ImgPond from 'imgpond'

export default {
  // eslint-disable-next-line vue/no-unused-components
  components: { PicViewer, ImgPond },
}
</script>

全局注册

import PicViewer from 'pic-viewer'
import ImgPond from 'imgpond'

Vue.use(PicViewer, {
  // 全局配置
})
Vue.use(ImgPond, {
  // 全局配置
})

CDN + ESM

⚠ 暂不支持 (ElementUI 未提供 ESM 导出)

CDN + IIFE

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/element-ui/lib/theme-chalk/index.css"
  >
</head>

<body>
  <div id="app">
    <img-pond v-model="value"></img-pond>
  </div>
  <script src="https://cdn.jsdelivr.net/npm/vue@2"></script>
  <script src="https://cdn.jsdelivr.net/npm/element-ui/lib/index.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/pic-viewer@0.10"></script>
  <script src="https://cdn.jsdelivr.net/npm/imgpond@0.12"></script>
  <script>
    Vue.use(PicViewer)
    Vue.use(ImgPond)

    new Vue({
      data() {
        return {
          value: undefined,
        }
      },
    }).$mount('#app')
  </script>
</body>

</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	原生 input 的 accept	string	`'image/*'`
validator	自定义数据源校验器	(source: File \| Blob \| string) => boolean
disabled	禁用状态	boolean	`false`
editable	是否开启编辑功能	boolean	`true`
aspectRatio	锁定裁剪比例	string / [string?, string?]
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 张
[1, 10]：限制数量下限不低于 1 张，且上限不高于 10 张

size

10：限制体积上限不高于 10 MB
[1]：限制体积下限不低于 1 MB
[1, 10]：限制体积下限不低于 1 MB，且上限不高于 10 MB

aspectRatio

1/1：限制宽高比为 1 比 1
['1/1']：限制宽高比下限不低于 1 比 1
['1/1', '2/1']：限制宽高比下限不低于 1 比 1，且上限不高于 2 比 1

accept

通过文件对话框选择图片时，优先展示指定类型的文件

⚠ 用户仍可以选择其它类型，文件类型校验应使用 validator

语法：

文件扩展名，不区分大小写，如 '.jpg.jpeg.png'
MIME type，如 'image/jpeg,image/png'

插槽

同 el-upload

事件

名称	说明	回调参数
size-error	选中图片的体积不符合要求时触发	图片体积（Byte）
...	`el-upload` 的事件（Function 类型的属性，去掉 on 前缀）

<ImgPond
  @remove="onRemove"
  @beforeUpload="onBeforeUpload"
/>

方法

名称	说明	参数
openEditor	打开图片编辑对话框	(source: File \| Blob \| string \| File[] \| Blob[] \| string[]) => void

参数为输入的数据源，支持的数据类型有：

File
Blob
Base64
URL：需要跨域支持
object URL：需要在当前 document 创建

如果没有编辑图片，则输出值类型不变 (与输入值一致)

如果编辑了图片，输入类型为 File 时，输出类型也为 File，其它情况均输出 Blob 类型

编程式提供数据源

<!-- 示例: 输入图片链接进行编辑 -->
<!-- 如果需要附加图片名称，可以先转换为 File 类型再输入 -->

<template>
  <ImgPond
    v-show="false"
    ref="imgPondRef"
    :upload="upload"
  />

  <el-button @click="openEditor">
    编辑图片
  </el-button>
</template>

<script setup>
const imgPondRef = ref()

async function urlToFile(url, fileName) {
  const blob = await (await fetch(url)).blob()
  return new File([blob], fileName, { type: blob.type })
}

function openEditor() {
  const file = urlToFile('https://picsum.photos/100', '100x100.jpg')
  imgPondRef.value.openEditor(file)
}

function upload(file) {
  return POST.upload(import.meta.env.VITE_APP_UPLOAD_API, {
    file,
  }).then(res => res.data.data)
}
</script>

校验文件扩展名

<template>
  <ImgPond
    :accept="accept"
    :validator="validator"
  />
</template>

<script setup>
const accept = '.jpg,.jpeg,.png'
const extension = accept.split(',')

function validator(source) {
  let valid = true
  if (source instanceof File) {
    valid = extension.includes(source.name.replace(/.+\./, '.').toLowerCase())
    if (!valid) {
      alert(`"${source.name}" 的格式不在可支持范围: ${accept}`)
    }
  }
  return valid
}
</script>

上传状态

<template>
  <ImgPond ref="imgPondRef" />
</template>

<script setup>
const imgPondRef = ref()

console.log(imgPondRef.value.uploading)
</script>

自定义上传时机

不配置 upload，绑定值得到二进制文件
将 srcAt 配置为 'url'，使图片能够正常预览
在适当时机自行上传

自定义 trigger

<template>
  <ImgPond
    class="custom-trigger"
    list-type="text"
    mb="8px"
  >
    <el-button>自定义 trigger</el-button>
  </ImgPond>
</template>

<style lang="scss" scoped>
.custom-trigger {

  :deep(.pic-viewer),
  :deep(.el-upload-list),
  :deep(.el-upload__tip),
  :deep(.el-upload__text) {
    display: none;
  }
}
</style>

自定义 tip

<ImgPond
  aspectRatio="375/120"
  :size="10"
  :count="1"
>
  <template #tip="{ aspectRatio, size, count, accept }">
    <div>{{ count }}</div>
    <div>{{ size }}</div>
    <div>{{ aspectRatio }}</div>
    <div>{{ accept }}</div>
  </template>
</ImgPond>

嵌套在表格中

以宽高 50px 为例，修改为如下样式：

:deep(.pic-viewer li) {
  margin: 0 !important; // 如果允许多张，则去掉这行

  img {
    height: 50px !important;
  }
}

:deep(.el-upload-list__item) {
  width: 50px;
  height: 50px;
  margin: 0; // 如果允许多张，则去掉这行

  &>.el-upload-list__item-status-label {
    width: 34px;
    height: 18px;

    &>i {
      margin-top: 0;
    }
  }

  .el-upload-list__item-actions {
    line-height: 50px;
    font-size: 16px;

    &>span+span {
      margin-left: 4px;
    }
  }
}

:deep(.el-upload) {
  width: 50px;
  height: 50px;
  line-height: 50px;
  margin: 0;

  &>.el-icon-plus {
    font-size: initial;
  }

  &>.el-upload__text {
    display: none;
  }
}

更新日志

各版本详细改动请参考 release notes。

cloydlau/imgpond