yj-imgpond

v0.12.7

Published

6 months ago

Image uploading one-stop solution.

Downloads

0High
0Medium
0Low

hanneil

vue img image pic picture upload uploader crop cropper cropperjs sortablejs element-ui el-upload dropzone filepond

特性

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

规划

支持 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 'yj-imgpond'

export default {
  components: { PicViewer, ImgPond }
}
</script>

全局注册

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

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

CDN + ESM

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

CDN + UMD

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css" />
  </head>

  <body>
    <div id="app">
      <img-pond v-model="value"></img-pond>
    </div>
    <script src="https://unpkg.com/vue@2"></script>
    <script src="https://unpkg.com/element-ui/lib/index.js"></script>
    <script src="https://unpkg.com/[email protected]"></script>
    <script src="https://unpkg.com/[email protected]"></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 | | isCompressor | 是否开启压缩功能 | boolean | true | | cropperMode | 图片裁剪模式 | 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'

cropperMode

0: 没有限制
1: 限制裁剪框不超过图片容器的范围。
2: 限制最片容器尺寸以在裁剪容器中展示。如果图片容器和裁剪容器的比例不同，则图片容器以cover模式填充（图片容器保持原有比例，最长边和裁剪容器大小一致，短边等比缩放，可能会有部分区域不可见)。
3: 限制图片容器尺寸以在裁剪器中展示。如果图片容器和裁剪容器的比例不同，则图片容器以contain模式填充（图片容器保持原有比例，最短边和裁剪容器大小一直，长边等比缩放，可能会有留白）。

插槽

同 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;
  }
}