@tarojs/plugin-platform-harmony-cpp NPM

@tarojs/plugin-platform-harmony-cpp

快速开始

安装和使用

安装 harmony 插件

# 使用 npm 安装
$ npm i @tarojs/plugin-platform-harmony-cpp
# 使用 pnpm 安装
$ pnpm i @tarojs/plugin-platform-harmony-cpp

添加插件配置

import os from 'os'
import path from 'path'

const config = {
  // ...
  plugins: ['@tarojs/plugin-platform-harmony-cpp'],
  harmony: {
    // 当前仅支持使用 Vite 编译鸿蒙应用
    compiler: 'vite',
    // Note: 鸿蒙工程路径，可以参考 [鸿蒙应用创建导读](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V2/start-with-ets-stage-0000001477980905-V2) 创建
    projectPath: path.join(os.homedir(), 'projects/my-business-project'),
    // Taro 项目编译到对应鸿蒙模块名，默认为 entry
    hapName: 'entry',
  },
  // ...
}

编译项目

# 编译鸿蒙应用
$ taro build --type harmony_cpp
# 编译鸿蒙原生组件
$ taro build native-components --type harmony_cpp

如果需要编译鸿蒙应用，同时使用编译鸿蒙原生组件，可以在页面配置中添加 entryOption: false 表示该页面是组件，同时可以用过 componentName 指定组件导出名。

export default {
  navigationBarTitleText: 'Hello World',
+  componentName: 'MyComponent',
+  entryOption: false,
}

功能

使用公共依赖库

插件默认使用内置版本的公共依赖库，可以通过 useChoreLibrary 配置禁用或者配置指定版本依赖。

const config = {
  // ...
  plugins: [
    '@tarojs/plugin-platform-harmony-cpp', // useChoreLibrary: 'local'
    // ['@tarojs/plugin-platform-harmony-cpp', { useChoreLibrary: false }],
    // ['@tarojs/plugin-platform-harmony-cpp', { useChoreLibrary: '4.1.0-alpha.0' }],
  ],
  // ...
}

插件版本可以通过 ohPackage.dependencies 配置或者鸿蒙工程内 oh-package.json5 配置覆盖。

类型定义

需要在 Taro 项目的 types/global.d.ts 文件夹里添加对插件类型的引用

/// <reference types="@tarojs/taro" />
/// <reference path="../node_modules/@tarojs/plugin-platform-harmony-cpp/types/define.d.ts" />

项目集成

Taro 默认支持构建鸿蒙应用，同时也允许开发者灵活扩展功能。你可以在 Taro 项目中使用鸿蒙原生模块，也可以在鸿蒙项目中集成 Taro 模块。

在 Taro 中使用鸿蒙原生模块

与 Taro 在其他端类似，可以通过配置 usingComponents 来引入鸿蒙原生组件。

/** index.config.ts */
export default {
  usingComponents: {
    title: './path/to/title-component'
  }
}

/** index.ts */
import { View } from '@tarojs/components'

export default function Index () {
  return <View>
    <title title="Hello World!" />
  </View>
}

如果希望使用 Taro 构建的鸿蒙原生组件或者为原生组件提供类型提示，也可以通过 importNativeComponent 方法来引入。

/** title.ts */
import { View } from '@tarojs/components'

definePageConfig({
  entryOption: false,
  componentName: 'Title',
})

export default function Title ({ title = 'Hello World' }) {
  return <View>{title}</View>
}

// importNativeComponent(path, moduleName, componentName)
export const Title = importNativeComponent<typeof import('./title').default>('./title', 'title', 'Title')

/** index.ts */
import { View } from '@tarojs/components'
import { Title } from './title'

export default function Index () {
  return <View>
    <Title title="Hello World!" />
  </View>
}

在鸿蒙项目中集成 Taro 模块

在鸿蒙项目中可以通过页面或者组件的形式来接入 Taro 模块，但如果不是 Taro 创建的鸿蒙项目需要在入口处添加 Taro 相关的初始化方法：

import { context, Current } from "@taro-oh/library/src/main/ets/npm/@tarojs/runtime"
import { TaroWindowUtil } from "@taro-oh/library/src/main/ets/npm/@tarojs/runtime"

export default class EntryAbility extends UIAbility {
  ...
  onWindowStageCreate(stage: ohWindow.WindowStage) {
    context.resolver(this.context)
    TaroWindowUtil.setWindowStage(stage)

    stage.loadContent('home_page', (err, data) => {
      const windowClass = stage.getMainWindowSync()
      Current.uiContext = windowClass.getUIContext()
      windowClass.setWindowLayoutFullScreen(true)
    })
  }
}

更多配置可以参考项目生成的 app.ts 文件改造。

通过页面接入需要在模块配置文件 module.json5 中配置 pages 参数，如果是组件模式，可以参考原生 ets 组件方法引入。

import { Title } from './components/title'

@Builder
function render () {
  Title({
    props: {
      title: 'Hello World!'
    }
  })
}

定制 Taro 运行时

与其他端类似，开发者同样可以通过继承 HarmonyCPP 实例来修改 Taro 的默认行为，包括新增运行时代码等。

import { HarmonyCPP } from '@tarojs/plugin-platform-harmony-cpp'

export default class MyTaro extends HarmonyCPP {
  // ...
  constructor () {
    super()
    // ...
    if (typeof this.runtimePath === 'string') {
      this.runtimePath = [this.runtimePath, path.resolve(__dirname, 'my-runtime')] // Note: 如果有需要可以覆盖 runtime 禁用 taro 默认 API 行为
    }
  }
}

如果不想构建端应用插件，也可以通过配置 copy 将自定义 ets 代码注入到项目中。

通过注入运行时，开发者可以监听 Taro 抛出的 __taroPluginEtsMethodsTrigger 事件，可以通过监听事件实现获取开发用户调用 Taro 方法的参数，或者修改 Taro 的默认行为。

import { eventCenter } from '@tarojs/runtime'
import { IEtsMethodsOptions } from '@tarojs/plugin-platform-harmony-cpp/dist/runtime/runtime-harmony'

/**
 * interface IEtsMethodsOptions {
 *   methodName?: string
 *   name?: string
 *   scope?: string
 *   type?: string
 *   args?: TaroAny[]
 *   successHandler?: (...args: TaroAny[]) => void
 *   errorHandler?: (...args: TaroAny[]) => void
 *   onInit?: (obj: TaroAny) => void
 * }
 */

eventCenter?.on('__taroPluginEtsMethodsTrigger', (option: IEtsMethodsOptions) => {
  switch (option.scope) {
    case 'route':
      // ...
      break
    default:
      break
  }
})

未实现的 API 可以通过监听 __taroNotSupport 事件自定义实现。

常见问题

ERROR: Failed to get ModuleInfo properties 'meta.pkgPath'

本地可能存在部分混淆导致 IDE 无法正确解析依赖，需要检查 build-profile.json5、obfuscation-rules.txt 等文件中是否开启混淆配置，需要关闭后清理 IDE 缓存重新编译。

- -enable-property-obfuscation
- -enable-toplevel-obfuscation
- -enable-filename-obfuscation
- -enable-export-obfuscation

ERROR: Cannot resolved import statement

本地执行 library 编译时，启用 useNormalizedOHMUrl 配置会导致外部依赖无法解析，建议在 library 模块中使用 useNormalizedOHMUrl: false 或者移除该配置。

ERROR: Duplicated files found in module default

不使用核心库切换到使用核心库时可能会出现该问题，需要清理 build-profile.json5 文件中关于 so 包的配置项。

{
  "apiType": "stageMode",
  "buildOption": {
-    "externalNativeOptions": {
-      "path": "./src/main/cpp/CMakeLists.txt",
-      "arguments": "-DCMAKE_JOB_POOL_COMPILE:STRING=compile -DCMAKE_JOB_POOL_LINK:STRING=link -DCMAKE_JOB_POOLS:STRING=compile=8;link=8",
-      "cppFlags": "",
-      "abiFilters": [
-        "arm64-v8a"
-      ]
-    }
  },
  ...
}

taro harmony