Skip to content

chooseImage ​

选择图片 ​

该方法用于拉起 APP 侧的图片选择能力,让用户从系统相册选择图片,或使用相机拍摄图片,并将选择结果返回给 SDK。

常见使用场景包括:用户上传头像、上传图片、选择分享图片、选择游戏内素材图片、反馈截图上传等。


方法声明 ​

java
/**
 * 选择图片
 *
 * @param handle 用于向 SDK 返回处理结果的状态句柄
 * @param params 请求参数
 */
void chooseImage(SUDOPStateHandle handle, SUDOPChooseImageParams params);

参数说明 ​

SUDOPChooseImageParams ​

java
public class SUDOPChooseImageParams {
    /**
     * 最多可以选择的图片张数
     */
    public int count;

    /**
     * 所选图片的尺寸
     * original:原图
     * compressed:压缩图
     */
    public String[] sizeType;

    /**
     * 选择图片的来源
     * album:从相册选图
     * camera:使用相机
     */
    public String[] sourceType;
}
字段名类型说明
countint最多可以选择的图片张数
sizeTypeString[]所选图片的尺寸类型,支持 original、compressed
sourceTypeString[]图片来源,支持 album、camera

参数取值说明 ​

sizeType ​

sizeType 用于指定返回图片的尺寸类型。

值说明
original返回原图
compressed返回压缩图

示例:

java
params.sizeType = new String[]{"original"};

或:

java
params.sizeType = new String[]{"compressed"};

如果同时包含 compressed,示例实现中会优先按压缩图处理:

java
boolean isOriginal = true;
if (sizeType != null) {
    for (String type : sizeType) {
        if ("compressed".equals(type)) {
            isOriginal = false;
        }
    }
}

sourceType ​

sourceType 用于指定选择图片的来源。

值说明
album从系统相册选择图片
camera使用相机拍摄图片

示例:

java
params.sourceType = new String[]{"album"};

或:

java
params.sourceType = new String[]{"camera"};

或:

java
params.sourceType = new String[]{"album", "camera"};

返回说明 ​

通过 SUDOPStateHandle 将选择图片的结果返回给 SDK。

选择成功 ​

选择成功时调用:

java
handle.success(dataJson);

成功返回的数据建议为 JSON 字符串,通常包含已选择图片的本地临时路径列表。

示例:

json
{
  "tempFilePaths": [
    "/data/user/0/com.xxx.xxx/cache/image_1.jpg",
    "/data/user/0/com.xxx.xxx/cache/image_2.jpg"
  ],
  "tempFiles": [
    {
      "path": "/data/user/0/com.xxx.xxx/cache/image_1.jpg",
      "size": 102400
    },
    {
      "path": "/data/user/0/com.xxx.xxx/cache/image_2.jpg",
      "size": 204800
    }
  ]
}
字段名类型说明
tempFilePathsString[]选择图片后生成的本地临时文件路径列表
tempFilesArray图片文件信息列表
tempFiles[].pathString图片本地临时路径
tempFiles[].sizelong图片文件大小,单位字节

具体返回字段可根据 SDK 要求实现,如果 SDK 对返回格式有固定协议,应以 SDK 协议为准。

选择失败 ​

选择失败或用户取消时调用:

java
handle.failure(retCode, retMsg);
参数类型说明
retCodeint错误码,0 表示成功,非 0 表示失败
retMsgString错误描述信息

示例:

java
handle.failure(-1, "sourceType fail to identify");

运行行为 ​

  • 由 SDK 触发:当 SDK 需要用户选择或拍摄图片时,会调用 chooseImage。
  • APP 判断图片来源:APP 根据 params.sourceType 判断使用相册、相机或弹窗让用户选择。
  • APP 判断图片质量:APP 根据 params.sizeType 判断返回原图或压缩图。
  • APP 拉起系统能力:根据来源调用系统相册选择器或相机拍摄能力。
  • 返回本地图片路径:用户选择或拍摄完成后,APP 将图片保存成本地临时文件路径,并通过 handle.success(...) 返回。
  • 失败或取消回调:如果用户取消选择、权限被拒绝、图片处理失败等,需要通过 handle.failure(...) 返回。

代码示例 ​

java
@Override
public void chooseImage(SUDOPStateHandle handle, SUDOPChooseImageParams params) {
    int count = params.count;
    String[] sizeType = params.sizeType;
    String[] sourceType = params.sourceType;

    boolean isOriginal = true;

    if (sizeType != null) {
        for (String type : sizeType) {
            if ("compressed".equals(type)) {
                isOriginal = false;
            }
        }
    }

    boolean isAlbum = false;
    boolean isCamera = false;

    if (sourceType != null) {
        for (String type : sourceType) {
            if ("album".equals(type)) {
                isAlbum = true;
            } else if ("camera".equals(type)) {
                isCamera = true;
            }
        }
    }

    if (isAlbum && isCamera) {
        showChooseDialog(count, isOriginal, handle);
    } else if (isCamera) {
        selectCamera(count, isOriginal, handle);
    } else if (isAlbum) {
        selectAlbum(count, isOriginal, handle);
    } else {
        handle.failure(-1, "sourceType fail to identify");
    }
}

示例实现逻辑说明 ​

1. 获取选择数量 ​

java
int count = params.count;

count 表示最多可以选择的图片数量。APP 侧应根据该值限制用户最多可选图片数量。


2. 判断图片尺寸类型 ​

java
boolean isOriginal = true;

if (sizeType != null) {
    for (String type : sizeType) {
        if ("compressed".equals(type)) {
            isOriginal = false;
        }
    }
}

示例逻辑中:

  • 默认返回原图;
  • 如果 sizeType 中包含 compressed,则返回压缩图。

3. 判断图片来源 ​

java
boolean isAlbum = false;
boolean isCamera = false;

if (sourceType != null) {
    for (String type : sourceType) {
        if ("album".equals(type)) {
            isAlbum = true;
        } else if ("camera".equals(type)) {
            isCamera = true;
        }
    }
}

示例逻辑中:

  • 包含 album:允许从相册选择;
  • 包含 camera:允许使用相机拍摄;
  • 两者都包含:弹出选择弹窗;
  • 都不包含:返回失败。

4. 根据来源执行对应逻辑 ​

java
if (isAlbum && isCamera) {
    showChooseDialog(count, isOriginal, handle);
} else if (isCamera) {
    selectCamera(count, isOriginal, handle);
} else if (isAlbum) {
    selectAlbum(count, isOriginal, handle);
} else {
    handle.failure(-1, "sourceType fail to identify");
}
条件行为
同时支持相册和相机调用 showChooseDialog,让用户选择相册或相机
仅支持相机调用 selectCamera
仅支持相册调用 selectAlbum
无法识别来源调用 handle.failure 返回失败

推荐实现流程 ​

text
SDK 调用 chooseImage
        ↓
APP 读取 count、sizeType、sourceType
        ↓
判断是否返回原图或压缩图
        ↓
判断图片来源:相册 / 相机 / 两者都支持
        ↓
检查并申请相册或相机权限
        ↓
拉起系统相册或相机
        ↓
用户选择或拍摄图片
        ↓
根据 sizeType 处理图片原图或压缩图
        ↓
生成本地临时文件路径
        ↓
选择成功:handle.success(resultJson)
选择失败/取消:handle.failure(retCode, retMsg)

权限说明 ​

根据不同图片来源,APP 侧可能需要处理以下权限。

相册 ​

不同 Android 版本权限可能不同:

  • Android 13 及以上:可能需要 READ_MEDIA_IMAGES
  • Android 12 及以下:可能需要 READ_EXTERNAL_STORAGE
  • 使用系统 Photo Picker 时,可能无需申请存储权限

相机 ​

使用相机拍摄图片通常需要:

xml
<uses-permission android:name="android.permission.CAMERA" />

如果将照片保存到外部目录,低版本系统还可能需要存储权限。


常见失败场景 ​

失败场景建议处理
sourceType 为空返回失败:sourceType fail to identify
sourceType 不包含 album 或 camera返回失败
用户取消选择返回失败或取消状态
用户拒绝相册权限返回失败,并提示权限被拒绝
用户拒绝相机权限返回失败,并提示权限被拒绝
相机不可用返回失败
相册选择器启动失败返回失败
图片压缩失败返回失败
临时文件生成失败返回失败
选择图片数量超过 countAPP 应限制选择数量或截断结果

注意事项 ​

  • 必须回调:用户选择成功、失败或取消后,都需要通过 handle.success(...) 或 handle.failure(...) 回调 SDK。
  • count 限制:APP 侧应根据 params.count 限制最多选择的图片数量。
  • 默认原图:示例实现中默认 isOriginal = true,只有 sizeType 包含 compressed 时才返回压缩图。
  • 来源校验:如果 sourceType 中不包含 album 或 camera,需要返回失败。
  • 权限申请:调用相册或相机前,需要根据系统版本和实现方式处理权限。
  • 临时文件路径:返回给 SDK 的图片路径建议为 APP 可读的本地临时文件路径。
  • 网络路径不适用:该接口用于本地选择或拍摄图片,不应直接返回网络图片地址。
  • 主线程调用 UI:拉起相册、相机、弹窗等 UI 操作应在主线程执行。
  • 图片压缩耗时:图片压缩、复制到临时目录等操作建议放到子线程处理。
  • 兼容 Android 版本:建议优先使用系统推荐的图片选择方案,并兼容不同 Android 版本的权限策略。