组件功能
ImageSelect 用于在表单中选择本地图片文件,并自动转换为 Base64 格式输出,适用于头像上传、封面图设置、缩略图配置等图片上传场景。
基础用法
Template 示例:
<ImageSelect name="avatar" />
效果展示如下:


上传图片后,效果展示如下:
上传图片后 | hover 展示删除图标,点击删除 | 组件禁用效果 |
![]() | ![]() | ![]() |
属性说明
属性名 | 类型 | 描述 | 默认值 |
name ★ | string | 表单字段名称 | - |
defaultValue | string | 默认图片值(base64 或 URL) | - |
required | boolean | 是否为必填字段 | false |
disabled | boolean | 是否禁用 | false |
maxSize | number | 最大文件大小(单位为 Byte(1MB = 1024 × 1024 Byte),不超过 20MB) | - |
注意:
★ 标记为必填属性。
使用示例
带默认值的图片选择
Template 示例:
<ImageSelectname="avatar"defaultValue="https://picsum.photos/id/237/400/400"/>
效果展示:


限制文件大小
Template 示例:
<ImageSelectname="thumbnail"maxSize="2097152"required="true"/>
此时表示限制上传的图片文件大小为 2 MB,当用户上传的图片超过文件大小限制后,将上传失败并给出错误提示。


禁用状态
Template 示例:
<ImageSelectname="logo"disabled="true"defaultValue="https://picsum.photos/id/237/400/400"/>
效果展示:


在 Multi-Agent 模式下,复合表单澄清询问 Widget 包含 ImageSelect 组件。以下以“应用信息收集助手”为例进行说明:
1. 进入 Agent 高级设置,在澄清样式中选择复合表单澄清。


Agent 输出格式选择身份信息介绍 Widget。


2. 用户开始对话,应用通过 Widget 进行澄清询问和信息收集。
澄清询问 Widget | 用户填写信息 |
![]() | ![]() |
3. 用户提交表单后,收集的头像图片展示在输出结果中。


功能特性
支持的图片格式
JPEG/JPG
PNG
GIF
WebP
BMP
SVG
文件大小限制
默认限制:20MB。
自定义上限:通过
maxSize 属性设置。当上传文件大小超出限制时会进行错误提示。
输出格式
选择的图片会转换为 Base64 格式。
输出值附带前缀标识:
ADPWidgetImageSelect=data:image/...。支持使用预设的 URL 或 base64 作为默认值。
交互行为
点击选择区域打开文件选择器进行文件上传。
支持拖拽上传文件。
预览图片并 hover 展示清除按钮。
图片加载失败时显示错误提示。
注意:
1. 建议设置合理的
maxSize 值,避免选择过大的图片影响加载性能和传输效率。2. 组件会自动验证文件类型,只接受图片格式文件。
3. 图片转换为 base64 后,数据体积会增大约 33%。
4. 组件依赖 FileReader API 实现文件读取,主流现代浏览器均已支持。
5. 当图片加载失败时,组件会显示错误状态提示,但不会阻断用户的后续操作。




