什么是自定义API,如何调用自定义API_移动开发平台 mPaaS(mPaaS)-阿里云帮助中心

本文分别从以下两个方面对自定义 API 进行详细的介绍：

小程序调用客户端自定义 API；
客户端发送小程序自定义事件。

小程序调用客户端自定义 API

小程序调用客户端自定义 API 步骤如下：

客户端自定义 API。

自定义 class 继承自 SimpleBridgeExtension。
```
public class CustomApiBridgeExtension extends SimpleBridgeExtension{
}
```
注意
请不要混淆该类和方法。

实现自定义方法。代码示例如下：

public class CustomApiBridgeExtension extends SimpleBridgeExtension{
    @ActionFilter
    public void tinyToNative(@BindingApiContext ApiContext apiContext,
                             @BindingRequest JSONObject params,
                             @BindingParam("param1") String param1,
                             @BindingParam("param2") String param2,
                             @BindingCallback BridgeCallback callback) {
        ···
    }
}

tinyToNative，表示小程序侧的调用方法名称，需要在 @ActionFilter 中添加。
方法中的参数，表示小程序侧传过来的参数以及客户端侧的一些 context 和 bridge。非必填，按实际需求增删。具体请参考自定义方法参数。

生成 JSONObject 结果，并将结果返回小程序。代码示例如下：

public class CustomApiBridgeExtension extends SimpleBridgeExtension{
    @ActionFilter
    public void tinyToNative(@BindingApiContext ApiContext apiContext,
                             @BindingRequest JSONObject params,
                             @BindingParam("param1") String param1,
                             @BindingParam("param2") String param2,
                             @BindingCallback BridgeCallback callback) {
        ···
        JSONObject result = BridgeResponse.SUCCESS.get();
        result.put("custom_message","value");
  // 将结果返回给小程序
        callback.sendJSONResponse(result);
    }
}

示例代码补充说明如下：

生成结果 JSONObject 成功请调用：

JSONObject result = BridgeResponse.SUCCESS.get();

若失败请调用：

JSONObject result = BridgeResponse.Error.newError(errorCode,errorMessage).get();

结果中可加自定义的参数。
```
result.put("custom_message","value");
```
将最终 JSONObject 结果返回小程序的 callback 是自定义方法参数中的 @BindingCallback BridgeCallback callback。
```
callback.sendJSONResponse(result);
```

自定义方法参数，具体说明如下：

@BindingId：String 类型，传入当前一次通信的 workId。
@BindingNode：Scope 类型，App.class 或 Page.class。框架按对应类型传入当前 App 或 Page。
@BindingApiContext：ApiContext 类型，通过该实例拿到当前 API 的 context。

@BindingExecutor：Executor 类型。选择不同的 Executor，并在其线程中执行对应的逻辑。Executor 类型名称、描述、优先级信息见下表。

Executor 类型名称	描述	优先级
ExecutorType.SYNC	直接执行不切线程，便于封装。	无
ExecutorType.UI	前台 UI 所依赖优先级最高的后台任务，不容忍排队。	`{@link Thread#NORM_PRIORITY}`
ExecutorType.URGENT_DISPLAY	前台 UI 所依赖优先级最高的后台任务，不容忍排队。	`{@link Thread#MAX_PRIORITY}`
ExecutorType.URGENT	前台 UI 所依赖优先级最高的后台任务，不容忍排队。	`{@link Thread#NORM_PRIORITY}`
ExecutorType.NORMAL	普通非紧急的后台任务，容忍排队。	`{@link Thread#MIN_PRIORITY}`
ExecutorType.IO	文件 IO 类操作持久化任务。耗时可预计，不久成功或发生异常两种情况之一。	`{@link Thread#MIN_PRIORITY}`
ExecutorType.NETWORK	网络相关的后台任务。耗时视条件波动。典型使用场景为发起 RPC 请求。	`{@link Thread#MIN_PRIORITY}`
ExecutorType.IDLE	闲散线程池，用于埋点等对耗时完全不敏感的任务。可用单线程池实现。	无

@BindingRequest：JSONObject 类型，将小程序侧的参数以 JSONObject 形式传入。

@BindingParam：默认值为 String，对应的是小程序侧的自定义参数的 key。对应值支持的参数包括 string、int、long、float、double、boolean。支持自定义 default 值。

@BindingParam(value = "stringParam", stringDefault = "default") String stringParam
@BindingParam(value = "intParam", intDefault = 1) int intParam
@BindingParam(value = "longParam", longDefault = 9223372036854775807L) long longParam
@BindingParam(value = "floatParam", floatDefault = 1.0F) float floatParam
@BindingParam(value = "doubleParam", doubleDefault = 1.79769313486231570e+308d) double doubleParam
@BindingParam(value = "booleanParam", booleanDefault = true) boolean booleanParam

@BindingCallback：BridgeCallback 类型，通过 BridgeCallback 可以向小程序发送结果。

示例代码

public class CustomApiBridgeExtension extends SimpleBridgeExtension {

    private static final String TAG = "CustomApiBridgeExtension";

    @ActionFilter
    public void tinyToNative(@BindingId String id,
                             @BindingNode(App.class) App app,
                             @BindingNode(Page.class) Page page,
                             @BindingApiContext ApiContext apiContext,
                             @BindingExecutor(ExecutorType.UI) Executor executor,
                             @BindingRequest JSONObject params,
                             @BindingParam("param1") String param1,
                             @BindingParam("param2") String param2,
                             @BindingCallback BridgeCallback callback) {
        RVLogger.d(TAG, "id: "+id+
                "\napp: "+app.toString()+
                "\npage: "+page.toString()+
                "\napiContext: "+apiContext.toString()+
                "\nexecutor: "+executor.toString());
        RVLogger.d(TAG, JSONUtils.toString(params));
        JSONObject result = BridgeResponse.SUCCESS.get();
        result.put("message", "客户端接收到参数：" + param1 + ", " + param2 + "\n返回 Demo 当前包名：" + apiContext.getActivity().getPackageName());
        // 将结果返回给小程序
        callback.sendJSONResponse(result);
    }

}

客户端注册自定义 API。容器初始化完成后，调用注册方法即可完成自定义 API 注册。注意不要混淆类名。
```
MriverEngine.registerBridge(CustomApiBridgeExtension.class);
```
小程序侧调用。代码示例如下：
```
my.call('tinyToNative', {
  param1: 'p1aaa',
  param2: 'p2bbb'
}, (result) => {
  console.log(result);
  my.showToast({
    type: 'none',
    content: result.message,
    duration: 3000,
  });
})
```
示例代码内容说明如下：
- 第一个参数为 action，与客户端自定义方法名 @ActionFilter 注解标注保持一致。
- 第二个参数为自定义参数。此示例中，客户端侧可以通过 @BindingRequest JSONObject 或 @BindingParam("param1") String param1 来接收，其中 param1、param2 值为任意字母和数字组合字符串。param1、 param2 仅为示例，自定义参数值支持的类型包括 String、int、long、boolean、float、double。
- 第三个参数为客户端的回调。

客户端发送小程序自定义事件

客户端发送小程序自定义事件步骤如下：

小程序注册事件。

// 第一个参数为自定义事件名，第二个参数是回调
my.on('nativeToTiny', (res) = >{
    my.showToast({
        type: 'none',
        content: JSON.stringify(res),
        duration: 3000,
        success: () = >{},
        fail: () = >{},
        complete: () = >{}
    });
})

客户端发送事件。

// 模拟发送的数据
JSONObject jo = new JSONObject();
jo.put("index", index);
AppManager appManager = RVProxy.get(AppManager.class);
if (null != appManager) {
    // 通过 AppManager 拿到当前运行的小程序实例
    App app = appManager.findAppByAppId("2018080616290001");
    if(null!=app){
        // 向小程序发送信息
        // 第一个参数为当前小程序活动页面，第二个为自定义的事件名，第三个参数为发送的数据
        MriverEngine.sendToRender(app.getActivePage(), "nativeToTiny", jo, null);
    }
}