图片上传一站式解决方案。
## ⚠ DEPRECATED
> **Warning**
>
> ImgPond 已推出 Element Plus (Vue 3) & Element UI (Vue 2.7/2.6) 一体通用版本
>
> 不仅能力得到增强，为了后续的漏洞修复和迭代优化，请迁移至原作者 [cloydlau](https://github.com/cloydlau) 的 [faim](https://github.com/cloydlau/faim)
## 特性
- 数据双向绑定 `v-model`，支持任意绑定值类型
- 数据源
- 用户选择本地文件 (File)
- 编程式提供数据源 (File/Blob/Base64/URL/[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))
- 编辑图片
- 格式转换
- 尺寸指定
- 品质调节
- 自由裁剪 & 锁定比例裁剪
- 翻转、缩放、无级角度旋转
- 限制图片
- 格式筛选
- 尺寸或尺寸范围 (间接限制宽高比例)
- 大小上限、下限
- 数量上限、下限
- 自定义校验
- 多选
- 拖拉拽排序
- 预览图片 ([pic-viewer](https://github.com/cloydlau/pic-viewer) 提供技术支持)
- 局部注册并传参，或全局注册并传参 ([vue-global-config](https://github.com/cloydlau/vue-global-config) 提供技术支持)
## 安装
```shell
npm i imgpond
```
### 外置依赖
- vue@2
- element-ui
- pic-viewer
### 局部注册
```vue
```
### 全局注册
```ts
import PicViewer from 'pic-viewer'
import ImgPond from 'imgpond'
Vue.use(PicViewer, {
// 全局配置
})
Vue.use(ImgPond, {
// 全局配置
})
```
### CDN + ESM
> ⚠ 暂不支持 (ElementUI 未提供 ESM 导出)
### CDN + IIFE
```html
```
## 属性
| 名称 | 说明 | 类型 | 默认值 |
|----------------------|--------------------------------|---------------------------------------------------------------------------------|-------------|
| value / v-model | 绑定值 | any | |
| arrayed | 绑定值是否为数组类型，默认自动 | boolean | |
| srcAt | 图片链接的位置 | string / symbol / (value: any) => any | |
| upload | 调用接口上传图片，返回图片链接 | (output: File \| Blob) => Promise \| 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 时需要配置 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept)
> ⚠ 用户仍可以选择其它类型，文件类型校验应使用 validator
可选值：
- 文件扩展名，不区分大小写，如 `'.jpg.jpeg.png'`
- [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml#image)，如 `'image/jpeg,image/png'`
### outputType
开启编辑模式时，可以指定输出的图片格式，可选值参考 [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml#image)
## 插槽
同 `el-upload`
## 事件
| 名称 | 说明 | 回调参数 |
|--------------|-----------------------------------------------------|-----------------|
| size-error | 未开启编辑模式，且图片大小不符合要求时触发 | 图片体积 (Byte) |
| width-error | 未开启编辑模式，且图片宽度不符合要求时触发 | 图片宽度 (像素) |
| height-error | 未开启编辑模式，且图片高度不符合要求时触发 | 图片高度 (像素) |
| ... | `el-upload` 的事件 (Function 类型的属性，去掉 on 前缀) | |
```html
```
## 方法
| 名称 | 说明 | 参数 |
|------------|------------------|--------------------------------------------------------------------------|
| openEditor | 打开图片编辑对话框 | (source: File \| Blob \| string \| File[] \| Blob[] \| string[]) => void |
参数为输入的数据源，支持的数据类型有：
- File
- Blob
- Base64
- URL：需要跨域支持
- object URL：需要在当前 `document` 创建
如果没有编辑图片，则输出值类型不变 (与输入值一致)
如果编辑了图片，输入类型为 File 时，输出类型也为 File，其它情况均输出 Blob 类型
如果未开启编辑模式，且限制了图片大小或宽高，则需要 `await openEditor(...)`
## 编程式提供数据源
```vue
编辑图片
```
## 校验文件扩展名
```vue
```
## 输出体积
图片经过编辑后，输出的体积与以下因素相关：
- 原图体积
- 配置或用户设置的图片宽度
- 配置或用户设置的图片高度
- 配置的图片格式
- 用户设置的品质系数
## 上传状态
```vue
```
## 自定义上传时机
1. 不配置 upload，绑定值得到二进制文件
2. 将 srcAt 配置为 `'url'`，使图片能够正常预览
3. 在适当时机自行上传
## 自定义 trigger
```vue
自定义 trigger
```
## 自定义 tip
```vue
{{ count }}
{{ size }}
{{ dimension }}
{{ accept }}
```
## 嵌套在表格中
以宽高 `50px` 为例，修改为如下样式：
```scss
: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](https://github.com/cloydlau/imgpond/releases)
