一、工具介绍

Flutter跨平台开发鸿蒙化规范工具是一套用于确保Flutter项目在OpenHarmony平台上正确构建和运行的标准化工具集。该工具旨在帮助开发者遵循Flutter鸿蒙化项目的最佳实践，确保项目目录结构、配置文件和依赖管理符合OpenHarmony平台的要求。

通过使用这套规范工具，开发者可以：

• 自动检查Flutter项目的鸿蒙化目录结构是否符合规范
• 自动修复不符合规范的配置文件和目录结构
• 确保HAR文件引用和依赖管理正确配置
• 简化Flutter插件项目从project结构到module结构的转换过程

二、环境搭建

2.1 系统要求

• Flutter SDK 3.7.0或更高版本
• OpenHarmony SDK API 9或更高版本
• DevEco Studio 3.0或更高版本
• Node.js 16.0或更高版本

2.2 安装依赖

在Flutter项目中添加规范工具依赖：

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

然后运行以下命令安装依赖：

flutter pub get

三、快速开始

3.1 初始化规范检查器

在项目的主入口文件中初始化规范检查器：

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void main() {
  // 初始化规范检查器
  SpecChecker.init();

  runApp(const MyApp());
}

3.2 执行规范检查

在命令行中运行以下命令执行规范检查：

flutter pub run flutter_ohos_spec_tools:check

检查结果将显示在控制台中，包括符合规范的项目结构和需要修复的问题。

3.3 自动修复规范问题

如果检查发现不符合规范的问题，可以使用以下命令自动修复：

flutter pub run flutter_ohos_spec_tools:fix

四、API调用示例

4.1 目录结构检查

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void checkDirectoryStructure() {
  // 检查Flutter鸿蒙化项目目录结构
  final result = SpecChecker.checkDirectoryStructure();

  if (result.isValid) {
    print('目录结构符合规范');
  } else {
    print('目录结构不符合规范：');
    result.issues.forEach((issue) {
      print('- ${issue.description}');
    });

    // 自动修复目录结构问题
    SpecFixer.fixDirectoryStructure();
    print('目录结构已修复');
  }
}

4.2 配置文件检查与修复

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void checkAndFixConfigs() {
  // 检查配置文件
  final configResult = SpecChecker.checkConfigFiles();

  if (configResult.isValid) {
    print('所有配置文件符合规范');
  } else {
    print('配置文件不符合规范：');
    configResult.issues.forEach((issue) {
      print('- ${issue.description}');
    });

    // 自动修复配置文件
    SpecFixer.fixConfigFiles();
    print('配置文件已修复');
  }
}

4.3 HAR文件管理

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void manageHarFiles() {
  // 检查HAR文件引用
  final harResult = SpecChecker.checkHarFiles();

  if (harResult.isValid) {
    print('HAR文件引用符合规范');
  } else {
    print('HAR文件引用不符合规范：');
    harResult.issues.forEach((issue) {
      print('- ${issue.description}');
    });

    // 自动修复HAR文件引用
    SpecFixer.fixHarFiles();
    print('HAR文件引用已修复');
  }
}

五、插件项目结构转换

对于Flutter插件项目，可以使用以下API将其从project结构转换为module结构：

import 'package:flutter_ohos_spec_tools/flutter_ohos_spec_tools.dart';

void convertPluginStructure() {
  // 将插件项目从project结构转换为module结构
  final conversionResult = PluginConverter.convertToModuleStructure();

  if (conversionResult.success) {
    print('插件结构转换成功');
    print('需要手动执行的步骤：');
    conversionResult.manualSteps.forEach((step) {
      print('- ${step}');
    });
  } else {
    print('插件结构转换失败：');
    print(conversionResult.errorMessage);
  }
}

六、命令行工具使用

6.1 检查项目规范

flutter pub run flutter_ohos_spec_tools:check

该命令会检查项目的目录结构、配置文件和HAR文件引用是否符合规范，并输出检查结果。

6.2 修复项目规范问题

flutter pub run flutter_ohos_spec_tools:fix

该命令会自动修复项目中不符合规范的问题，包括目录结构、配置文件和HAR文件引用。

6.3 转换插件结构

flutter pub run flutter_ohos_spec_tools:convert_plugin

该命令会将Flutter插件项目从project结构转换为module结构，并更新相关配置文件。

6.4 生成规范报告

flutter pub run flutter_ohos_spec_tools:report

该命令会生成项目规范检查报告，包括符合规范的项目结构和需要修复的问题。

七、最佳实践

7.1 项目目录结构规范

确保Flutter鸿蒙化项目的目录结构符合以下规范：

project/
├── lib/                      # Flutter代码
├── ohos/                     # OpenHarmony代码
│   ├── AppScope/             # 应用全局配置
│   │   └── app.json5         # 应用配置文件
│   ├── build-profile.json5   # 项目构建配置
│   ├── entry/                # 应用入口模块
│   │   ├── src/              # 模块源代码
│   │   │   ├── main/         # 主源码目录
│   │   │   │   ├── entryability/  # 应用入口
│   │   │   │   │   └── EntryAbility.ets
│   │   │   │   └── pages/    # 页面目录
│   │   │   │       └── Index.ets
│   │   │   └── resources/    # 资源文件
│   │   ├── build-profile.json5   # 模块构建配置
│   │   ├── oh-package.json5      # 模块依赖配置
│   │   └── src/main/module.json5 # 模块配置文件
│   ├── har/                  # HAR文件目录
│   │   └── flutter.har       # Flutter核心HAR文件
│   └── oh-package.json5      # 项目依赖配置
└── pubspec.yaml              # Flutter依赖配置

7.2 配置文件规范

确保以下配置文件符合规范：

7.2.1 ohos/oh-package.json5

{
  "name": "your_project_name",
  "version": "1.0.0",
  "description": "项目描述",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "@ohos/flutter_ohos": "file:./har/flutter.har"
  },
  "devDependencies": {
    "@ohos/hypium": "1.0.11"
  }
}

7.2.2 ohos/entry/oh-package.json5

{
  "name": "entry",
  "version": "1.0.0",
  "description": "应用入口模块",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "@ohos/flutter_ohos": "file:../har/flutter.har"
  }
}

7.2.3 ohos/entry/src/main/module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "deviceTypes": [
      "default",
      "tablet",
      "2in1"
    ]
  }
}

7.3 HAR文件管理规范

• 所有HAR文件应统一存放在ohos/har目录下
• 使用file:协议引用HAR文件，例如："@ohos/flutter_ohos": "file:./har/flutter.har"
• 在overrides中也指定HAR文件引用，确保依赖解析正确

八、常见问题

8.1 目录结构不符合规范

问题：执行规范检查时提示目录结构不符合规范。

解决方案：运行以下命令自动修复目录结构：

flutter pub run flutter_ohos_spec_tools:fix

8.2 HAR文件引用错误

问题：构建时提示HAR文件引用错误。

解决方案：检查oh-package.json5文件中的HAR文件引用路径是否正确，并确保HAR文件存在于指定位置。

8.3 插件结构转换失败

问题：执行插件结构转换命令时失败。

解决方案：确保当前目录是Flutter插件项目的根目录，并且项目已经初始化。如果转换失败，可以手动执行以下步骤：

mv ohos/ohos ./ohos2
rm -rf ohos
mv ohos2 ohos
flutter pub get
flutter build hap --debug

然后手动修改配置文件中的name字段和hvigorfile.ts文件。

九、总结

Flutter跨平台开发鸿蒙化规范工具是确保Flutter项目在OpenHarmony平台上正确构建和运行的重要工具。通过使用这套工具，开发者可以自动检查和修复项目的目录结构、配置文件和HAR文件引用，确保项目符合OpenHarmony平台的要求。

同时，该工具还提供了命令行接口和Dart API，方便开发者在不同场景下使用。通过遵循工具提供的最佳实践，开发者可以简化Flutter项目的鸿蒙化过程，提高开发效率和项目质量。

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net