tencent cloud

腾讯云超级应用服务

错误提示 UI 自定义

下载
聚焦模式
字号
最后更新时间: 2026-08-26 10:16:01

功能概述

从 2.4.3 版本起,SDK 内部错误提示(Toast/弹窗)统一收口,superapp 可通过实现扩展点 MiniErrorUIProxy 完全接管错误提示 UI,实现提示文案、样式、交互的自定义,并消除与 superapp 自身回调导致的重复弹窗冲突。
superapp 接管后仅影响提示 UI,SDK 的容器关闭、错误上报等行为不受影响。

扩展点

MiniErrorUIProxy

public abstract class MiniErrorUIProxy {

/**
* 展示 SDK 内部错误提示。
*
* @param activity 当前承载 Activity(可能为 null,superapp 需自行判空)
* @param info 错误上下文
* @return {@code true} 表示 superapp 已自行展示,SDK 跳过内置 UI;{@code false} 表示走 SDK 默认提示。
*/
public boolean showError(Activity activity, MiniErrorInfo info) {
return false;
}

/**
* 当错误已通过 {@code ResultReceiver} 回调过 superapp({@link MiniErrorInfo#reportedToHost} 为 true)时,
* 是否抑制 SDK 内置提示。superapp 已在回调里自行弹提示时返回 {@code true} 可消除双弹。
*
* @return {@code true} 抑制内置提示;{@code false}(默认)保持现有行为。
*/
public boolean suppressBuiltInWhenReported() {
return false;
}
}
说明:
activity 可能为 null 或已进入 finishing 状态,操作前需检查。

MiniErrorInfo(错误上下文)

字段
说明
domain
错误域,用于区分错误发生在哪个阶段,取值见下方常量
code
错误码,可用于精确匹配特定错误并展示对应 UI
msg
SDK 默认错误文案,可直接使用或忽略
appId
小程序 appId,部分前置失败时可能为空
engineType
引擎类型(小程序/小游戏)
willFinish
SDK 后续是否会关闭容器。为 true 时不宜弹 Dialog,建议用 Toast
reportedToHost
为 true 时表示该错误已通过 ResultReceiver 回调过 superapp

Domain

常量
含义
DOMAIN_PRE_LAUNCH
启动前置阶段
DOMAIN_LAUNCH
加载阶段
DOMAIN_RUNTIME
运行时

接入方式

1. 继承 MiniErrorUIProxy 实现自定义逻辑;
2. 通过 @ProxyService(proxy = MiniErrorUIProxy.class) 注解注册到 SDK。

示例代码

@ProxyService(proxy = MiniErrorUIProxy.class)
public class MyErrorUIProxy extends MiniErrorUIProxy {

@Override
public boolean showError(Activity activity, MiniErrorInfo info) {
if (activity == null || activity.isFinishing()) {
return false; // Activity 不可用,走 SDK 内置提示
}
// willFinish 为 true 时 SDK 会关闭容器,不宜弹 Dialog
if (info.willFinish) {
Toast.makeText(activity, info.msg, Toast.LENGTH_SHORT).show();
} else {
showCustomDialog(activity, info);
}
return true; // 已接管
}

@Override
public boolean suppressBuiltInWhenReported() {
return true; // superapp 已在回调中自行展示,抑制内置提示避免双弹
}
}

决策流程

SDK 处理错误提示的优先级:
1. 未注册 MiniErrorUIProxy:走内置提示。
2. 错误已回调 superapp 且 suppressBuiltInWhenReported() 返回 true:跳过内置提示,消除双弹。
3. showError() 返回 true :superapp 已接管,跳过内置提示。
4. 否则:走内置提示。

注意事项

activity 可能为 null 或已进入 finishing 状态,弹 Dialog 等需操作 Activity 的 UI 前需检查,并结合 info.willFinish 判断——为 true 时 SDK 会关闭容器,建议改用 Toast。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈