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;
}| 字段名 | 类型 | 说明 |
|---|---|---|
count | int | 最多可以选择的图片张数 |
sizeType | String[] | 所选图片的尺寸类型,支持 original、compressed |
sourceType | String[] | 图片来源,支持 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
}
]
}| 字段名 | 类型 | 说明 |
|---|---|---|
tempFilePaths | String[] | 选择图片后生成的本地临时文件路径列表 |
tempFiles | Array | 图片文件信息列表 |
tempFiles[].path | String | 图片本地临时路径 |
tempFiles[].size | long | 图片文件大小,单位字节 |
具体返回字段可根据 SDK 要求实现,如果 SDK 对返回格式有固定协议,应以 SDK 协议为准。
选择失败
选择失败或用户取消时调用:
java
handle.failure(retCode, retMsg);| 参数 | 类型 | 说明 |
|---|---|---|
retCode | int | 错误码,0 表示成功,非 0 表示失败 |
retMsg | String | 错误描述信息 |
示例:
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 | 返回失败 |
| 用户取消选择 | 返回失败或取消状态 |
| 用户拒绝相册权限 | 返回失败,并提示权限被拒绝 |
| 用户拒绝相机权限 | 返回失败,并提示权限被拒绝 |
| 相机不可用 | 返回失败 |
| 相册选择器启动失败 | 返回失败 |
| 图片压缩失败 | 返回失败 |
| 临时文件生成失败 | 返回失败 |
选择图片数量超过 count | APP 应限制选择数量或截断结果 |
注意事项
- 必须回调:用户选择成功、失败或取消后,都需要通过
handle.success(...)或handle.failure(...)回调 SDK。 - count 限制:APP 侧应根据
params.count限制最多选择的图片数量。 - 默认原图:示例实现中默认
isOriginal = true,只有sizeType包含compressed时才返回压缩图。 - 来源校验:如果
sourceType中不包含album或camera,需要返回失败。 - 权限申请:调用相册或相机前,需要根据系统版本和实现方式处理权限。
- 临时文件路径:返回给 SDK 的图片路径建议为 APP 可读的本地临时文件路径。
- 网络路径不适用:该接口用于本地选择或拍摄图片,不应直接返回网络图片地址。
- 主线程调用 UI:拉起相册、相机、弹窗等 UI 操作应在主线程执行。
- 图片压缩耗时:图片压缩、复制到临时目录等操作建议放到子线程处理。
- 兼容 Android 版本:建议优先使用系统推荐的图片选择方案,并兼容不同 Android 版本的权限策略。
