Skip to content

previewImage ​

预览图片 ​

该方法用于根据 SDK 传入的图片链接列表,拉起 APP 侧图片预览页面,并展示指定图片。常见使用场景包括图片查看、截图预览、相册图片预览、动态图片预览等。


方法声明 ​

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

参数说明 ​

SUDOPPreviewImageParams ​

java
public class SUDOPPreviewImageParams implements Serializable {
    /**
     * 当前显示图片的链接
     */
    public String current;

    /**
     * 需要预览的图片链接列表
     */
    public String[] urls;
}
字段名类型说明
currentString当前需要优先显示的图片链接
urlsString[]需要预览的图片链接列表

参数取值说明 ​

current ​

current 表示打开预览页面后默认展示的图片。

示例:

java
params.current = "https://example.com/image_1.jpg";

如果 current 为空,APP 可默认展示 urls 中的第一张图片。


urls ​

urls 表示可预览的图片链接列表。

示例:

java
params.urls = new String[]{
        "https://example.com/image_1.jpg",
        "https://example.com/image_2.jpg",
        "https://example.com/image_3.jpg"
};

图片链接可以根据 APP 实现支持以下类型:

  • 网络图片地址,例如 https://example.com/image.jpg
  • 本地文件路径,例如 /data/user/0/com.xxx.xxx/cache/image.jpg
  • file:// URI
  • content:// URI

实际支持的链接类型取决于 APP 图片加载框架或预览页面实现。


返回说明 ​

通过 SUDOPStateHandle 将调用结果返回给 SDK。

调用成功 ​

图片预览页面成功拉起时调用:

java
handle.success(dataJson);

示例实现中不需要返回业务数据,因此直接返回 null:

java
handle.success(null);

调用失败 ​

如果图片预览页面无法打开,或参数异常,可调用:

java
handle.failure(retCode, retMsg);

示例:

java
handle.failure(-1, "previewImage params invalid");
参数类型说明
retCodeint错误码,0 表示成功,非 0 表示失败
retMsgString错误描述信息

运行行为 ​

  • 由 SDK 触发:当 SDK 需要预览图片时,会调用 previewImage。
  • APP 拉起图片预览页面:APP 根据传入的 current 和 urls 打开图片预览 Activity 或自定义页面。
  • 默认展示 current:预览页面应优先展示 params.current 对应图片。
  • 支持多图切换:如果 urls 中包含多张图片,预览页面可支持左右滑动查看。
  • 立即回调成功:示例实现中先调用 handle.success(null),然后启动 PreviewImageActivity。

代码示例 ​

java
@Override
public void previewImage(SUDOPStateHandle handle, SUDOPPreviewImageParams params) {
    handle.success(null);
    PreviewImageActivity.start(context, params);
}

示例实现逻辑说明 ​

1. 返回调用成功 ​

java
handle.success(null);

示例实现中,收到调用后立即向 SDK 返回成功,表示 APP 已接受预览图片请求。


2. 启动图片预览页面 ​

java
PreviewImageActivity.start(context, params);

APP 侧启动自定义图片预览页面,并将 params 传入页面中。

由于 SUDOPPreviewImageParams 实现了 Serializable,可以通过 Intent 携带参数:

java
Intent intent = new Intent(context, PreviewImageActivity.class);
intent.putExtra("params", params);
context.startActivity(intent);

推荐实现流程 ​

text
SDK 调用 previewImage
        ↓
APP 校验 params、urls、current
        ↓
返回调用结果 handle.success(null)
        ↓
启动图片预览页面
        ↓
预览页面加载 urls 图片列表
        ↓
定位并展示 current 对应图片
        ↓
用户滑动查看或关闭页面

预览页面建议能力 ​

功能说明
默认展示指定图片优先展示 current 对应的图片
多图滑动支持在 urls 图片列表中左右滑动切换
图片缩放支持双指缩放、双击缩放
长图适配支持长图滚动或等比缩放显示
加载状态网络图片加载时显示 loading
加载失败提示图片加载失败时显示占位图或错误提示
保存图片可根据业务需要支持长按保存到相册
关闭预览支持点击返回或关闭按钮退出预览页面

参数校验建议 ​

建议在启动预览页面前进行基础校验:

java
if (params == null || params.urls == null || params.urls.length == 0) {
    handle.failure(-1, "previewImage params invalid");
    return;
}

如果 current 为空或不在 urls 中,可默认展示第一张图片:

java
if (params.current == null || !Arrays.asList(params.urls).contains(params.current)) {
    params.current = params.urls[0];
}

常见失败场景 ​

失败场景建议处理
params 为空handle.failure(-1, "previewImage params invalid")
urls 为空handle.failure(-1, "previewImage urls empty")
current 不在 urls 中默认展示第一张或返回失败
图片链接格式不支持显示加载失败占位图
网络图片加载失败显示加载失败提示
本地图片文件不存在显示加载失败提示
Activity 启动失败handle.failure(-1, "previewImage start activity fail")

注意事项 ​

  • 必须回调:方法被调用后,应通过 handle.success(...) 或 handle.failure(...) 通知 SDK 调用结果。
  • 示例为立即成功:示例实现中先调用 handle.success(null) 再启动 Activity,表示请求已受理,不代表图片一定加载成功。
  • 图片加载失败不一定回调 SDK:预览页面中的单张图片加载失败,一般在页面内提示用户即可。
  • UI 操作在主线程执行:启动 Activity、弹窗、图片预览等 UI 操作应在主线程进行。
  • 支持链接类型取决于实现:网络地址、本地路径、file://、content:// 是否支持,取决于图片加载框架和预览页面实现。
  • Serializable 传参限制:如果图片列表较大,不建议通过 Serializable 传递大量数据,可考虑使用全局缓存、Parcelable 或临时存储。
  • 上下文要求:如果使用非 Activity 的 context 启动页面,需要为 Intent 添加 FLAG_ACTIVITY_NEW_TASK。
  • 安全性:加载外部链接时注意校验协议和来源,避免加载不可信资源导致风险。