react-native-mobilex 开发文档

react-native-mobilex

前提

鸿蒙OS请先按照鸿蒙RN文档将RN工程鸿蒙化后再进行以下步骤。

安装

npm install react-native-mobilex.tgz

本工程依赖 react-native-webview, 运行以下命令进行安装

npm install react-native-webview

鸿蒙OS还需要安装鸿蒙适配 webview

npm install @react-native-oh-tpl/react-native-webview

配置鸿蒙原生工程

鸿蒙RN暂不支持 autolink，需要手动进行配置。

若事先进行过react-native-webview适配，则可忽略以下步骤中 webview 的相关配置。

在 harmony/entry/oh-package.json5 中添加依赖：

"dependencies": {
    ......
    "react-native-mobilex": "file:../../node_modules/react-native-mobilex/harmony/rn_mobilex.har",
    "@react-native-oh-tpl/react-native-webview": "file:../../node_modules/@react-native-oh-tpl/react-native-webview/harmony/rn_webview.har",
},

在 harmony/entry/src/main/cpp/CMakeLists.txt中添加模块：

add_subdirectory("${OH_MODULE_DIR}/react-native-mobilex/src/main/cpp" ./mobilex)
add_subdirectory("${OH_MODULE_DIR}/@react-native-oh-tpl/react-native-webview/src/main/cpp" ./webview)

......

target_link_libraries(rnoh_app PUBLIC rnoh_mobilex)
target_link_libraries(rnoh_app PUBLIC rnoh_webview)

在 harmony/entry/src/main/cpp/PackageProvider.cpp 中应用模块

......
#include "MobileXPackage.h"
#include "WebViewPackage.h"


std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        ......
        std::make_shared<MobileXPackage>(ctx),
        std::make_shared<WebViewPackage>(ctx),
    };
}

在 harmony/entry/src/main/etc/RNPackagesFactory.ets 中应用模块

......
import { MobileXPackage }  from 'react-native-mobilex/ts'
import { WebViewPackage } from '@react-native-oh-tpl/react-native-webview/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
    return [
        ......
        new MobileXPackage(ctx),
        new WebViewPackage(ctx),
    ];
}

在 harmony/entry/src/main/ets/pages/Index.ets 中增加 webview 配置

......
import { WebView, WEB_VIEW } from "@react-native-oh-tpl/react-native-webview"

@Builder
export function buildCustomRNComponent(ctx: ComponentBuilderContext) {
    if (ctx.componentName === WEB_VIEW) { // 注册 webview 原生组件
        WebView({
            ctx: ctx.rnComponentContext,
            tag: ctx.tag
        });
    }
}

struct Index {
    build() {
        Column() {
            ......
            RNApp({
                rnInstanceConfig: {
                    ......
                    arkTsComponentNames: [
                        WEB_VIEW //components 添加 webview
                    ]
                },
                ......
            })
        }
    }   
}

在 harmony/entry/src/main/ets/entryability/EntryAbility.ets 中完善生命周期调用，避免部分 RN 方法结果错误

  onWindowStageCreate(windowStage: window.WindowStage): void {
    super.onWindowStageCreate(windowStage); // 添加 super 方法
    ...
  }

  onForeground(): void {
    super.onForeground() // 添加 super 方法
    ...
  }

  onBackground(): void {
    super.onBackground() // 添加 super 方法
    ...
  }

配置完成后同步并重新运行整个工程即可。

配置 Android 原生工程

Android 最低支持版本为 7.0（API 24）。

修改 Android 工程根目录下的 settings.gradle，添加以下脚本，使其可正常编译 sdk 使用到的依赖


apply from: file("../node_modules/react-native-mobilex/android/mobilex_module.gradle"); applyMobileXSettingsGradle(settings)

修改 Android 工程下 app/src/main/java/<包名>/MainActivity.java，添加以下代码

import com.supermap.rnmobilex.MobileXResource;

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  MobileXResource.onActivityResult(requestCode, resultCode, data);

使用

使用前请先激活，激活时保持网络畅通。

import {LicenseModule, RTNCore} from 'react-native-mobilex'


async function init() {
  RTNCore.initEnvironment(9988) // 初始化并指定本地服务端口号

  const license = await RTNCore.getLicenseInfo()
  if (!license.license?.valid) {
    const serial = 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX' //序列号
    const query = await RTNCore.queryLicense(serial)
    const modules = query.modules.map(item => item.module)
    const result = await RTNCore.activateLicense(serial, modules)
    if (result.success) {
      console.log("激活成功")
    } else {
      console.warn("激活失败")
    }
  } else {
    console.log("已激活")
  }
}

激活后通过 MapView 渲染, 修改 APP.tsx 如下, 打开 app 后显示地图

App.tsx

import { MapController, MapView, RTNCore } from 'react-native-mobilex'
import { useEffect, useState } from 'react'

export default function SimpleApp() {
  const [valid, setValid] = useState(false)

  useEffect(() => {
    init()
  }, [])

  async function init() {
    RTNCore.initEnvironment(9988) // 初始化并指定本地服务端口号

    const license = await RTNCore.getLicenseInfo()
    if (!license.license?.valid) {
      const serial = 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX' //序列号
      const query = await RTNCore.queryLicense(serial)
      const result = await RTNCore.activateLicense(
        serial,
        query.modules.map(item => item.module),
      )
      if (result.success) {
        console.log('激活成功')
        setValid(true)
      } else {
        console.warn('激活失败')
      }
    } else {
      console.log('已激活')
      setValid(true)
    }
  }

  async function onMapLoad(controller: MapController) {
    // 添加数据源：高德 墨卡托 gcj02
    const sourceId = await controller.datasources.add({
      type: 'raster',
      name: 'gaode',
      data: {
        tiles: [
          'http://wprd04.is.autonavi.com/appmaptile?x={x}&y={y}&z={z}&lang=zh_cn&size=1&scl=2&style=7',
        ],
        tileSize: 256,
      },
    })

    if (!sourceId) return

    // 设置地图坐标系
    await controller.map.setCRS('WebMercator', 'GCJ02')

    // 添加底图
    await controller.baseLayers.add({
      type: 'image',
      sourceId: sourceId,
      name: 'gaode_layer',
    })

    // 定位
    await controller.map.flyTo({
      center: { x: 108, y: 30 },
      scale: 1 / 30000000,
    })
  }

  if (!valid) return null

  return <MapView onInited={onMapLoad} />
}

功能模块与许可要求

以下要求适用于通过 RN Controller 调用功能。多个许可类别之间是“同时需要”的关系。许可还须满足设备绑定和有效期要求。

功能入口	所需许可
`MapView` / `MapController` 初始化	核心
`SceneView` / `SceneController` 初始化	核心 + 三维场景
二维基础模块：`map`、`baseLayers`、`datasources`、`layers`、`rasterTileProvider`、`symbolLibrary`、`dataConversion`、`theme`、`recordset`、`geometry`、`cacheService`、`trackingLayer`、`navigation`、`callouts`、`crsTranslator`	核心；通过 SceneController 使用时还需三维场景
`geometrist`	核心 + 数据分析；通过 SceneController 使用时还需三维场景
三维基础模块：`scene`、`camera`、`entityGraphicLayers`、`primitiveGraphicLayers`、`s3mLayers`、`animation`、`measure`、`magnifier`、`coordTrans`、`fileConverter`	核心 + 三维场景
`analysis`、`geometrist3D`	核心 + 三维场景 + 三维空间分析
`particleLayers`、`scanEffect`	核心 + 三维场景 + 三维特效

许可不足导致控件初始化失败时，通过 onInitError 处理；Controller 异步功能调用失败时，应捕获返回的 Promise 错误。查询结果中的剩余名额用于选择激活模块，不代表本机已取得该模块的有效许可。

切换已保存的许可

文件许可和在线许可可以同时保留。调用 RTNCore.setLicenseType('file') 或 RTNCore.setLicenseType('web')，可切换当前使用的许可。目标许可需通过本机有效性校验；成功返回 true，并持久化选择、通知 Controller 刷新授权。失败返回 false，保持原选择。

const switched = await RTNCore.setLicenseType('file');
if (switched) {
  const info = await RTNCore.getLicenseInfo();
  console.log(info.license?.type); // 'file'
}

切换不重新激活、不归还在线名额，也不合并模块。导入文件和在线激活成功后仍自动选用对应许可。建议在创建地图或场景前完成切换；已有 Controller 的后续功能调用按刷新后的许可校验，切换不会自动销毁或重建已显示的地图对象。