tencent cloud

腾讯云超级应用服务

文档腾讯云超级应用服务代码接入指引AndroidAndroid API自定义小程序能力自定义小程序 API

自定义小程序 API

PDF
聚焦模式
字号
最后更新时间： 2026-03-20 17:56:26
如果在小程序中需要调用某些 superapp 提供的能力，在小程序 SDK 未实现或无法实现时，开发者可以通过注册扩展（自定义） API 来实现相关能力，使得小程序能够调用 superapp 中提供的自定义 API 能力 。

Superapp 实现自定义 API

Superapp 通过继承 BaseJsPlugin 实现自定义的小程序API能力。
说明：
继承 BaseJsPlugin 并用注解进行定义 @JsPlugin(secondary = true)；
定义一个方法，方法只能有一个参数且参数必须是 RequestEvent 类型；
然后在方法上定义注解@JsEvent("事件名")，当小程序 js 调用“事件名”时就会调用到@JsEvent修饰的对应方法；
@JsEvent 支持定义多个事件名；
支持同步或异步返回数据（同一事件只能选择一种方式）；
可以通过调用 sendState 给小程序端多次返回中间状态，sendState 调用结束后必须调用 ok 或 fail 标识整个流程结束。
示例代码：
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
    @JsEvent("customAsyncEvent")
    public void custom(final RequestEvent req) {
        //获取参数
        //req.jsonParams
        //获取当前小程序信息
        //mMiniAppContext.getMiniAppInfo();
        //异步返回数据
        //req.fail();
        //req.ok();
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("key", "test");
        } catch (JSONException e) {
            e.printStackTrace();
        }
        req.ok(jsonObject);
    }

    @JsEvent("customSyncEvent")
    public String custom1(final RequestEvent req) {
        //获取参数
        //req.jsonParams
        //获取当前小程序信息
        //mMiniAppContext.getMiniAppInfo();
        //同步返回数据
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("key", "value");
        } catch (JSONException e) {
            throw new RuntimeException(e);
        }
        return req.okSync(jsonObject);
    }

    /**
     * 覆盖内置API样例（getAppBaseInfo为SDK内置API）
     * @param req
     */
    @JsEvent("getAppBaseInfo")
    public void getAppBaseInfo(final RequestEvent req) {
        //获取参数
        //req.jsonParams
        //获取当前小程序信息
        //mMiniAppContext.getMiniAppInfo();
        //异步返回数据
        //req.fail();
        //req.ok();
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("key", "test");
        } catch (JSONException e) {
            e.printStackTrace();
        }
        req.ok(jsonObject);
    }
    
    @JsEvent("testState")
    public void testState(final RequestEvent req) {

      try {
          //回调中间状态
          req.sendState(req, new JSONObject().put("progress", 1));
          req.sendState(req, new JSONObject().put("progress", 30));
          req.sendState(req, new JSONObject().put("progress", 60));
          req.sendState(req, new JSONObject().put("progress", 100));
      } catch (JSONException e) {
          e.printStackTrace();
      }

      JSONObject jsonObject = new JSONObject();
      try {
          jsonObject.put("key", "test");
          req.ok(jsonObject);
      } catch (JSONException e) {
        throw new RuntimeException(e);
      }
    }
}

小程序中调用方法

//异步api调用
var opts = {
   api_name: 'customAsyncEvent',
   progress: function(res) {
     //sendState状态监听代码
   },
   success: function(res) {},
   fail: function(res) {},
   complete: function(res) {},
   data: { // 入参
      name : 'kka',
      age : 22
   }
 }
 wx.invokeNativePlugin(opts); 

//同步api调用
var opts = {
   api_name: 'customSyncEvent',
   sync:true
}
var rst = wx.invokeNativePlugin(opts);

进阶使用

使用 wx.api 方式调用自定义 API

自定义 API 支持在终端 app 配置文件的方式进行配置，在小程序中通过直接调用 wx.api 的方式来调用。
1. 配置自定义 API
参考如下的模板配置自定义 API 的参数信息：
说明：
配置模板中，自定义 API 的配置信息会被放在如下的 JSON 文件中。
JSON 文件外层的 extApi 字段用于存放自定义API数组，extApi 中的每一个对象表示一个自定义 API 的配置信息；
JSON 文件外层的 overwriteWxApi 字段用于配置自定义事件是否覆盖默认的小程序 API 实现。当设置为 true 时，如果自定义的 API 事件名与小程序 SDK 内置的方法名相同，则会覆盖 SDK 内置的方法。最终调用时会调用开发者自定义的 API。
每个自定义的 API 配置需要包含如下三个关键字：
name：自定义 API 的事件名称，需要与@JsEvent定义的事件名称一致；
sync：是否同步调用，需要与“创建API”示例数据返回方式保持一致；
params：自定义 API 的参数描述，其中：参数支持 JSON 格式，可以嵌套对象； 字符串类型的参数值初始化为 ""（空字符串）； 数字类型的参数值初始化为 0。
模板如下：
{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": 0,
        "object": {
          "key": ""
        }
      }
    },
    {
      "name": "customAsyncEvent2",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    }
   ], 
   "overwriteWxApi": false
}
2. 指定自定义 API 的配置文件路径
将定义的 API 配置文件存放到工程的 assets 目录下（文件名和路径开发者可以自己定义）。

代码中指定自定义 API 配置文件的路径信息
@ProxyService(proxy = MiniAppProxy.class)
public class MiniAppProxyImpl extends BaseMiniAppProxyImpl {
      @Override
    public MiniConfigData configData(Context context, int configType, JSONObject params) {
        if(configType == MiniConfigData.TYPE_CUSTOM_JSAPI) {
            //自定义JsApi配置
            MiniConfigData.CustomJsApiConfig customJsApiConfig = new MiniConfigData.CustomJsApiConfig();
            customJsApiConfig.jsApiConfigPath = "tcmpp/custom-config.json";

            return new MiniConfigData
                    .Builder()
                    .customJsApiConfig(customJsApiConfig)
                    .build();
        }
      
      return null;
}
3. 小程序开发者调用自定义 API
举例：
Superapp 自定义 customAsyncEvent 和 getAppBaseInfo 两个自定义 API，其配置文件如下：

{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "customAsyncEvent",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "getAppBaseInfo",
      "sync": false,
      "params": {
      }
    }
  ],
  "overwriteWxApi": true
}
小程序开发者可以通过如下的方式访问自定义 API。
var opts = {
    progress: function(res) {},
    success: function(res) {},
    fail: function(res) {},
    complete: function(res) {}
}
wx.testState(opts); 

wx.customAsyncEvent({"name":"123","age":"18"})
wx.getAppBaseInfo()//会覆盖系统API，然后调用到自定义API中
注意：
由于自定义 API 配置文件中 overwriteWxApi 属性的值配置为 true，当小程序调用 wx.getAppBaseInfo 时，会调用 superapp 自定义 getAppBaseInfo 实现。

在自定义 API 中启动 Activity

如因业务需要，需要在自定义 API 中拉起 Activity 来处理业务，可以通过如下方式处理：
1. 添加 Activity 返回监听，并在监听处理完成后移除监听：
注意：
注册监听和移除监听建议配对使用，否则会有内存泄漏的风险。
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
    @JsEvent("testStartActivityForResult")
    public void testStartActivityForResult(final RequestEvent req) {
      Activity activity = req.activityRef.get();
      TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
          @Override
          public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
              TmfMiniSDK.removeActivityResultListener(this);

              Log.i(ModuleApplet.TAG, data.getStringExtra("key"));
              req.ok();
              return true;
          }
      });
  }
}
2. 启动新的 Activity：
注意：
启动 Activity 时，requestCode 必须>=1000000，否则可能与内部 requestCode 冲突，引起未知问题。
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
    @JsEvent("testStartActivityForResult")
    public void testStartActivityForResult(final RequestEvent req) {
      Activity activity = req.activityRef.get();
      TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
          @Override
          public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
              TmfMiniSDK.removeActivityResultListener(this);

              Log.i(ModuleApplet.TAG, data.getStringExtra("key"));
              req.ok();
              return true;
          }
      });

      //注意：requestCode必须>=1000000，否则可能与内部requestCode冲突，引起未知问题
      activity.startActivityForResult(new Intent(activity, TransActivity.class), 1000000);
  }
}

自定义 API 问题排查

如果自定义 API 出现调用错误，可以参考 Android 常见问题 进行处理。

上一篇: 小程序文件管理下一篇: 自定义小程序视图组件

帮助和支持

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

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

文档反馈