全部产品
云市场
云游戏

自定义 JSAPI

更新时间:2020-09-18 14:43:25

JavaScript API(JSAPI)是为 H5 应用提供原生能力的接口,您可以利用这些接口使用更多的原生能力和操控能力,提高 H5 应用的用户体验。

H5 容器组件提供以下能力:

  • 丰富的内置 JSAPI,实现例如页面 push、pop、标题设置等功能。更多信息查看 内置 JSAPI
  • 支持用户自定义 JSAPI 和插件功能,扩展业务需求。

本文介绍如何实现自定义 JSAPI 和插件功能。

关于此任务

自定义 JSAPI 插件具备以下特点:

  • 为了让各个业务更加灵活地接入 H5 容器,H5 容器提供一种可以给外部业务注册插件配置的机制。
  • 业务方使用这种方式注册自定义的外部插件,代码可以放在自己的 bundle 中,全过程不需要 H5 容器介入。使用插件配置的方式注册插件时,H5 容器只在页面调用的时候才初始化对象,并不会立即生成对象。
  • 实现插件和注册插件可以不在同一个 bundle 中,实现依赖解耦。您需要通过 H5Service 动态将插件注入容器。
说明
  • 必须在页面调用 JS 之前注入 JS,一般在静态链接的 Pipeline 中注入。如果过早注入,会出现容器的 bundle 还没加载好(h5service==null)的问题。
  • 如果注册的 bundle 不是静态链接,而是懒加载的 bundle 的话,会存在 metainfo 还没加载,JS 就要调用的问题。

前端页面调用 Native

  1. 通过 MPNebula 的注册 JSAPI 接口,注册 JSAPI。

    说明MyJSApiPlugin 的源码可以前往 代码示例 中查看。

    • 注册 JSAPI 接口如下:
      1. /**
      2. * 注册自定义 H5 插件(JSAPI)
      3. *
      4. * @param className 插件类名,需要全路径(package + class)
      5. * @param bundleName bundle 名(bundle 名可在 主 module/build/intermediates/bundle/META-INF/BUNDLE.MF 中查看,如果该插件写在 portal 工程中,则 bundleName 需填空字符串 "")
      6. * @param scope 范围,通常为 page
      7. * @param events 注册的事件
      8. */
      9. public static void registerH5Plugin(String className, String bundleName, String scope, String[] events)
    • 注册示例如下:
      1. MPNebula.registerH5Plugin(
      2. MyJSApiPlugin.class.getName(),
      3. BuildConfig.BUNDLE_NAME,
      4. "page",
      5. new String[]{"myapi1","myapi2",H5Plugin.CommonEvents.H5_PAGE_SHOULD_LOAD_URL}
      6. );
  2. 前端调用。

    通过以下方法使得前端调用自定义 JSAPI:将 event 参数修改成以上插件注册的事件。插件将通过 event.getParam() 获取 JS 的传值,从中解析出数据。

    1. AlipayJSBridge.call('myapi2', {
    2. param2: 'World'
    3. },
    4. function(result) {
    5. console.log(result);
    6. });

Native 调用前端页面

H5 容器也可以是 Native 主动调用页面。

以网络变化 JSAPI 为例,页面监听该事件,如下所示:

  1. 前端注册监听。
    1. document.addEventListener('h5NetworkChange',
    2. function(e) {
    3. alert("网络环境发生变化,可调用 getNetworkType 接口获取详细信息");
    4. },
    5. false);
  2. 客户端监听到网络发生变化时,向页面发送调用事件。
    1. JSONObject param = new JSONObject();
    2. // param 设置自定义的参数
    3. param.put("data", param);
    4. H5Page h5Page = h5Service.getTopH5Page();
    5. if (h5Page != null) {
    6. h5Page.getBridge().sendDataWarpToWeb("h5NetworkChange", param, null);
    7. }

使用 Inspect

使用 Chrome 的 inspect 工具,检查调用自定义的 JSAPI 是否有效:

  1. 将手机连接电脑,在电脑中打开 Chrome 浏览器,输入 chrome://inspect,进入调试页面。
  2. 使用 mPaaS demo 打开蚂蚁金服金融科技首页。此时,Chrome 的 inspect 页面会变成如下所示:

    说明:部分电脑打开 chrome://inspect 会白屏,需要升级到 Chrome 最新版本。

  3. 点击图中的 inspect,出现如下页面:

  4. 点击页面工具栏上的 Console 进入页面调试模式。接下来,您就可以如图例所示调用自己的 API 接口了。

相关链接