ImgPond
图片上传一站式解决方案。
## 特性
- 数据双向绑定 `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))
- 编辑图片
- 自由裁剪
- 锁定比例裁剪 (支持设置具体的值及其公差，也支持设置一个范围)
- 翻转、缩放、无级角度旋转
- 输出品质调节
- 限制图片
- 数量上限、下限
- 体积上限、下限
- 格式筛选
- 自定义校验
- 拖拉拽排序
- 预览图片
- 局部注册并传参，或全局注册并传参
## 安装
```shell
npm i yj-imgpond
```
### 外置依赖
- vue@2
- element-ui
- pic-viewer
### 局部注册
```vue
```
### 全局注册
```ts
import PicViewer from 'pic-viewer'
import ImgPond from 'yj-imgpond'
Vue.use(PicViewer, {
// 全局配置
})
Vue.use(ImgPond, {
// 全局配置
})
```
### CDN + ESM
> ⚠ 暂不支持 (ElementUI 未提供 ESM 导出)
### CDN + UMD
```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 | [原生 input 的 accept](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept) | string | `'image/*'` |
| validator | 自定义数据源校验器 | (source: File \| Blob \| string) => boolean | |
| disabled | 禁用状态 | boolean | `false` |
| editable | 是否开启编辑功能 | boolean | `true` |
| aspectRatio | 锁定裁剪比例 | string / [string?, string?] | |
| aspectRatioTolerance | 锁定裁剪比例的公差 | number | `0` |
| isCompress | 超出宽度是否自动压缩 | boolean | true |
| compressMaxWidth | 自动压缩宽度 | number | 1280 |
| compressorParams | 压缩图片参数（同compressorjs参数） | number | {convertTypes: [], convertSize: Infinity} |
| 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 时需要配置 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](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)，如 `'image/jpeg,image/png'`
### cropperMode
- 0: 没有限制
- 1: 限制裁剪框不超过图片容器的范围。
- 2: 限制最片容器尺寸以在裁剪容器中展示。 如果图片容器和裁剪容器的比例不同，则图片容器以 cover 模式填充（图片容器保持原有比例，最长边和裁剪容器大小一致，短边等比缩放，可能会有部分区域不可见)。
- 3: 限制图片容器尺寸以在裁剪器中展示。 如果图片容器和裁剪容器的比例不同，则图片容器以 contain 模式填充（图片容器保持原有比例，最短边和裁剪容器大小一直，长边等比缩放，可能会有留白）。
## 插槽
同 `el-upload`
## 事件
| 名称 | 说明 | 回调参数 |
| ---------- | ------------------------------------------------------- | ---------------- |
| size-error | 选中图片的体积不符合要求时触发 | 图片体积（Byte） |
| ... | `el-upload` 的事件（Function 类型的属性，去掉 on 前缀） | |
```html
```
## 方法
| 名称 | 说明 | 参数 |
| ---------- | ------------------ | ------------------------------------------------------------------------ |
| openEditor | 打开图片编辑对话框 | (source: File \| Blob \| string \| File[] \| Blob[] \| string[]) => void |
参数为输入的数据源，支持的数据类型有：
- File
- Blob
- Base64
- URL：需要跨域支持
- object URL：需要在当前 `document` 创建
如果没有编辑图片，则输出值类型不变 (与输入值一致)
如果编辑了图片，输入类型为 File 时，输出类型也为 File，其它情况均输出 Blob 类型
## 编程式提供数据源
```vue
编辑图片
```
## 校验文件扩展名
```vue
```
## 上传状态
```vue
```
## 自定义上传时机
1. 不配置 upload，绑定值得到二进制文件
2. 将 srcAt 配置为 `'url'`，使图片能够正常预览
3. 在适当时机自行上传
## 自定义 trigger
```vue
自定义 trigger
```
## 自定义 tip
```vue
{{ count }}
{{ size }}
{{ aspectRatio }}
{{ 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;
}
}
```
## 升级日志
### v0.12.10
feat: 实现自动压缩功能，当图片宽度超过 compressMaxWidth 时进行压缩
### v0.12.10
feat: 增加文件建议大小和溢出提示配置，文件大小溢出时自动压缩，如果压缩后仍然大于预期大小，将提示用户自行处理
### v0.12.9
feat: 支持配置图片压缩功能，实时显示裁剪后的图片大小