Skip to content

saveImageToPhotosAlbum ​

保存图片到系统相册 ​

该方法用于将 APP 本地图片文件保存到用户设备的系统相册中。通常用于游戏截图保存、分享海报保存、二维码保存、战绩图保存等场景。

SDK 会传入一个本地图片文件路径,APP 侧需要校验文件是否存在,并将该图片写入系统相册。保存完成后,通过 SUDOPStateHandle 将结果回传给 SDK。


方法声明 ​

java
/**
 * 保存图片到系统相册
 *
 * @param handle 用于向 SDK 返回处理结果的状态句柄
 * @param params 请求参数
 */
void saveImageToPhotosAlbum(
        SUDOPStateHandle handle,
        SUDOPSaveImageToPhotosAlbumParams params
);

参数说明 ​

SUDOPSaveImageToPhotosAlbumParams ​

java
public class SUDOPSaveImageToPhotosAlbumParams {
    /**
     * 图片文件路径,可以是临时文件路径或永久文件路径(本地路径),不支持网络路径
     */
    public String filePath;
}
字段名类型说明
filePathString图片文件路径,可以是临时文件路径或永久文件路径;必须是本地路径,不支持网络路径

返回说明 ​

通过 SUDOPStateHandle 将保存结果返回给 SDK。

保存成功 ​

保存成功时调用:

java
handle.success(dataJson);

该接口成功时通常不需要返回业务数据,可以传 null 或空字符串:

java
handle.success(null);

或:

java
handle.success("");

保存失败 ​

保存失败时调用:

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

示例:

java
handle.failure(-1, "The filePath does not exist.");

运行行为 ​

  • 由 SDK 触发:当游戏或 SDK 需要将本地图片保存到系统相册时,会调用 saveImageToPhotosAlbum。
  • APP 校验文件路径:APP 侧需要检查 params.filePath 是否为空、文件是否存在,以及是否为本地文件路径。
  • APP 写入系统相册:校验通过后,APP 将对应图片写入系统相册。
  • 异步或同步回调:保存完成后,APP 需要通过 handle.success(...) 或 handle.failure(...) 通知 SDK 保存结果。
  • 权限处理:在部分 Android 版本中,保存到相册可能需要申请存储或媒体权限,APP 应自行处理权限申请和兼容逻辑。

代码示例 ​

java
@Override
public void saveImageToPhotosAlbum(
        SUDOPStateHandle handle,
        SUDOPSaveImageToPhotosAlbumParams params
) {
    File file;

    if (params.filePath == null || !(file = new File(params.filePath)).exists()) {
        handle.failure(-1, "The filePath does not exist.");
        return;
    }

    boolean result = false;

    try {
        result = saveImageToGallery(context, file);
    } catch (Exception e) {
        handle.failure(-1, "saveImageToPhotsAlbum error:" + e);
        return;
    }

    if (result) {
        handle.success(null);
    } else {
        handle.failure(-1, "saveImageToPhotsAlbum fail");
    }
}

推荐实现流程 ​

text
SDK 调用 saveImageToPhotosAlbum
        ↓
APP 校验 params.filePath
        ↓
判断文件是否存在
        ↓
检查或申请相册/媒体存储权限
        ↓
将图片保存到系统相册
        ↓
保存成功:handle.success(null)
保存失败:handle.failure(retCode, retMsg)

常见失败场景 ​

失败场景建议处理
filePath 为空handle.failure(-1, "The filePath does not exist.")
文件不存在handle.failure(-1, "The filePath does not exist.")
传入网络图片地址返回失败,不支持网络路径
文件不是有效图片返回失败,并提示图片格式异常
无相册或媒体写入权限申请权限,用户拒绝时返回失败
系统相册写入失败返回失败,并附带具体错误信息
保存过程中发生异常捕获异常并通过 handle.failure 返回

注意事项 ​

  • 必须回调:无论保存成功还是失败,都需要调用 handle.success(...) 或 handle.failure(...)。
  • 只支持本地路径:filePath 必须是本地图片文件路径,不支持 HTTP/HTTPS 等网络路径。
  • 文件存在性校验:保存前必须校验文件是否存在,避免无效路径导致异常。
  • 权限兼容:不同 Android 版本的相册保存权限要求不同,APP 需要根据系统版本自行适配。
  • Android 10 及以上:建议使用 MediaStore 保存到相册,适配分区存储机制。
  • Android 9 及以下:可能需要申请 WRITE_EXTERNAL_STORAGE 权限。
  • 避免阻塞主线程:图片复制、写入相册和媒体库刷新可能耗时,建议放到子线程执行。
  • 错误信息准确:失败时建议返回明确的错误原因,便于 SDK 或业务侧定位问题。
  • 方法名拼写:示例中的错误信息为 saveImageToPhotsAlbum,实际实现时可统一为 saveImageToPhotosAlbum,避免日志歧义。