接入 HarmonyOS NEXT

本文介绍如何将小程序组件接入到 HarmonyOS NEXT 客户端。您可以基于已有工程使用 ohpmrc 方式接入小程序 SDK 到客户端。

前置条件

添加小程序 SDK 前，请确保已经接入工程到 mPaaS。更多信息请参见 基于已有工程使用 ohpmrc 接入。

引入依赖

在项目的 .ohpmrc 中添加如下仓库。

@mpaas:registry=https://mpaas-ohpm.oss-cn-hangzhou.aliyuncs.com/meta

使用 ohpm install @mpaas/hrivermini 安装小程序的依赖。

添加 SDK

在 oh-package.json5 中配置所需依赖，具体版本号参考基于已有工程使用 ohpmrc 接入 中的添加 mPaaS 组件依赖。

{
  "license": "",
  "devDependencies": {},
  "author": "",
  "name": "entry",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": {
    "@mpaas/hrivermini": "0.0.2-beta" // 0.0.2-beta为具体版本号
  }
}

配置权限

在 module.json5 中配置所需权限。

"requestPermissions":[
  {
  "name" : "ohos.permission.GET_NETWORK_INFO",
  },
  {
  "name" : "ohos.permission.INTERNET",
  },
  {  // 根据需要，如果有使用到选择图片、保存图片到sdk等功能，需要添加
        "name": "ohos.permission.READ_MEDIA",
        "reason": "$string:internet_reason",
        "usedScene": {
        }
  },
  { // 根据需要，如果有使用到扫码功能，需要添加
        "name": "ohos.permission.CAMERA",
        "reason": "$string:internet_reason",
        "usedScene": {}
  },
  { // 根据需要，如果有使用到获取位置功能，需要添加
        "name": "ohos.permission.LOCATION",
        "reason": "$string:internet_reason",
        "usedScene": {
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:internet_reason",
        "usedScene": {
        }
  }
]

使用 SDK

初始化

在 mPaaS 框架初始化完成之后，初始化 HRiverMini。

HRiverMini.init()

mPaaS 框架初始化可参考 接入 mPaaS 能力，示例如下：

import AbilityStage from '@ohos.app.ability.AbilityStage';
import { MPFramework } from '@mpaas/framework';

export default class ModuleEntry extends AbilityStage {
  async onCreate() {
    MPFramework.create(this.context);
    
    MPFramework.instance.userId = 'MPTestCase'
  }
}

打开小程序

小程序的页面路由基于 Navigation，需要在 Navigation 页面的 aboutToAppear() 添加以下配置：

aboutToAppear() {
  HRiverMini.notifyNavigationCreate(this.context, this.pageInfos)
}

启动小程序 API：

let startParams = new Map<string, Object>() // 启动参数
HRiverMini.startApp("2023112713520001", startParams)

启动小程序并跳转到指定页面：

let startParams = new Map<string, Object>()
startParams.set("page", "/page/component/view/view");
HRiverMini.startApp("2020012000000001", startParams)

注册自定义 API

在 HRiverMini.init() 初始化之前调用以下 API：

HRiverMini.registerExtension(()=> {
      import('@mpaas/hriverminidemo/src/main/ets/component/CustomExtension')
      import('@mpaas/hriverminidemo/src/main/ets/component/CustomExtension1')
      import('@mpaas/hriverminidemo/src/main/ets/component/CustomExtension2')
    })

import 即动态引入自定义 API 的 Extension。

CustomExtension 的实现如下：

import { ApiBaseExtension,
  BridgeCallback,
  defineJSAPIClass, ExtensionParameter,
  MyExtHubContext,
  registerJSAPI, required } from '@mpaas/exthub'

@defineJSAPIClass(():ApiBaseExtension => {return new CustomExtension()})
export class CustomExtension extends ApiBaseExtension {
  /**
   * 自定义Api： customApi
   * @param param
   * @param context
   * @param callback
   */
  @registerJSAPI
  customApi(@required(ExtensionParameter.CallParameters) param: Record<string, Object>,
    @required(ExtensionParameter.MyExtHubContext) context: MyExtHubContext,
    @required(ExtensionParameter.BridgeCallback) callback: BridgeCallback) {
    // 参数从param读取
    // 上下文如页面context等从context中读取
    // 回调给小程序使用callback

    // 调用成功后回调具体数据
    callback.sendSuccessResponse({
      data: 'apiSuccess'
    })
  }

  /**
   * 自定义Api： customApi2
   * @param param
   * @param context
   * @param callback
   */
  @registerJSAPI
  customApi2(@required(ExtensionParameter.CallParameters) param: Record<string, Object>,
    @required(ExtensionParameter.MyExtHubContext) context: MyExtHubContext,
    @required(ExtensionParameter.BridgeCallback) callback: BridgeCallback) {
    // 失败的回调通知
    callback.sendErrorResponse(-1, "call failed msg")
  }
}

Native 通知小程序

import { EngineUtils, HRiverMiniEngine } from '@mpaas/hrivermini'

HRiverMiniEngine.sendToRender(EngineUtils.getPageFromContext(context)?.getRender() || null, 'event', {})

扫码预览/真机调试

方式一：直接调起扫码。

let startParams = new Map<string, Object>()
HRiverMini.scan(getContext(this), startParams)

方式二：通过其他扫码，打开扫码结果。

let startParams = new Map<string, Object>()
HRiverMini.scanByUri(scanResult, startParams) // scanResult为扫码结果的string

启动参数

当前版本组件的特殊说明

地图组件目前基于华为地图，支持的 API 包括 getCurrentLocation和moveToLocation，需要在华为地图官网申请使用。

当前版本不支持的功能

• 小程序更新接口

• 小程序自定义启动、导航栏

• 小程序右上角菜单扩展

• 权限管控配置

• 预置小程序

当前版本不支持的组件和 API

• 蓝牙

• 文件 API：压缩图片、保存文件、获取文件信息、获取文件列表、移除文件、删除文件

• 地图部分功能

• canvas2

• 直播

• 联系人

• 隐藏键盘

• websocket

• 加载字体