图片选择器组件

概述

ImageSelector 是专门用于图片上传和选择的组件，支持图片预览、裁剪、尺寸验证等功能，提供网格展示和拖拽上传体验。

组件路径：web/apps/web-ele/src/components/zq-form/image-selector/

组件名称：ImageSelector

功能特性

• 图片上传：支持点击选择和拖拽上传
• 图片预览：支持大图预览
• 图片裁剪：可选启用裁剪功能
• 尺寸验证：支持最小/最大宽高限制
• 网格展示：已选图片网格显示
• 最近图片：快速选择最近上传的图片
• 多选支持：单选/多选模式

Props

属性	类型	默认值	说明
modelValue	string | string[]	-	图片 ID
multiple	boolean	false	是否多选
placeholder	string	'请选择图片'	占位符
disabled	boolean	false	是否禁用
clearable	boolean	true	是否可清除
showImageInfo	boolean	true	是否显示图片信息
maxSize	number	10	最大文件大小（MB）
maxWidth	number	0	最大宽度（0 不限制）
maxHeight	number	0	最大高度（0 不限制）
minWidth	number	0	最小宽度
minHeight	number	0	最小高度
accept	string[]	['image/*']	接受的文件类型
gridColumns	number	4	网格列数
sortable	boolean	false	是否可排序
enableCrop	boolean	false	是否启用裁剪
cropAspectRatio	number	-	裁剪比例
cropShape	'rect' | 'circle'	'rect'	裁剪形状
size	number	-	触发器尺寸（正方形）
width	number	-	触发器宽度
height	number	-	触发器高度
source	string	'form'	文件来源标识

Events

事件	参数	说明
update:modelValue	string | string[] | undefined	值更新
change	string | string[] | undefined	值变化

Expose 方法

方法	说明
openModal()	打开图片选择弹窗

使用示例

单图上传

<template>
  <ImageSelector v-model="imageId" placeholder="请选择图片" />
</template>

<script setup>
import { ref } from 'vue';

const imageId = ref('');
</script>

多图上传

<template>
  <ImageSelector
    v-model="imageIds"
    :multiple="true"
    :grid-columns="4"
  />
</template>

<script setup>
import { ref } from 'vue';

const imageIds = ref([]);
</script>

头像上传（带裁剪）

<template>
  <ImageSelector
    v-model="avatarId"
    :enable-crop="true"
    :crop-aspect-ratio="1"
    crop-shape="circle"
    :size="100"
    placeholder="上传头像"
  />
</template>

<script setup>
import { ref } from 'vue';

const avatarId = ref('');
</script>

尺寸限制

<template>
  <ImageSelector
    v-model="imageId"
    :min-width="800"
    :min-height="600"
    :max-size="5"
    placeholder="最小 800x600，最大 5MB"
  />
</template>

自定义触发器尺寸

<template>
  <ImageSelector
    v-model="imageId"
    :width="200"
    :height="150"
  />
</template>

与表单设计器集成

在表单设计器中，该组件作为 image-selector 类型的表单项使用：

{
  "type": "image-selector",
  "field": "cover_image",
  "label": "封面图",
  "props": {
    "multiple": false,
    "maxSize": 5,
    "enableCrop": true,
    "cropAspectRatio": 1.78,
    "placeholder": "请上传封面图"
  }
}

典型应用场景

• 头像上传：enableCrop=true + cropShape="circle" + cropAspectRatio=1
• 封面图：enableCrop=true + cropAspectRatio=16/9
• 产品图片：multiple=true + gridColumns=4
• 证件照：minWidth/minHeight 限制尺寸