Flutter-HarmonyOS 跨平台应用演示

基于 Flutter for OpenHarmony 的跨平台应用示例项目，展示了 Flutter 组件在 HarmonyOS 平台上的实际应用。

项目概述

这是一个 Flutter-HarmonyOS 跨平台应用，通过 Flutter-OpenHarmony 集成，将 Flutter 应用嵌入到 HarmonyOS (OpenHarmony) 原生应用中。

• 平台: HarmonyOS SDK 5.1.0(18)
• 架构: Stage 模式应用
• 语言: ArkTS (OpenHarmony 扩展集 - .ets 文件)
• 构建系统: Hvigor (HarmonyOS 构建系统，集成 Flutter)
• 仓库: https://gitcode.com/pickstar/openharmony-flutter-demos.git

项目结构

my_cross_platform_app/
├── flutter/                     # Flutter 子项目
│   ├── lib/                     # Flutter 源码
│   └── test/                    # Flutter 测试
├── ohos/                        # HarmonyOS 子项目
│   ├── AppScope/                # 应用级配置
│   ├── entry/                   # 主应用模块
│   │   ├── src/
│   │   │   ├── main/ets/
│   │   │   │   ├── entryability/    # 应用入口
│   │   │   │   └── pages/           # UI 页面
│   │   │   └── ohosTest/            # Hypium 测试
│   │   └── resources/               # 模块资源
│   └── oh-package.json5            # 依赖配置
└── README.md                     # 项目说明

构建命令

构建项目

cd ohos
hvigorw --mode module -p product=default assembleHap

运行测试

# HarmonyOS 测试
cd ohos
hvigorw test

# Flutter 测试
cd flutter
flutter test

已完成的组件演示

按钮组件

组件	日期	功能	博客链接
TextButton	2026-01-13	文本按钮，扁平化设计，支持自定义样式	详情
OutlinedButton	2026-01-13	边框按钮，透明背景，适用于次级操作	详情
IconButton	2026-01-13	图标按钮，轻量级交互组件	详情
FloatingActionButton	2026-01-13	浮动操作按钮（FAB），支持多位置/尺寸/样式，带徽章	详情

输入组件

组件	日期	功能	博客链接
TextField	2026-01-13	文本输入框，支持多种输入类型、样式定制	详情
TextFormField	2026-01-13	表单输入框，内置验证器、样式装饰、表单状态管理	详情

文件说明

HarmonyOS 演示页面

• entry/src/main/ets/pages/*DemoPage.ets - 组件演示页面

测试用例

• entry/src/ohosTest/ets/test/*.test.ets - Hypium 测试用例

配置文件

• entry/src/main/resources/base/profile/main_pages.json - 路由配置
• entry/src/ohosTest/ets/test/List.test.ets - 测试套件入口

技术架构

Flutter 集成模式

1. EntryAbility (entry/src/main/ets/entryability/EntryAbility.ets)

   • 继承 @ohos/flutter_ohos 的 FlutterAbility
   • 重写 configureFlutterEngine() 注册插件
   • HarmonyOS 应用的入口点

2. FlutterPage (entry/src/main/ets/pages/Index.ets)

   • 包含嵌入 Flutter 内容的 FlutterPage 组件
   • 使用 LocalStorage 管理视图 ID
   • 通过 EventHub 处理返回按钮事件

3. 插件注册

   • GeneratedPluginRegistrant.ets 自动生成
   • 向 Flutter 引擎实例注册 Flutter 插件

核心组件

• FlutterEngine: Flutter 运行时核心引擎
• FlutterPage: 渲染 Flutter 内容的 UI 组件
• EventHub: 用于跨组件通信（如返回按钮事件）

开发规范

ArkTS 文件约定

• Ability 类: 使用 *Ability.ets 后缀，扩展相应的 Ability 基类
• 页面组件: 使用 @Entry 装饰器，实现 build() 方法
• 组件: 使用 @Component 装饰器
• 状态管理: 使用 @LocalStorageLink 进行本地存储状态管理

返回按钮处理

onBackPress(): boolean {
  this.context.eventHub.emit('EVENT_BACK_PRESS')
  return true  // 阻止默认行为
}

测试框架

使用 @ohos/hypium 框架：

• 测试文件位于 entry/src/ohosTest/ets/test/
• 测试运行器: OpenHarmonyTestRunner.ts
• 使用 describe, it, expect 组织测试
• 使用 hilog 进行日志记录

资源组织

• 字符串: resources/base/element/string.json
• 图标: resources/base/media/
• 配置特定: resources/profile/ 用于不同构建变体

配置信息

• 包名: com.example.my_cross_platform_app
• SDK 版本: 5.1.0(18)
• 运行时: HarmonyOS
• API 类型: stageMode

依赖项

• @ohos/hypium (1.0.6) - 测试框架
• @ohos/flutter_ohos - Flutter OpenHarmony 集成
• flutter-hvigor-plugin - 构建集成（通过 hvigorconfig.ts 注入）

相关链接

• Flutter for OpenHarmony 实战系列
• OpenHarmony 跨平台社区
• 项目仓库

许可证

本项目遵循 CC 4.0 BY-SA 许可协议。