← 返回图片处理组件参考 · 全部使用指导

图片处理使用指导

• 图片处理使用指导
  • 工作原理
  • 快速上手
  • 案例一：上传前压缩并显示大小
  • 案例二：圆形头像
  • 案例三：拍照加水印
  • 案例四：照片转 Base64 交给大模型识图
  • 案例五：多步串联
  • 案例六：处理失败时告诉用户原因
  • 常见问题
  • 平台说明
  • 完整 .aia 源码与操作指导
    • 图片编辑与头像
  • 原图与输出

手机拍的照片动辄几 MB、几千像素，直接上传又慢又费流量。图片处理组件在手机上就能把照片压小、 裁剪、旋转、加水印、转成 Base64，最常用在「上传之前」这一步。

工作原理

• 每个方法都直接返回新图片的路径，原图不动。返回的路径可以直接设给图像组件显示、交给 Web 上传， 也可以当作下一步处理的输入；
• 自动摆正：手机照片常带「拍摄方向」信息，处理前会先按它摆正，所以竖着拍的照片不会变横；
• 大图不怕：特别大的原图读入时自动降低分辨率，不会因内存不够闪退；
• 存放位置：新图片存在应用专属目录的 ImageTools 文件夹，不需要存储权限，卸载 App 时一起删除；
• 出错时返回空文本，并触发本组件的处理失败时（参数是方法名和中文原因），不会弹系统错误框。

图片来源可以是素材文件名、照相机或图像选择器返回的路径、本地路径。

快速上手

拖一个照相机、一个按钮、一个图像和一个图片处理：

when 按钮1.Click() {
  照相机1.TakePicture()
}

when 照相机1.AfterPicture(图像位址) {
  图像1.Picture = 图片处理1.Compress(图像位址, 1080, 80)
}

拍照后显示的是压缩版：最长边不超过 1080 像素、质量 80，体积通常只有原图的十分之一左右。

案例一：上传前压缩并显示大小

从相册选一张照片，压缩后显示前后大小，再上传到服务器：

global 小图 = ""

when 图像选择器1.AfterPicking() {
  小图 = 图片处理1.Compress(图像选择器1.Selection, 1080, 80)
  图像1.Picture = 小图
  标签_大小.Text = join("原图 ", round(图片处理1.FileSize(图像选择器1.Selection) / 1024), " KB → 压缩后 ", round(图片处理1.FileSize(小图) / 1024), " KB")
}

when 按钮_上传.Click() {
  Web1.Url = "https://example.com/upload"
  Web1.PostFile(小图)
}

最长边 1080、质量 80 是清晰和体积的平衡点；只用来做缩略图可以用 480、质量 70。

案例二：圆形头像

从相册选图，先从中间裁出正方形，再裁成圆形（圆外透明），最后压小：

when 图像选择器1.AfterPicking() {
  图像_头像.Picture = 图片处理1.Resize(图片处理1.CropCircle(图像选择器1.Selection), 300, 300)
}

裁成圆形（图像位址）（CropCircle）会自动从中间取最大的正方形，所以不用先调用裁成正方形； 圆形头像总是存成 PNG（保留透明）。

案例三：拍照加水印

给照片右下角加上时间水印，适合打卡、巡检拍照：

when 照相机1.AfterPicture(图像位址) {
  图像1.Picture = 图片处理1.AddTextWatermark(图像位址, 计时器1.FormatDateTime(计时器1.Now(), "yyyy-MM-dd HH:mm"), &HFFFFFFFF, 0, "右下")
}

要点：

• 字号填 0 时按图片宽度自动（约宽度的 1/20），不同分辨率的照片水印比例一致；
• 位置可填 左上、右上、左下、右下、居中（也认 top-left 这类英文写法）；
• 文字带淡阴影，浅色、深色背景上都看得清。

案例四：照片转 Base64 交给大模型识图

很多大模型接口要求图片以 Base64 文本放进请求里。先压缩再转，文本会小很多：

global 照片Base64 = ""

when 照相机1.AfterPicture(图像位址) {
  照片Base64 = 图片处理1.ToBase64(图片处理1.Compress(图像位址, 1024, 80))
  标签1.Text = join("Base64 长度：", textLength(照片Base64))
}

拿到文本后按接口要求放进请求（需要时拼上 data:image/jpeg;base64, 前缀）。 接口返回的 Base64 图片用Base64转图片（Base64文本）（FromBase64）还原成文件：

when Web1.GotText(URL网址, 响应代码, 响应类型, 响应内容) {
  图像1.Picture = 图片处理1.FromBase64(响应内容)
}

案例五：多步串联

每一步的返回值都是新图片路径，可以直接作为下一步的输入。例如把横拍的证件照旋转、裁成正方形、转黑白：

when 按钮_处理.Click() {
  图像1.Picture = 图片处理1.Grayscale(图片处理1.CropSquare(图片处理1.Rotate(图像选择器1.Selection, 90)))
}

也可以把「输出格式」属性设为 PNG，让缩放、裁剪等结果存成 PNG（「压缩」总是存 JPEG）。

案例六：处理失败时告诉用户原因

每个方法失败时都返回空文本，同时触发本组件的「处理失败时」事件，参数是失败的方法名和中文原因。 只想知道成没成功，判断返回值是不是空文本就够了；要把原因显示出来，再接这个事件：

when 按钮_压缩.Click() {
  var 新图 = 图片处理1.Compress(文本输入框_图片.Text, 1080, 80)
  if 新图 == "" {
    标签_状态.Text = "没有压缩成功，原因见下方"
  } else {
    图像1.Picture = 新图
    标签_状态.Text = "压缩完成"
  }
}

when 图片处理1.Failed(函数名称, 消息) {
  标签_原因.Text = join("处理失败：", 函数名称, "，", 消息)
}

跑起来看：在文本输入框里填一个不存在的文件名（如 不存在.jpg）点压缩，标签_状态显示「没有压缩成功，原因见下方」， 标签_原因以「处理失败：Compress，」开头，后面是读不到图片的原因；不会弹出系统错误框， 屏幕的「出现错误时」也不会触发。换成真实的图片（素材名或图像选择器的选中项）再点，图像显示压缩后的新图。

常见问题

平台说明

• 安卓：全部支持；
• 鸿蒙：全部支持。新图片在后台保存：图像组件显示、Web 上传会自动等待或直接使用内存中的图片； 刚处理完立刻「转Base64」会提示稍后再转，「文件大小」在保存完成前返回 0。

完整 .aia 源码与操作指导

下载 .aia 源码

真实图片编辑的完整操作页：导入后自动把仓库伴侣图标的Base64解码成图片，可立即预览并逐项处理；也可选择系统相册照片。默认每个操作从原图开始，勾选连续处理后才串联上一结果。

导入 ImageToolsAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

图片编辑与头像

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 真实图片编辑的完整操作页：导入后自动把仓库伴侣图标的Base64解码成图片，可立即预览并逐项处理；也可选择系统相册照片。默认每个操作从原图开始，勾选连续处理后才串联上一结果。 覆盖检查 21/21。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

原图与输出

示例原图 sample.png 字节复制自仓库 aiplayapp/assets/app-icon.png（850×852）；同一文件的完整Base64也在全局变量里，初始化通过真实FromBase64落盘。这使伴侣及独立包都能得到可处理的文件路径；没有通过给图片处理传网络链接来冒充本地文件。

图片输出自动存入组件自己的目录，不改原图。鸿蒙输出路径可能先返回、后台才编码完成；图像组件会处理内存结果，但FileSize暂为0、ToBase64可能提示等待。稍后点击读取或转换，不用固定延时冒充完成通知。相册已有照片才可选图；长期保存处理后的路径需自己记录并保证文件未被删除。