Flutter三方库适配OpenHarmony【flutter_web_auth】— OpenHarmony 插件工程搭建与配置文件详解

前言

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

从这篇开始正式进入 OpenHarmony 适配的核心内容。第一步是搭建插件工程——创建ohos目录、配置各种 json5 文件、写好入口导出。这些看起来是"脚手架"工作，但配置错一个字段就可能导致插件加载失败，排查起来非常痛苦。

一、ohos 目录结构

1.1 完整目录树

flutter_web_auth/ ├── lib/ # Dart 源码 ├── android/ # Android 插件 ├── ios/ # iOS 插件 ├── macos/ # macOS 插件 ├── ohos/ # OpenHarmony 插件 │ ├── src/ │ │ └── main/ │ │ ├── ets/ │ │ │ └── components/ │ │ │ └── plugin/ │ │ │ └── FlutterWebAuthPlugin.ets ← 核心实现 │ │ └── module.json5 ← 模块声明 │ ├── build-profile.json5 ← 构建配置 │ ├── hvigorfile.ts ← 构建脚本 │ ├── index.ets ← 入口导出 │ ├── oh-package.json5 ← 包配置 │ └── .gitignore ← Git 忽略 ├── pubspec.yaml # Flutter 包配置 └── example/ # 示例应用

1.2 各文件职责

二、oh-package.json5 包配置

2.1 完整内容

{ "name": "flutter_web_auth", "version": "1.0.0", "description": "Please describe the basic information.", "main": "index.ets", "author": "", "license": "Apache-2.0", "dependencies": {} }

2.2 字段说明

2.3 与 pubspec.yaml 的对应

# pubspec.yamlname:flutter_web_authversion:0.6.0

// oh-package.json5 "name": "flutter_web_auth", // 必须一致 "version": "1.0.0", // 可以不同

📌name 必须一致，否则 Flutter-OHOS 框架找不到插件。version 可以独立管理。

三、build-profile.json5 构建配置

3.1 完整内容

{ "apiType": "stageMode", "targets": [ { "name": "default", "runtimeOS": "OpenHarmony" } ] }

3.2 字段说明

3.3 Stage 模型 vs FA 模型

💡所有 Flutter-OHOS 插件都使用 Stage 模型。如果你看到 FA 模型的教程，那是过时的。

四、module.json5 模块声明

4.1 完整内容

{ "module": { "name": "flutter_web_auth", "type": "har", "deviceTypes": [ "default", "tablet" ] } }

4.2 字段说明

4.3 模块类型

4.4 与 secure_application 的对比

// flutter_web_auth 的 module.json5 { "module": { "name": "flutter_web_auth", "type": "har", "deviceTypes": ["default", "tablet"] } } // secure_application 的 module.json5（完全相同的结构） { "module": { "name": "secure_application", "type": "har", "deviceTypes": ["default", "tablet"] } }

📌所有 Flutter-OHOS 插件的 module.json5 结构都一样，只有 name 不同。

五、index.ets 入口文件

5.1 完整内容

importFlutterWebAuthPluginfrom'./src/main/ets/components/plugin/FlutterWebAuthPlugin';exportdefaultFlutterWebAuthPlugin;

5.2 作用

index.ets 是 oh-package.json5 中main字段指向的文件。Flutter-OHOS 框架通过这个文件找到插件类。

5.3 导入路径

index.ets ↓ import from ./src/main/ets/components/plugin/FlutterWebAuthPlugin.ets ↓ export default FlutterWebAuthPlugin 类

5.4 常见错误

六、hvigorfile.ts 构建脚本

6.1 完整内容

import{harTasks}from'@ohos/hvigor-ohos-plugin';exportdefault{system:harTasks,plugins:[]}

6.2 作用

hvigorfile.ts 是 Hvigor 构建系统的配置文件，类似 Android 的 build.gradle。对于 Flutter 插件，使用默认的harTasks就够了。

七、.gitignore 配置

7.1 完整内容

/node_modules /oh_modules /build /oh-package-lock.json5 /.preview

7.2 说明

八、pubspec.yaml 中的 ohos 平台声明

8.1 配置

flutter:plugin:platforms:android:package:com.linusu.flutter_web_authpluginClass:FlutterWebAuthPluginohos:package:com.linusu.flutter_web_authpluginClass:FlutterWebAuthPluginios:pluginClass:FlutterWebAuthPluginmacos:pluginClass:FlutterWebAuthPluginweb:pluginClass:FlutterWebAuthWebfileName:flutter_web_auth_web.dart

8.2 ohos 平台字段

8.3 与其他插件的对比

💡不同插件的 ohos 平台配置方式不完全一样。有的需要 package，有的需要 fileName，取决于 Flutter-OHOS 框架的版本和插件的注册方式。

九、工程搭建检查清单

9.1 文件检查

• ohos/oh-package.json5存在且 name 正确
• ohos/build-profile.json5存在且 apiType 为 stageMode
• ohos/src/main/module.json5存在且 type 为 har
• ohos/index.ets存在且导出路径正确
• ohos/hvigorfile.ts存在
• ohos/src/main/ets/components/plugin/FlutterWebAuthPlugin.ets存在

9.2 配置一致性检查

• oh-package.json5 的 name 与 pubspec.yaml 的 name 一致
• pubspec.yaml 中 ohos.pluginClass 与 ArkTS 类名一致
• index.ets 的 import 路径指向正确的文件

9.3 常见搭建错误

总结

本文详细讲解了 flutter_web_auth 的 OpenHarmony 插件工程搭建：

1. 目录结构：标准的 ohos/ 目录布局，6个关键文件
2. oh-package.json5：包名必须与 pubspec.yaml 一致
3. module.json5：type 为 har，支持 default 和 tablet
4. index.ets：入口导出，路径必须正确
5. pubspec.yaml：ohos 平台声明 pluginClass

下一篇我们讲 FlutterPlugin 与 AbilityAware 双接口实现——flutter_web_auth 为什么需要 AbilityAware。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• OpenHarmony HAR 包开发
• oh-package.json5 规范
• module.json5 配置
• Flutter-OHOS 插件开发
• flutter_web_auth Gitcode
• Hvigor 构建系统
• pubspec.yaml 插件配置
• 开源鸿蒙跨平台社区