@tarojs/plugin-platform-harmony-cpp 4.0.8-beta.3

package/README.md

@@ -0,0 +1,270 @@
+# @tarojs/plugin-platform-harmony-cpp
+
+## 快速开始
+
+### 安装和使用
+
+- 安装 harmony 插件
+
+  ```shell
+  # 使用 npm 安装
+  $ npm i @tarojs/plugin-platform-harmony-cpp
+  # 使用 pnpm 安装
+  $ pnpm i @tarojs/plugin-platform-harmony-cpp
+  ```
+
+- 添加插件配置
+
+  ```ts
+  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',
+    },
+    // ...
+  }
+  ```
+
+### 编译项目
+
+```sh
+# 编译鸿蒙应用
+$ taro build --type harmony_cpp
+# 编译鸿蒙原生组件
+$ taro build native-components --type harmony_cpp
+```
+
+如果需要编译鸿蒙应用，同时使用编译鸿蒙原生组件，可以在页面配置中添加 `entryOption: false` 表示该页面是组件，同时可以用过 `componentName` 指定组件导出名。
+
+```diff
+export default {
+  navigationBarTitleText: 'Hello World',
++  componentName: 'MyComponent',
++  entryOption: false,
+}
+```
+
+## 功能
+
+### 使用公共依赖库
+
+插件默认使用内置版本的公共依赖库，可以通过 useChoreLibrary 配置禁用或者配置指定版本依赖。
+
+```ts
+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 文件夹里添加对插件类型的引用
+
+```ts
+/// <reference types="@tarojs/taro" />
+/// <reference path="../node_modules/@tarojs/plugin-platform-harmony-cpp/types/define.d.ts" />
+
+```
+
+## 项目集成
+
+Taro 默认支持构建鸿蒙应用，同时也允许开发者灵活扩展功能。你可以在 Taro 项目中使用鸿蒙原生模块，也可以在鸿蒙项目中集成 Taro 模块。
+
+### 在 Taro 中使用鸿蒙原生模块
+
+与 Taro 在其他端类似，可以通过配置 `usingComponents` 来引入鸿蒙原生组件。
+
+```ts
+/** 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` 方法来引入。
+
+```ts
+/** 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 相关的初始化方法：
+
+```ts
+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 组件方法引入。
+
+```plain
+import { Title } from './components/title'
+
+@Builder
+function render () {
+  Title({
+    props: {
+      title: 'Hello World!'
+    }
+  })
+}
+```
+
+### 定制 Taro 运行时
+
+与其他端类似，开发者同样可以通过继承 HarmonyCPP 实例来修改 Taro 的默认行为，包括新增运行时代码等。
+
+```ts
+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 的默认行为。
+
+```ts
+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 缓存重新编译。
+
+```diff
+- -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 包的配置项。
+
+```diff
+{
+  "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"
+-      ]
+-    }
+  },
+  ...
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { HarmonyOS_ArkTS } from '@tarojs/plugin-platform-harmony-ets/dist';
+import { IPluginContext, TConfig } from '@tarojs/service';
+import { IHarmonyConfig } from '@tarojs/taro/types/compile';
+
+declare class Harmony extends HarmonyOS_ArkTS {
+    option: IOptions;
+    platform: string;
+    runtimePath: string;
+    useETS: boolean;
+    useJSON5: boolean;
+    get context(): IPluginContext;
+    constructor(ctx: IPluginContext, config: TConfig, option: IOptions);
+    get harmonyPluginPath(): string;
+    get harmonyCppPluginPath(): string;
+    get apiLibrary(): string;
+    get componentLibrary(): string;
+    get runtimeLibrary(): string;
+    get runtimeFrameworkLibrary(): string;
+    get runtimeFrameworkReconciler(): string;
+    modifyPageConfig(): void;
+    updateModulePackage(outputRoot: string, ohPackage?: Exclude<IHarmonyConfig['ohPackage'], undefined>, ohpm?: string): void;
+}
+
+interface IOptions {
+    useConfigName?: string;
+    /** @default "local" */
+    useChoreLibrary?: 'local' | 'remote' | false | string;
+}
+declare const _default: (ctx: IPluginContext, options?: IOptions) => void;
+
+export { Harmony as HarmonyCPP, _default as default };
+export type { IOptions };