H5 包壳小程序介绍

如需开发 H5 包壳小程序，请联系小程序团队获得相关授权。

使用限制

基础库从 3.1.0 或更高版本支持。

原理说明

1. H5 包壳小程序技术本质：hybrid 混合开发技术

简单来说，就是 H5 页面运行在小程序容器中，通过注入 bridge，使得 H5 页面能够与小程序容器进行通信，从而可以调用小程序容器提供的一些能力，例如：获取小程序平台的 uid、获取系统信息等。

2. bridge 是如何注入的？

1. bridge 实际是一段 js 代码，封装了与小程序容器建立通信和基础 API 调用的能力。

2. bridge 的引用和普通 js 脚本一致，可以通过 script 标签进行引入，在需要使用小程序 API 的 HTML 中写入这样的标签：

   <script src="https://app-oss.byte-app.com/common/js/byteh5bridge.aio.min.js"></script>

3. bridge 加载成功后，会在 window 上挂载 @tiranssion/byteh5bridge，因此目前可以通过判定 window 上是否有 @transsion/byteh5bridge 属性来判定 bridge 是否加载成功。

   if (typeof window['@transsion/byteh5bridge'] != 'undefined') {
     console.log('bridge file loaded');
   }

4. bridge 加载成功后，还需要判断当前是否运行在 MiniShell（包壳小程序运行时） 中 可以通过 window.dltms.isMiniShellGame()方法判断 当运行在 MiniShell 中时，可以用该方法进行判断，如果是运行在 MiniShell 环境中，则会返回 true，注意判断条件

   if (window.dltms && window.dltms.isMiniShellGame()) {
     console.log('run in minishell');
   }

使用步骤

1. 在页面中引入 bridge JS 文件

<script src="https://app-oss.byte-app.com/common/js/byteh5bridge.aio.min.js"></script>

2. 调用方式说明

在 H5 包壳小程序中，调用形式都是固定的，通过 callApi(methodName, params) 方法

callApi 参数说明

参数名	类型	是否必传	说明
methodName	String	是	调用的方法名
params	Object	否	调用参数

params 参数说明 success、fail、complete 为通用参数

参数名	类型	是否必传	说明
success	Function	否	调用结果成功回调，调用成功后会执行
fail	Function	否	调用结果失败回调，调用失败后会执行
complete	Function	否	调用结果完成回调，调用完成后会执行，不论成功与否
其他参数	Any	否	基于不同的调用方法，部分需要额外的参数，相关说明会在具体 API 使用文档中标注。

调用形式

const dlt = window['@transsion/byteh5bridge'];
const canCallDlt = dlt && window.dltms && window.dltms.isMiniShellGame();

if (canCallDlt) {
  //  methodName 即为要调用的 API 名称
  dlt.callApi(`${methodName}`, {
    paramA: 'xxx', // 具体参数
    success: (res) => {
      console.log('success: ', res);
    },
    fail: (res) => {
      console.log('fail: ', res);
    },
    complete: (res) => {
      console.log('complete: ', res);
    },
  });
}

通用返回结果说明

属性	类型	说明
success	String	描述接口调用成功或失败。"true": 成功；"false":失败
errMsg	String	success 为 “false” 时才会有该字段
其他参数	Any	基于不同的 API，部分方法回返回额外字段，相关说明会在具体 API 使用文档中标注。

备注： 接口调用成功时，会在 success 回调函数中返回对应的其他参数数据；失败时，会在 fail 回调函数中返回，结果和通用返回结果一致。 complete 回调函数，在方法调用成功时，返回内容和 success 回调函数一致，失败时返回内容和 fail 回调函数一致。