kitchen/packages/本地已适配鸿蒙的库.md

鸿蒙适配方案

文档创建: 2026-04-09 | 最后更新: 2026-04-14 适配策略: 纯 Dart 包零成本适配 + 原生插件完整适配

---

一、纯 Dart 包 vs 原生插件判断

检查项	纯 Dart 包	原生插件
android/ ios/ 目录	❌ 无	✅ 有
flutter.plugin 声明	❌ 无	✅ 有
MethodChannel / FFI	❌ 无	✅ 有
适配方式	空壳 ohos 目录	ets 原生实现 + har 包
工作量	5min	1-3 天

快速判断流程

新包是否包含原生代码？
├── 否（纯 Dart）→ ✅ 零适配：改版本号 + 空壳 ohos 目录
└── 是（有原生代码）
    ├── MethodChannel → 需 ets 实现 + DevEco Studio 打 har
    └── FFI → 需编译鸿蒙版 .so + CMakeLists

---

二、纯 Dart 包适配步骤（通用模板）

2.1 拉取源码

cd packages
git clone --depth 1 --branch <version> <github-url> <package-name>

2.2 修改版本号

pubspec.yaml 中 version: x.x.x → x.x.x-ohos.1

2.3 创建空壳 ohos 目录

packages/<name>/ohos/
├── Index.ets
├── oh-package.json5
├── build-profile.json5
├── libs/                          # flutter.har 占位（空目录）
└── src/main/
    ├── module.json5
    ├── resources/base/profile/    # 空目录
    └── ets/components/plugin/
        └── <Name>Plugin.ets       # 空壳类

通用文件模板（所有纯 Dart 包共用）

Index.ets

import <Name>Plugin from './src/main/ets/components/plugin/<Name>Plugin';
export default <Name>Plugin;

oh-package.json5

{
  "name": "<package_name>",
  "version": "<version>-ohos.1",
  "description": "<desc> - HarmonyOS adaptation",
  "main": "Index.ets",
  "author": "",
  "license": "<license>",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

build-profile.json5

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

module.json5

{
  "module": {
    "name": "<package_name>",
    "type": "har",
    "deviceTypes": ["default", "tablet"]
  }
}

<Name>Plugin.ets

export default class <Name>Plugin {}

2.4 项目引用 & 验证

# pubspec.yaml
dependencies:
  <package_name>:
    path: packages/<package_name>

flutter pub get && flutter analyze --no-pub

---

三、原生插件适配流程（参考）

详见 ohos平台适配flutter三方库指导.md

1. flutter create --platforms ohos <plugin>_ohos
2. 复制 android 版 lib dart 代码，android → ohos
3. DevEco Studio 编写 ets 原生代码（参考 android/ios）
4. pubspec.yaml 添加 flutter.plugin.platforms.ohos
5. DevEco Studio → Build → Make Module 打 har 包
6. flutter create --platforms ohos example 验证

---

四、Web 兼容性问题备忘

项目 Web 白屏与各适配包无关，是项目本身依赖问题：

问题依赖	原因	修复方案
dart:io (logger_service)	Web 不支持	条件导入或 kIsWeb 检查
path_provider (git版)	可能无 web 实现	跳过初始化
permission_handler	Web 不支持原生权限	stub 或跳过
fluttertoast (本地)	可能无 web 实现	SnackBar 替代

---

五、已适配纯 Dart 包清单

5.1 总览表

#	包名	原版本	适配版本	日期	状态
1	fl_chart	1.2.0	1.2.0-ohos.1	2026-04-09	✅ Android / HarmonyOS
2	badges	3.2.0	3.2.0-ohos.1	2026-04-10	✅ analyze 通过
3	flutter_staggered_grid_view	0.7.0	0.7.0-ohos.1	2026-04-12	✅ analyze 通过
4	cached_network_image	3.4.1	3.4.1-ohos.1	2026-04-12	✅ analyze 通过
5	flutter_markdown_plus	1.0.7	1.0.7-ohos.1	2026-04-14	✅ analyze 通过
6	flutter_card_swiper	7.2.0	7.2.0-ohos.1	2026-04-14	✅ analyze 通过

5.2 各包克隆命令速查

cd packages

# 1. fl_chart
git clone --depth 1 --branch 1.2.0 https://github.com/imaNNeo/fl_chart.git fl_chart

# 2. badges
git clone --depth 1 --branch v3.2.0 https://github.com/yako-dev/flutter_badges.git badges

# 3. flutter_staggered_grid_view
git clone --depth 1 --branch v0.7.0 https://github.com/letsar/flutter_staggered_grid_view.git

# 4. cached_network_image（monorepo，主包在子目录）
git clone --depth 1 --branch v3.4.1 https://github.com/Baseflow/flutter_cached_network_image.git cached_network_image
# 引用路径: packages/cached_network_image/cached_network_image

# 5. flutter_markdown_plus
git clone --depth 1 --branch v1.0.7 https://github.com/foresightmobile/flutter_markdown_plus.git flutter_markdown_plus

# 6. flutter_card_swiper
git clone --depth 1 --branch v7.2.0 https://github.com/ricardodalarme/flutter_card_swiper.git flutter_card_swiper

5.3 各包使用示例

fl_chart

import 'package:fl_chart/fl_chart.dart';
LineChart(LineChartData(...))

badges

import 'package:badges/badges.dart' as badges;
badges.Badge(badgeContent: Text('3'), child: Icon(CupertinoIcons.shopping_cart))

flutter_staggered_grid_view

import 'package:flutter_staggered_grid_view/flutter_staggered_grid_view.dart';
MasonryGridView.count(crossAxisCount: 2, itemCount: items.length, itemBuilder: (ctx, i) => Tile(index: i))

cached_network_image

import 'package:cached_network_image/cached_network_image.dart';
CachedNetworkImage(imageUrl: 'url', placeholder: (ctx, url) => CircularProgressIndicator(), errorWidget: (ctx, url, err) => Icon(Icons.error))

flutter_markdown_plus

import 'package:flutter_markdown_plus/flutter_markdown_plus.dart';
Markdown(data: '# Hello\n**bold** text', onTapLink: (text, href, title) {})

flutter_card_swiper

import 'package:flutter_card_swiper/flutter_card_swiper.dart';
CardSwiper(itemCount: cards.length, itemBuilder: (ctx, index) => CardWidget(cards[index]), onSwipe: (prev, curr, direction) {})

---

六、项目依赖兼容性总览

依赖	来源	Web	鸿蒙	备注
fl_chart	本地 path	✅	✅	纯 Dart
badges	本地 path	✅	✅	纯 Dart
flutter_staggered_grid_view	本地 path	✅	✅	纯 Dart
cached_network_image	本地 path	✅	✅	条件导入，IO 分支
flutter_markdown_plus	本地 path	✅	✅	纯 Dart，全平台支持
flutter_card_swiper	本地 path	✅	✅	纯 Dart
hive_ce	pub.dev	✅	✅	纯 Dart
get / dio / logger / intl	pub.dev	✅	✅	纯 Dart
shared_preferences	pub.dev	✅	✅	localStorage
path_provider	git(鸿蒙版)	⚠️	✅	需验证 web
connectivity_plus	git(鸿蒙版)	⚠️	✅	需验证 web
share_plus	git(鸿蒙版)	⚠️	✅	需验证 web
permission_handler	git(鸿蒙版)	❌	✅	Web 不支持
fluttertoast	本地 path	⚠️	✅	需验证 web

---

七、参考文档索引

文档	用途
ohos平台适配flutter三方库指导.md	原生插件完整适配流程（MethodChannel、打 har 包）
[开发FFI plugin.md](./开发FFI plugin.md)	FFI 插件开发指南
OpenHarmony应用如何集成Flutter模块.md	Flutter 模块集成到鸿蒙应用
FlutterChannel通信.md	MethodChannel / EventChannel / BasicMessageChannel 用法