tencent cloud

定制小程序 SDK 接口
最后更新时间：2025-05-23 18:45:54
定制小程序 SDK 接口
最后更新时间： 2025-05-23 18:45:54
为了丰富使用场景，小程序 SDK 对外开放了一部分接口，这部分接口可以由 superapp 定制实现，以提供 superapp 特色的能力给小程序使用。

前提条件

实现小程序 SDK 的接口定制，需要按照如下的方式自定义 MiniAppProxy：
说明：
定义实现类并继承 BaseMiniAppProxyImpl，并使用@ProxyService(proxy = MiniAppProxy.class)注解进行修饰。
@ProxyService(proxy = MiniAppProxy.class)
public class MiniAppProxyImpl extends BaseMiniAppProxyImpl{}
前提条件的步骤完成后，可以按照下面的方法进行小程序 SDK 接口进行自定义，小程序SDK主要支持了以下几种类型的接口。

一、定制胶囊按钮功能

1. 定制关闭按钮事件监听

定制胶囊按钮的关闭事件监听，能够让 superapp 在关闭按钮点击时获取到对应的回调事件。
关闭按钮示意图：

API 说明：onCapsuleButtonCloseClick方法返回值表示是否自定义关闭按钮监听，返回值为 true 表示自定义，false（默认值）表示使用默认监听。
/**
 * 点击胶囊按钮的关闭选项
 * 调用环境：子进程
 *
 * @param miniAppContext 小程序运行环境(小程序进程，非主进程)
 * @param onCloseClickedListener 点击小程序关闭时回调
 * @return 不支持该接口，请返回false
 */
public abstract boolean onCapsuleButtonCloseClick(IMiniAppContext miniAppContext,
        DialogInterface.OnClickListener onCloseClickedListener);
示例代码：
    @Override
    public boolean onCapsuleButtonCloseClick(IMiniAppContext miniAppContext,
                                             DialogInterface.OnClickListener onCloseClickedListener) {
        Log.e("TAG","onCapsuleButtonCloseClick"+miniAppContext.getMiniAppInfo());
        //handle close mini app event
        return true;
    }

2. 定制更多按钮事件监听

定制更多按钮的事件监听，能够让 superapp 在点击更多按钮点击时监听到对应回调事件。
更多按钮示意图：



API 说明：onCapsuleButtonMoreClick 方法返回值表示是否自定义更多按钮监听，返回值为 true 表示自定义，false（默认值）表示使用默认监听。
/**
 * 点击胶囊按钮的更多选项
 *
 * @param miniAppContext 小程序运行环境
 * @return 不支持该接口，请返回false
 */
public abstract boolean onCapsuleButtonMoreClick(IMiniAppContext miniAppContext);
示例代码：
@Override
public boolean onCapsuleButtonMoreClick(IMiniAppContext miniAppContext) {
    // 弹出自定义更多面板
    return true;
}

3. 定制更多按钮展示列表及点击事件

当用户触发更多按钮点击事件时，会弹出如下的可选扩展按钮列表，默认列表示意图如下：

通过重写 MiniAppProxy 的 getMoreItems 方法，可以实现定制更多菜单扩展按钮列表。
API 说明：
getMoreItems 方法返回值表示定制的扩展按钮列表；
方法参数 MoreItemList.Builder 用于添加扩展按钮，扩展按钮的展示顺序和添加顺序一致；
MoreItem的id属性用于区分按钮，需要具备唯一性。
/**
 * 返回胶囊更多面板的按钮，扩展按钮的ID需要设置为[100, 200]这个区间中的值，否则，添加无效
 * 调用环境：子进程
 *
 * @param builder
 * @return
 */
public abstract ArrayList<MoreItem> getMoreItems(MoreItemList.Builder builder);

警告：
扩展按钮的ID需要设置为[100, 200]这个区间中的值，否则，添加无效。
示例代码：
@Override
public ArrayList<MoreItem> getMoreItems(IMiniAppContext miniAppContext, MoreItemList.Builder builder) {
    MoreItem item1 = new MoreItem();
    // 设置菜单id(必须)，扩展按钮的ID需要设置为[100, 200]这个区间中的值，否则，添加无效。
    item1.id = ShareProxyImpl.OTHER_MORE_ITEM_1;
    // 设置菜单标题(可选)
    item1.text = getString(miniAppContext, R.string.applet_mini_proxy_impl_other1);
    // 设置菜单图标(可选)
    item1.drawable = R.mipmap.mini_demo_about;
    // 设置无障碍描述(可选), 默认是菜单标题
    item2.contentDescription = "菜单无障碍描述";
    // 监听点击事件
    item2.onClickListener = new MoreItem.MoreItemClickListener() {
        @Override
        public void onClick(IMiniAppContext context, MoreItem item) {
            // 处理点击事件
        }
    };

    // 自行调整顺序。
    builder.addMoreItem(item1)
            // 根据需求添加内置菜单项
            .addRestart(getString(miniAppContext, R.string.applet_mini_proxy_impl_restart),
                    R.mipmap.mini_demo_restart_miniapp)
            // 根据需求添加内置菜单项
            .addAbout(getString(miniAppContext, R.string.applet_mini_proxy_impl_about),
                    R.mipmap.mini_demo_about)
            // 根据需求添加内置菜单项
            .addSetting(getString(miniAppContext, R.string.mini_sdk_more_item_setting_0),
                    R.drawable.mini_sdk_setting,
                    //设置无障碍描述(可选), 默认是菜单标题
                    "小程序设置");
    return builder.build();
}

private String getString(IMiniAppContext miniAppContext, int id) {
    return miniAppContext.getContext().getString(id);
}

二、定制图片选择

小程序 SDK 提供默认的图片选择，默认使用 Android 系统自带的相册选择器进行选择，在小程序调用多媒体选择 wx.chooseImage、wx.chooseVideo、wx.chooseMedia时触发。
定制图片选择可以通过重写 BaseMiniAppProxyImpl 的 chooseMediaFromAlbum和chooseMediaFromCamera方法实现。
API 说明：
参数 Context：当前小程序页面的 activity 实例。
参数 options：媒体选择选项；ChooseMediaOptions。
参数 listener：图片选择回调接口；ChooseMediaProxy.IChooseMediaListener。
返回值 boolean：返回值为 false 表示使用默认图片选择实现，返回值为 true 表示使用定制图片选择实现。
/**
 * 从相册选择媒体文件
 * @param context
 * @param options
 * @param listener 
 * @return
 */
public boolean chooseMediaFromAlbum(Activity context, ChooseMediaOptions options, ChooseMediaProxy.IChooseMediaListener listener) 
/**
 * 从相机拍摄媒体文件
 * @param context
 * @param options
 * @param listener
 * @return
 */
public boolean chooseMediaFromCamera(Activity context, ChooseMediaOptions options, ChooseMediaProxy.IChooseMediaListener listener)
示例代码：
public static final int REQUEST_CHOOSE_MEDIA = 110;
public static final int REQUEST_CHOOSE_MEDIA_CAMERA = 111;

@Override
public void chooseMediaFromAlbum(Activity context, ChooseMediaOptions options, IChooseMediaListener listener) {
    try {
        TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
            @Override
            public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
                if (requestCode == REQUEST_CHOOSE_MEDIA && resultCode == Activity.RESULT_OK) {
                    ArrayList<Uri> picturePath = new ArrayList<>();
                    if (data == null) {
                        Log.e(TAG, "empty intent ,failed getting from chooseImage");
                        listener.onResult(false, null);
                        return false;
                    }
                    if (null != data.getClipData()) {
                        Log.d(TAG, "use clipdata as intent uri ");
                        ClipData clipData = data.getClipData();
                        for (int i = 0; i < clipData.getItemCount(); i++) {
                            picturePath.add(clipData.getItemAt(i).getUri());
                        }
                        Log.d(TAG, "send to mini with path " + picturePath.size());
                    } else if (null != data.getData()) {
                        Log.d(TAG, "select picture path is  " + data.getData());
                        picturePath.add(data.getData());
                    }
                    listener.onResult(true, picturePath);
                } else {
                    listener.onResult(false, null);
                }
                MiniSDK.removeActivityResultListener(this);
                return true;
            }
        });
        Intent chooserIntent = new Intent(Intent.ACTION_GET_CONTENT);
        if (options.maxCount > 1) {
            chooserIntent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true);
        }
        switch (options.mediaType) {
            case ChooseMediaOptions.MEDIA_TYPE_IMAGE:
                chooserIntent.setType("image/*");
                break;
            case ChooseMediaOptions.MEDIA_TYPE_VIDEO:
                chooserIntent.setType("video/*");
                break;
            case ChooseMediaOptions.MEDIA_TYPE_MIX:
                chooserIntent.setType("*/*");
                chooserIntent.putExtra(Intent.EXTRA_MIME_TYPES, new String[]{"image/*", "video/*"});
            default:
                chooserIntent.setType("image/*");
                break;
        }
        context.startActivityForResult(chooserIntent, REQUEST_CHOOSE_MEDIA);
    } catch (Exception e) {
        listener.onResult(false, null);
    }
}

@Override
public void chooseMediaFromCamera(Activity context, ChooseMediaOptions options, IChooseMediaListener listener) {
    Intent takePhotoIntent;
    if (options.mediaType == ChooseMediaOptions.MEDIA_TYPE_VIDEO) {
        takePhotoIntent = new Intent(MediaStore.ACTION_VIDEO_CAPTURE);
        int duration = options.duration;
        if (duration < 1 || duration > 60000) {
            duration = 60000;
        }
        takePhotoIntent.putExtra(MediaStore.EXTRA_DURATION_LIMIT, duration);
        if (options.camera == ChooseMediaOptions.CAMERA_TYPE_FRONT) {
            takePhotoIntent.putExtra("android.intent.extras.CAMERA_FACING", 1);
        }
    } else {
        takePhotoIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    }

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
        takePhotoIntent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
    }

    if (takePhotoIntent.resolveActivity(context.getPackageManager()) == null) {
        Log.e(TAG, "resolveActivity failed ,has no camera app");
        listener.onResult(false, null);
        return;
    }

    if (options.cameraOutput == null) {
        Log.e(TAG, "createImageFile failed ");
        listener.onResult(false, null);
        return;
    }

    Uri imageUri = options.cameraOutput;
    takePhotoIntent.putExtra(MediaStore.EXTRA_OUTPUT, imageUri);
    context.startActivityForResult(takePhotoIntent, REQUEST_CHOOSE_MEDIA_CAMERA);
    TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
        @Override
        public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
            if (requestCode != REQUEST_CHOOSE_MEDIA_CAMERA) {
                return false;
            }
            if (resultCode != Activity.RESULT_OK) {
                listener.onResult(false, null);
            } else {
                ArrayList<Uri> picturePath = new ArrayList<>();
                picturePath.add(imageUri);
                listener.onResult(true, picturePath);
            }
            MiniSDK.removeActivityResultListener(this);
            return true;
        }
    });
}

三、定制图片预览

小程序 SDK 提供默认的图片预览实现，在小程序调用多媒体选择 wx.previewImage 时触发。
定制图片预览可以通过重写 BaseMiniAppProxyImpl 的 openImagePreview 方法实现。
默认图片预览页面如下图：

API 说明：
参数 Context：当前小程序页面的 activity 实例；
参数 selectedIndex：当前选中图片在列表中位置；
参数 pathList：待展示图片路径列表；
返回值 boolean：返回值为 false 表示使用默认图片展示，返回值为 true 表示使用定制图片展示。
/**
 * 打开图片预览界面
 * 调用环境：子进程
 *
 * @param context 当前Activity
 * @param selectedIndex 当前选择的图片索引
 * @param pathList 图片路径列表
 * @return 不支持该接口，请返回false
 */
public abstract boolean openImagePreview(Context context, int selectedIndex, List<String> pathList);
示例代码：
/**
 * 打开图片预览界面
 *
 * @param context       当前Activity
 * @param selectedIndex 当前选择的图片索引
 * @param pathList      图片路径列表
 * @return 不支持该接口，请返回false
 */
@Override
public boolean openImagePreview(Context context, int selectedIndex, List<String> pathList) {
    //todo start your image preview 
    Intent intent = new Intent(context, CustomPreviewActivity.class);
    intent.putExtra("curIndex",selectedIndex);
    intent.putStringArrayListExtra("pathList", pathList);
    context.startActivity(intent);
    return true;
}

四、定制授权弹框中的用户信息

小程序申请获取用户信息的时候，会弹出用户授权弹窗；superapp 可以定制用户授权弹窗部分信息，包括有：头像图片和用户昵称，如下图：

可以通过重写 BaseMiniAppProxyImpl 的 getNickName 和 getAvatarUrl 方法实现定制。
API说明：
参数 appId：当前请求授权的小程序 appId；
参数 AsyncResult：用于返回用户信息给小程序 SDK。
/**
 * 获取scope.userInfo授权用户昵称
 *
 * @return 用户昵称
 */
public abstract String getNickName();

/**
 * 获取scope.userInfo授权用户头像（默认使用应用图标）
 *
 * @return 用户头像地址
 */
public abstract String getAvatarUrl();
示例代码：
@Override
public String getNickName() {
    return "userInfo测试";
}

@Override
public String getAvatarUrl() {
    return "https://xxx/avatar.png"
}

五、定制图片加载器

警告：
由于小程序 SDK 没有默认的图片加载器实现，所以图片的加载依赖于 superapp 的实现；若 superapp 未实现图标加载器，则会导致部分页面的图片加载异常。
superapp 开发者，需要通过重写 BaseMiniAppProxyImpl 的 getDrawable 方法实现图片加载的定制。
API 说明：
参数 context：当前请求授权的小程序进程上下文；
参数 source：图片来源，可以是本地或者网络图片；
参数 width：图片宽度；
参数 height：图片高度；
参数 defaultDrawable：默认图片，用于加载中和加载失败；
返回值 Drawable：加载的 drawable 对象。
@Override
public Drawable getDrawable(Context context, String source, int width, int hight, Drawable defaultDrawable)
示例代码：
@Override
public Drawable getDrawable(Context context, String source, int width, int hight, Drawable defaultDrawable) {
    //接入方接入自己的ImageLoader
    //示例代码里使用开源的universalimageloader
    UniversalDrawable drawable = new UniversalDrawable();
    if (TextUtils.isEmpty(source)) {
        return drawable;
    }
    drawable.loadImage(context, source);
    return drawable;
}

六、定制小程序数据按账户隔离存储

通过重写 BaseMiniAppProxyImpl 的 getAccount 方法实现小程序数据的隔离存储。
API 说明：返回值是用户账号（必须唯一），设置后数据会按账号隔离存储,不建议使用用户敏感信息。
/**
 * 用户账号,必须唯一，设置后数据会按账号隔离存储,不建议使用用户敏感信息
 * 调用环境：主进程
 */
@Override
public String getAccount() {
    return "tmf_test";
}

七、定制虚拟域名

小程序打用到默认的虚拟域名，这个域名并非真实的域名，在浏览器中是无法访问的，如果需要自定义可以按照如下配置进行设置。
默认虚拟域名如下图：

定制虚拟域名，需要重写 BaseMiniAppProxyImpl 的 configData 方法，并拦截 configType 为 MiniConfigData.TYPE_DOMAIN的方法实现自定义。
示例代码：
@Override
public MiniConfigData configData(Context context, int configType, JSONObject params) {
    if(configType == MiniConfigData.TYPE_DOMAIN) {
        //虚拟域名配置
        MiniConfigData.DomainConfig domainConfig = new MiniConfigData.DomainConfig();
        domainConfig.domain = "test.com";

        return new MiniConfigData
                .Builder()
                .domainConfig(domainConfig)
                .build();
    }
    
    return new MiniConfigData
                .Builder()
                .build();
}

八、定制小程序内 WebView 的 userAgent

可以通过重写 BaseMiniAppProxyImpl 的 configData 方法，并拦截 configType 为MiniConfigData.TYPE_WEBVIEW的方法实现自定义。
示例代码：
@Override
public MiniConfigData configData(Context context, int configType, JSONObject params) {
    if(configType == MiniConfigData.TYPE_WEBVIEW) {
        //webView userAgent
        String ua = params.optString(MiniConfigData.WebViewConfig.WEBVIEW_CONFIG_UA);
        MiniConfigData.WebViewConfig webViewConfig = new MiniConfigData.WebViewConfig();
        //设置开发者需要追加的userAgent，注意：不要把原始的ua设置进去了
        webViewConfig.userAgent = "key/value";

        return new MiniConfigData
                .Builder()
                .webViewConfig(webViewConfig)
                .build();
    }

    return new MiniConfigData
            .Builder()
            .build();
}

九、定制扫码能力

小程序 SDK 提供了默认的扫描实现（参考扫码扩展库），也对外提供接口，供用户定制扫码能力。
定制扫码能力，需要重写 BaseMiniAppProxyImpl 的 enterQRCode 方法实现。
API 说明：
参数 context：当前发起扫码的小程序进程上下文；
参数 onlyFromCamera：是否只允许摄像头扫码；
参数 AsyncResult：扫码结果回调；
返回值 boolean：true 表示自定义扫码能力，false 表示使用内置扫码能力（需集成扫码扩展库）。
/**
 * 扫码二维码
 *
 * @param context        上下文
 * @param onlyFromCamera 只允许摄像头扫码
 * @param result         扫描结果
 * @return true:自定义扫码;false:使用内置扫码
 */
@Override
public boolean enterQRCode(Context context, boolean onlyFromCamera, AsyncResult result);

十、指定小程序保存文件的存储路径

通过重写 BaseMiniAppProxyImpl 的 getSaveFileDir 方法，实现小程序 API 保存图片、视频到系统相册中的指定目录。
示例代码：
/**
 * 指定小程序API保存图片、视频到系统相册中的目录
 *
 */
public  String getSaveFileDir(){
return "myapp";
}
注意：
默认路径为 tcmpp。

十一、监听小程序生命周期

可以通过重写 BaseMiniAppProxyImpl 的 onAppStateChange 方法，实现监听小程序生命周期。
API说明：
参数 appState：当前小程序的生命周期状态，定义参考 AppState；
参数 MiniAppEvent：当前小程序的生命周期事件。
/**
 * 小程序生命周期事件回调
 * 调用上下文环境：主进程UI线程
 *
 * @param appState 事件状态
 * @param event 事件
 */
public abstract void onAppStateChange(@AppState int appState, MiniAppEvent event);

十二、定制基础库更新策略和监听

可以通过重写 BaseMiniAppProxyImpl 的 isUpdateBaseLib 方法，实现监听小程序基础库的更新信息。
API说明：
参数 context：上下文；
参数 data：小程序基础库的更新信息；
返回值：true 表示更新基础库，false 表示不更新基础库；默认值为 false。
/**
 * 基础库检测到更新时，是否进行更新
 * @param context
 * @param data 基础库信息数据
 * @return true:更新;false:不更新，默认为 true
 */
public abstract boolean isUpdateBaseLib(Context context, JSONObject data);

本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈