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;
}| 字段名 | 类型 | 说明 |
|---|---|---|
current | String | 当前需要优先显示的图片链接 |
urls | String[] | 需要预览的图片链接列表 |
参数取值说明
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://URIcontent://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");| 参数 | 类型 | 说明 |
|---|---|---|
retCode | int | 错误码,0 表示成功,非 0 表示失败 |
retMsg | String | 错误描述信息 |
运行行为
- 由 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。 - 安全性:加载外部链接时注意校验协议和来源,避免加载不可信资源导致风险。
