Flutter跨平台开发鸿蒙化规范指南

本文介绍了Flutter OpenHarmony化开发的工程目录规范和插件项目更新要求。

david

796人浏览 · 2025-12-23 22:51:11

david · 2025-12-23 22:51:11 发布

1. 规范介绍

Flutter OpenHarmony化开发过程中，遵循统一的项目结构和插件规范是确保开发效率和项目可维护性的关键。本指南详细介绍了Flutter OpenHarmony化工程的目录结构规范和插件项目结构更新要求，帮助开发者构建符合官方标准的跨平台应用。

2. Flutter OpenHarmony化工程目录结构

2.1 关键文件说明

Flutter OpenHarmony化工程包含以下核心配置文件和代码文件：

2.1.1 配置文件

ohos/
├── AppScope/
│   └── app.json5                # 应用全局配置信息（包名、版本号等）
├── build-profile.json5          # 项目级构建配置
├── oh-package.json5             # 项目级依赖配置
└── entry/
    ├── build-profile.json5      # 模块级构建配置
    ├── oh-package.json5         # 模块级依赖配置
    └── src/main/
        └── module.json5         # 模块基本配置（名称、类型、支持设备等）

2.1.2 代码文件

ohos/entry/src/main/
├── entryability/
│   └── EntryAbility.ets         # 应用入口文件
└── pages/
    └── Index.ets                # 应用加载的第一个页面

2.2 已过时可删除的目录和文件

以下目录和文件已过时，可以安全删除：

# 直接从flutter_flutter模板复制的HAR产物
delete ohos/har/har_product/*

# 旧版HAR文件，已被ohos/har/flutter.har替代
delete ohos/har/flutter_embedding.har

# ICU数据文件，直接从flutter_flutter模板复制
delete ohos/dta/icudtl.dat

3. Flutter插件项目结构更新

3.1 更新内容概述

为了更好地支持OpenHarmony生态，Flutter插件项目结构需要进行以下更新：

将插件中的ohos目录从OpenHarmony工程project结构替换为module结构
统一管理HAR文件，将所有引用的HAR文件放到ohos/har目录下
删除插件中的旧模块目录

3.2 使用AtomGit引入规范工具包

为了简化规范的实施，开发者可以使用官方提供的规范工具包：

dependencies:
  flutter:
    sdk: flutter
  flutter_ohos_spec_tools:
    git:
      url: "https://atomgit.com/"
      path: "packages/flutter_ohos_spec_tools/flutter_ohos_spec_tools"

3.3 详细更新步骤

以integration_test插件为例，详细说明更新步骤：

3.3.1 目录结构转换

将插件的ohos目录从project结构转换为module结构：

cd flutter_flutter/packages/integration_test
# 备份原ohos目录
mv ohos/ohos ./ohos2
# 删除原ohos目录
rm -rf ohos
# 重命名备份目录为ohos
mv ohos2 ohos
# 更新依赖
cd example
flutter pub get
# 测试编译
flutter build hap --debug

3.3.2 配置文件更新

修改插件的oh-package.json5

{
  "name": "integration_test", // 和插件名(pubspec.yaml中的name)保持一致
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {
    "@ohos/flutter_ohos": "file:har/flutter.har"
  }
}

修改插件的module.json5

{
  "module": {
    "name": "integration_test", // 和插件名(pubspec.yaml中的name)保持一致
    "type": "har",
    "deviceTypes": [
      "default",
      "tablet",
      "2in1"
    ]
  }
}

修改插件的hvigorfile.ts

export { harTasks } from '@ohos/hvigor-ohos-plugin';

3.3.3 引用HAR文件的配置

在使用插件的Flutter项目中，需要正确配置HAR文件的引用：

项目级oh-package.json5

{
  // ...
  "dependencies": {
    "@ohos/flutter_ohos": "file:./har/flutter.har"
  },
  "overrides": {
    "@ohos/flutter_ohos": "file:./har/flutter.har"
  }
}

模块级oh-package.json5

{
  // ...
  "dependencies": {
    "integration_test": "file:../har/integration_test.har"
  }
}

4. 规范工具包API使用

4.1 初始化规范检查

使用规范工具包初始化项目检查：

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void main() {
  // 初始化规范检查工具
  SpecChecker.init(
    projectPath: './',
    checkDirectoryStructure: true,
    checkPluginStructure: true,
  );

  // 执行规范检查
  final result = SpecChecker.checkAll();

  // 输出检查结果
  print('规范检查结果：');
  print('目录结构检查：${result.directoryStructureValid ? '通过' : '不通过'}');
  print('插件结构检查：${result.pluginStructureValid ? '通过' : '不通过'}');

  // 输出详细问题
  if (result.issues.isNotEmpty) {
    print('\n发现的问题：');
    for (final issue in result.issues) {
      print('- ${issue.description}');
      print('  建议：${issue.suggestion}');
    }
  } else {
    print('\n✅ 所有规范检查通过！');
  }
}

4.2 自动修复规范问题

使用规范工具包自动修复部分问题：

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void main() async {
  // 初始化规范修复工具
  final fixer = SpecFixer(
    projectPath: './',
    backupBeforeFix: true, // 修复前创建备份
  );

  // 执行自动修复
  final fixResult = await fixer.fixAll();

  // 输出修复结果
  print('规范修复结果：');
  print('已修复问题：${fixResult.fixedIssues.length}');
  print('无法自动修复问题：${fixResult.unfixedIssues.length}');

  if (fixResult.unfixedIssues.isNotEmpty) {
    print('\n需要手动修复的问题：');
    for (final issue in fixResult.unfixedIssues) {
      print('- ${issue.description}');
      print('  建议：${issue.suggestion}');
    }
  } else {
    print('\n✅ 所有问题已自动修复！');
  }
}

5. 常见问题及解决方案

5.1 路径不存在错误

问题描述：

hvigor ERROR: ENOENT: no such file or directory, stat 'xxx/flutter_flutter/packages/integration_test/ohos/build/default/cache/default/default@packageHar/ohos/oh_modules/@ohos/flutter_ohos'

解决方案：
手动删除报错信息提示的文件路径。

5.2 符号链接操作权限问题

问题描述：

hvigor ERROR: ENOENT: operation not permitted, symlink
'xxx/webview_flutter_ohos/ohos/webview_flutter/oh_modules/.ohpm/@ohos+flutter_ohos@file+libs+flutter.har/oh_modules/@ohos/flutter_ohos' ->
'xxx/webview_flutter_ohos/ohos/build/default/cache/default/default@PackageHar/webview_flutter/oh_modules/@ohos/flutter_ohos'

解决方案：
手动删除旧的插件目录结构，例如：

rm -rf flutter_packages/packages/webview_flutter_ohos/ohos/webview_flutter
rm -rf flutter_packages/packages/path_provider_ohos/ohos/path_provider
rm -rf flutter_packages/packages/file_selector_ohos/ohos/FileSelector