构建第一个仓颉与 ArkTS 混合鸿蒙应用

cjHybridHarmony/
├── 📁 AppScope/                    # 应用级配置
│   ├── 📁 resources/              # 全局资源
│   │   └── 📁 base/
│   │       ├── 📁 element/        # 字符串、颜色等元素
│   │       └── 📁 media/          # 图片、音频等媒体
│   └── 📄 app.json5               # 应用全局配置
├── 📁 entry/                       # 主模块
│   ├── 📁 har/                    # HAR依赖包
│   │   └── 📄 CJHyAPIRegister-v1.0.1.har
│   ├── 📁 src/                    # 源代码目录
│   │   ├── 📁 main/               # 主要源码
│   │   │   ├── 📁 cangjie/        # 仓颉源码目录
│   │   │   ├── 📁 ets/            # ArkTS源码目录
│   │   │   ├── 📁 resources/      # 模块资源
│   │   │   └── 📄 module.json5    # 模块配置
│   │   ├── 📁 mock/               # Mock数据
│   │   ├── 📁 ohosTest/           # 单元测试
│   │   └── 📁 test/               # 其他测试
│   └── 📄 build-profile.json5     # 模块构建配置
├── 📁 hvigor/                      # 构建工具
│   ├── 📄 cangjie-build-support-3.1.132.tgz
│   └── 📄 hvigor-config.json5
└── 📄 build-profile.json5         # 应用构建配置

// Index.ets - 首页（纯ArkTS页面）
import { router } from'@kit.ArkUI';
import { BusinessError } from'@kit.BasicServicesKit';

@Entry
@Component
struct Index {
@State message: string = 'Hello World'

  build() {
    Row() {
      Column() {
        // 主标题
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 20 })

        // 副标题
        Text('这是一个仓颉与ArkTS混合应用')
          .fontSize(16)
          .fontColor('#666666')
          .margin({ bottom: 40 })

        // 跳转按钮
        Button() {
          Text('前往仓颉页面')
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .fontColor(Color.White)
        }
        .type(ButtonType.Capsule)
        .backgroundColor('#0D9FFB')
        .width('60%')
        .height(50)
        .onClick(() => {
          console.info('点击了跳转按钮')
          // 页面跳转逻辑将在后续步骤中实现
        })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

Row (水平容器)
└── Column (垂直容器)
    ├── Text (主标题)
    ├── Text (副标题)
    └── Button (跳转按钮)

ArkTS页面 (@Entry)
├── 页面生命周期管理
├── 路由导航处理
└── 仓颉组件容器
    └── 仓颉UI组件 (@HybridComponentEntry)
        ├── 业务逻辑处理
        ├── 数据计算
        └── UI渲染

cjHybridHarmony
├── 📁 AppScope
│   ├── 📁 resources
│   │   └── 📁 base
│   │       ├── 📁 element
│   │       └── 📁 media
│   └── 📄 app.json5
├── 📁 entry
│   ├── 📁 har
│   │   ├── 📄 CJHyAPIRegister-v1.0.1.har
│   │   └── 📄 CJHybridView-v1.0.4.har
│   ├── 📁 src
│   │   ├── 📁 main
│   │   │   ├── 📁 cangjie
│   │   │   ├── 📁 ets
│   │   │   ├── 📁 resources
│   │   │   └── 📄 module.json5
│   │   ├── 📁 mock
│   │   │   └── 📄 mock-config.json5
│   │   ├── 📁 ohosTest
│   │   │   ├── 📁 ets
│   │   │   └── 📄 module.json5
│   │   └── 📁 test
│   │       ├── 📄 List.test.ets
│   │       └── 📄 LocalUnit.test.ets
│   ├── 📄 .gitignore
│   ├── 📄 build-profile.json5
│   ├── 📄 hvigorfile.ts
│   ├── 📄 obfuscation-rules.txt
│   ├── 📄 oh-package-lock.json5
│   └── 📄 oh-package.json5
├── 📁 hvigor
│   ├── 📄 cangjie-build-support-3.1.132.tgz
│   └── 📄 hvigor-config.json5
├── 📄 .gitignore
├── 📄 build-profile.json5
├── 📄 code-linter.json5
├── 📄 hvigorfile.ts
├── 📄 oh-package-lock.json5
└── 📄 oh-package.json5

  "dependencies": {
    "libark_interop_loader.so": "file:./src/main/cangjie/loader",
    "cjhyapiregister": "file:./har/CJHyAPIRegister-v1.0.1.har",
    "cjhybridview": "file:./har/CJHybridView-v1.0.4.har"
  }

// second.cj
package ohos_app_cangjie_entry

import ohos.base.*
import ohos.component.*
import ohos.hybrid_base.*
import ohos.state_macro_manage.*
import ohos.state_manage.*
import cj_res_entry.app

@HybridComponentEntry
@Component
class Second {
    @State var msg: String = "Hello Cangjie"

    public func build() {
        Row() {
            Column() {
                Text(this.msg)
                    .fontSize(50)
                    .fontWeight(FontWeight.Bold)

                Button() {
                    Text("Back")
                        .fontSize(30)
                        .fontWeight(FontWeight.Bold)
                }
                .shape(ShapeType.Capsule)
                .margin(top: 20)
                .backgroundColor(Color(0x0D9FFB))
                .width(40.percent)
                .height(5.percent)
            }
            .width(100.percent)
        }
        .height(100.percent)
    }
}

import { CJHybridComponentV2 } from 'cjhybridview';
import { register_hsp_api } from 'cjhyapiregister';

register_hsp_api()

@Entry
@Component
struct Second {
  @State message: string = 'Hello World';

build() {
    Column() {
      CJHybridComponentV2({
        library: 'ohos_app_cangjie_entry',
        component: 'Second'
      })
    }
    .height('100%')
    .width('100%')
  }
}

// Index.ets - 首页（支持页面跳转）
import { router } from'@kit.ArkUI';
import { BusinessError } from'@kit.BasicServicesKit';

@Entry
@Component
struct Index {
@State message: string = 'Hello World'

  build() {
    Row() {
      Column() {
        // 主标题
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 20 })

        // 副标题
        Text('这是一个仓颉与ArkTS混合应用')
          .fontSize(16)
          .fontColor('#666666')
          .margin({ bottom: 40 })

        // 跳转按钮
        Button() {
          Text('前往仓颉页面')
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .fontColor(Color.White)
        }
        .type(ButtonType.Capsule)
        .backgroundColor('#0D9FFB')
        .width('60%')
        .height(50)
        .onClick(() => {
          console.info('点击了跳转按钮，准备跳转到第二页')

          // 执行页面跳转
          router.pushUrl({
            url: 'pages/second'
          }).then(() => {
            console.info('成功跳转到第二页')
          }).catch((err: BusinessError) => {
            console.error(`页面跳转失败: Code=${err.code}, Message=${err.message}`)
          })
        })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

ArkTS页面
├── 路由管理 (router.back())
└── 函数注册
    ↓ (通过互操作传递)
仓颉组件
├── 接收ArkTS函数
└── 调用路由返回

// second.cj - 仓颉页面组件（支持互操作）
package ohos_app_cangjie_entry

// 导入必要的模块
import ohos.base.*
import ohos.component.*
import ohos.hybrid_base.*
import ohos.state_macro_manage.*
import ohos.state_manage.*
import cj_res_entry.app
import ohos.ark_interop.*
import ohos.ark_interop_macro.*
import std.collection.*

// ==================== 互操作函数管理 ====================

// 全局HashMap，用于保存ArkTS注册的回调函数
// 简化演示：假设所有回调函数均为无参数、无返回值
public let globalJSFunction = HashMap<String, () -> Unit>()

// 注册ArkTS函数到仓颉侧
@Interop[ArkTS]
public func registerJSFunc(name: String, fn: () -> Unit): Unit {
    // 检查函数是否已经注册
    if (globalJSFunction.contains(name)) {
        AppLog.error("函数注册失败: 函数 ${name} 已存在")
        return
    }
    // 保存函数到HashMap中
    globalJSFunction.put(name, fn)
    AppLog.info("成功注册函数: ${name}")
}

// 注销ArkTS函数
@Interop[ArkTS]
public func unregisterJSFunc(name: String): Unit {
    globalJSFunction.remove(name)
    AppLog.info("成功注销函数: ${name}")
}

// ==================== 仓颉页面组件 ====================

@HybridComponentEntry
@Component
class Second {
    @State var msg: String = "Hello Cangjie"

    public func build() {
        Row() {
            Column() {
                // 页面标题
                Text(this.msg)
                    .fontSize(40)
                    .fontWeight(FontWeight.Bold)
                    .margin({ bottom: 20 })

                // 描述文字
                Text("这是仓颉组件页面")
                    .fontSize(16)
                    .fontColor('#666666')
                    .margin({ bottom: 40 })

                // 返回按钮
                Button() {
                    Text("返回上一页")
                        .fontSize(18)
                        .fontWeight(FontWeight.Bold)
                        .fontColor(Color.White)
                }
                .shape(ShapeType.Capsule)
                .backgroundColor(Color(0x0D9FFB))
                .width(60.percent)
                .height(50)
                .margin({ top: 20 })
                .onClick {
                    AppLog.info("点击了返回按钮")

                    // 尝试获取注册的回调函数
                    let optFn = globalJSFunction.get("SecondPageRouterBack")
                    if (let Some(fn) <- optFn) {
                        AppLog.info("调用ArkTS回调函数执行页面返回")
                        fn() // 调用ArkTS注册的回调函数
                    } else {
                        AppLog.error("页面返回失败: 回调函数不存在")
                    }
                }
            }
            .width(100.percent)
            .height(100.percent)
            .justifyContent(FlexAlign.Center)
        }
        .height(100.percent)
        .backgroundColor('#F5F5F5')
    }
}

entry/
└── src/
    └── main/
        ├── cangjie/
        │   ├── ark_interop_api/          # 🆕 自动生成的接口目录
        │   │   ├── ark_interop_api.d.ts  # TypeScript接口声明文件
        │   │   └── oh-package.json5      # 包配置文件
        │   ├── loader/                   # 互操作加载器
        │   ├── second.cj                 # 仓颉组件文件
        │   ├── cjpm.toml                 # 仓颉包管理配置
        │   └── ...
        └── ets/
            └── pages/
                ├── Index.ets             # ArkTS首页
                └── Second.ets            # ArkTS混合页面

// second.ets - ArkTS页面容器（支持仓颉组件嵌入）
import { CJHybridComponentV2 } from'cjhybridview';
import { register_hsp_api } from'cjhyapiregister';

// 导入页面路由模块
import { router } from'@kit.ArkUI';
import { BusinessError } from'@kit.BasicServicesKit';

// 导入仓颉与ArkTS互操作库
import { requireCJLib } from'libark_interop_loader.so';
import { CustomLib } from'libark_interop_api.so';

// 注册HSP API
register_hsp_api()

// 加载仓颉库
// 注意：仓颉以package为编译单元，每个package编译为对应的so文件
let cjlib = requireCJLib("libohos_app_cangjie_entry.so") as CustomLib

@Entry
@Component
struct Second {

// ==================== 页面生命周期 ====================

  aboutToAppear(): void {
    console.info('Second页面即将出现，注册回调函数')

    // 注册页面返回回调函数到仓颉侧
    cjlib.registerJSFunc('SecondPageRouterBack', () => {
      try {
        console.info('执行页面返回操作')
        router.back() // 返回上一页
        console.info('成功返回到首页')
      } catch (err) {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`页面返回失败: Code=${code}, Message=${message}`)
      }
    })
  }

  aboutToDisappear(): void {
    console.info('Second页面即将销毁，注销回调函数')

    // 在页面销毁前注销回调函数，避免内存泄漏
    cjlib.unregisterJSFunc('SecondPageRouterBack')
  }

// ==================== 页面构建 ====================

  build() {
    Row() {
      // 嵌入仓颉页面组件
      CJHybridComponentV2({
        library: "ohos_app_cangjie_entry", // 仓颉组件所在的package名
        component: "Second"                // 仓颉组件的class名
      })
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#FFFFFF')
  }
}

┌─────────────────┐    router.pushUrl()    ┌──────────────────┐
│   Index.ets     │ ──────────────────────→ │   Second.ets     │
│  (ArkTS首页)    │                         │  (ArkTS容器)     │
└─────────────────┘                         └──────────────────┘
                                                      │
                                                      │ 嵌入组件
                                                      ↓
                                            ┌──────────────────┐
                                            │   Second.cj      │
                                            │  (仓颉组件)      │
                                            └──────────────────┘
                                                      │
                                                      │ 回调函数
                                                      ↓
                                            ┌──────────────────┐
                                            │  router.back()   │
                                            │  (返回首页)      │
                                            └──────────────────┘

"buildOption": { // 配置项目在构建过程中使用的相关配置
  "cangjieOptions": { // 仓颉相关配置
    "path": "./src/main/cangjie/cjpm.toml", // cjpm配置文件路径，提供仓颉构建配置
    "abiFilters": ["arm64-v8a", "x86_64"] // 自定义仓颉编译架构，默认编译架构为arm64-v8a
  }
}

# 1. 清理项目
File > Clean Project

# 2. 重新同步依赖
File > Sync and Refresh Project

# 3. 检查 oh-package.json5 中的依赖配置

"cangjieOptions": {
  "abiFilters": ["arm64-v8a", "x86_64"]
}