自定义 API

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

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

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

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

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

  1. 客户端自定义 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);
          }
      
      }
      
  2. 客户端注册自定义 API。容器初始化完成后,调用注册方法即可完成自定义 API 注册。注意不要混淆类名。

    MriverEngine.registerBridge(CustomApiBridgeExtension.class);
  3. 小程序侧调用。代码示例如下:

    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。

    • 第三个参数为客户端的回调。

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

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

  1. 小程序注册事件。

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

    // 模拟发送的数据
    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);
        }
    }
阿里云首页 移动开发平台 mPaaS 相关技术圈