520kiss/kitchen

Fork 0

Files

Developer 13fdbdc431 瀑布流

2026-04-13 03:39:29 +08:00

18 KiB

Raw Blame History

fl_chart 鸿蒙适配方案

文档创建: 2026-04-09 适配版本: fl_chart 1.2.0 → 1.2.0-ohos.1 验证状态: ✅ Android / ✅ HarmonyOS / ⚠️ Web（白屏，非 fl_chart 问题）

一、适配结论

fl_chart 是纯 Dart 包，无任何原生平台代码，适配鸿蒙零成本。

检查项	结果	说明
是否有 `android/` `ios/` 原生目录	❌ 无	纯 Dart 实现
是否使用 `MethodChannel`	❌ 无	无平台通道
是否使用 `dart:io`	❌ 无	仅用 `dart:ui`（Canvas）
依赖是否纯 Dart	✅ 是	`equatable` + `vector_math` + `flutter`
是否需要 FFI	❌ 不需要	无原生调用
Canvas API 鸿蒙兼容	✅ 兼容	Flutter OH 引擎完整支持 `dart:ui`

二、适配步骤

2.1 拉取源码到本地

cd e:\project\flutter\f\mom_kitchen\packages
git clone --depth 1 --branch 1.2.0 https://github.com/imaNNeo/fl_chart.git fl_chart

2.2 修改版本号

编辑 packages/fl_chart/pubspec.yaml：

# 修改前
version: 1.2.0

# 修改后
version: 1.2.0-ohos.1

版本号加 -ohos.1 后缀标识鸿蒙适配版，避免与 pub.dev 版本冲突。

2.3 创建 ohos 目录结构

纯 Dart 包只需空壳 ohos 模块，满足鸿蒙构建系统识别要求：

packages/fl_chart/ohos/
├── Index.ets                                          # 模块入口
├── oh-package.json5                                   # 依赖配置
├── build-profile.json5                                # 构建配置
├── libs/                                              # flutter.har 占位
└── src/main/
    ├── module.json5                                   # 模块声明（har 类型）
    ├── resources/base/profile/                        # 资源目录
    └── ets/components/plugin/
        └── FlChartPlugin.ets                          # 空壳插件

各文件内容

ohos/Index.ets

import FlChartPlugin from './src/main/ets/components/plugin/FlChartPlugin';
export default FlChartPlugin;

ohos/oh-package.json5

{
  "name": "fl_chart",
  "version": "1.2.0-ohos.1",
  "description": "A highly customizable Flutter chart library - HarmonyOS adaptation",
  "main": "Index.ets",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

ohos/build-profile.json5

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

ohos/src/main/module.json5

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

ohos/src/main/ets/components/plugin/FlChartPlugin.ets

export default class FlChartPlugin {}

纯 Dart 包的 ets 文件为空壳，因为所有逻辑在 Dart 层完成，无需原生实现。

2.4 项目引用本地依赖

编辑项目根目录 pubspec.yaml：

dependencies:
  fl_chart:
    path: packages/fl_chart

2.5 验证

flutter pub get
flutter analyze --no-pub
flutter run -d <device-id>

三、纯 Dart 包 vs 原生插件适配对比

对比项	纯 Dart 包（如 fl_chart）	原生插件（如 path_provider）
是否需要 ets 原生代码	❌ 空壳即可	✅ 需要完整实现
是否需要 MethodChannel	❌ 不需要	✅ 需要
是否需要打 har 包	❌ 不需要	✅ 需要
是否需要 DevEco Studio	❌ 不需要	✅ 需要
pubspec.yaml 声明	无需 `flutter.plugin`	需要 `flutter.plugin.platforms.ohos`
适配工作量	⏱️ 5 分钟	⏱️ 1-3 天
适配风险	🟢 零风险	🟡 中等（API 差异）

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

如需适配原生插件，请参考以下流程：

1. 创建 ohos 模块
   flutter create --platforms ohos <plugin_name>_ohos

2. 编写 Dart 接口
   复制 android 版 lib 代码，将 android 改为 ohos

3. 编写 ets 原生代码
   参考 android/ios 实现，使用 OpenHarmony API 重写

4. 修改 pubspec.yaml
   flutter: plugin: platforms: 添加 ohos 声明

5. 打 har 包
   DevEco Studio → Build → Make Module

6. 编写 example 验证
   flutter create --platforms ohos example

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

四、Web 端白屏问题分析

4.1 现象

✅ Android 端正常
✅ HarmonyOS 端正常
❌ Web 端白屏

4.2 原因分析

白屏与 fl_chart 无关，是项目本身存在多个 Web 不兼容的依赖：

问题依赖	引用位置	Web 兼容	说明
`dart:io`	`logger_service.dart`	❌	Web 不支持 `dart:io`，需条件导入
`path_provider` (git版)	`hive_service.dart` `api_service.dart` `logger_service.dart`	⚠️	git 版可能无 web 实现
`connectivity_plus` (git版)	`api_service.dart` `connectivity_service.dart`	⚠️	git 版可能无 web 实现
`permission_handler`	`permission_service.dart`	❌	Web 不支持原生权限
`share_plus` (git版)	`common_utils.dart`	⚠️	git 版可能无 web 实现
`fluttertoast` (本地)	`toast_service.dart`	⚠️	本地版可能无 web 实现
`hive_ce`	`hive_service.dart` + 4个 model	⚠️	需验证 Web 存储

4.3 关键阻塞

logger_service.dart 直接 import 'dart:io' 无条件导入，这是 Web 白屏的最可能原因。Web 端加载 dart:io 会直接崩溃。

4.4 修复方案

方案 A：条件导入（推荐）

// logger_service.dart
import 'dart:io' if (dart.library.html) 'logger_web_stub.dart';

创建 logger_web_stub.dart：

// Web 端 stub，提供空实现
class File {}
class Directory {}
// ... 其他 dart:io 中用到的类

方案 B：运行时检查

import 'package:flutter/foundation.dart';

if (kIsWeb) {
  // Web 端跳过文件操作
} else {
  // 原生端正常执行
}

方案 C：Web 端不初始化问题服务

在 app_service.dart 中：

if (!kIsWeb) {
  await LoggerService().init();
  await HiveService().init();
}

4.5 修复优先级

优先级	修复项	工作量
P0	`logger_service.dart` 条件导入 `dart:io`	30min
P1	`hive_service.dart` Web 端跳过初始化	15min
P1	`api_service.dart` Web 端跳过 connectivity 检查	15min
P2	`permission_service.dart` Web 端 stub	20min
P2	`toast_service.dart` Web 端使用 SnackBar 替代	20min
P3	git 版依赖验证 Web 平台支持	1h

五、项目依赖 Web 兼容性清单

依赖	来源	Web 兼容	鸿蒙兼容	备注
`fl_chart`	本地 path	✅	✅	纯 Dart，全平台兼容
`hive_ce`	pub.dev	✅	✅	纯 Dart，Web 用 IndexedDB
`equatable`	pub.dev	✅	✅	纯 Dart
`vector_math`	pub.dev	✅	✅	纯 Dart
`get`	pub.dev	✅	✅	纯 Dart
`dio`	pub.dev	✅	✅	纯 Dart
`logger`	pub.dev	✅	✅	纯 Dart
`intl`	pub.dev	✅	✅	纯 Dart
`path_provider`	git (鸿蒙版)	⚠️	✅	需验证 Web 支持
`connectivity_plus`	git (鸿蒙版)	⚠️	✅	需验证 Web 支持
`share_plus`	git (鸿蒙版)	⚠️	✅	需验证 Web 支持
`permission_handler`	git (鸿蒙版)	❌	✅	Web 不支持原生权限
`fluttertoast`	本地 path	⚠️	✅	需验证 Web 支持
`shared_preferences`	pub.dev	✅	✅	Web 用 localStorage
`cupertino_icons`	pub.dev	✅	✅	纯资源包

六、快速判断：新包是否需要鸿蒙适配

新包是否包含原生代码？
├── 否（纯 Dart）
│   └── ✅ 零适配，直接使用
│       └── 若需本地化：改版本号 + 创建空壳 ohos 目录
│
└── 是（有原生代码）
    ├── 使用 MethodChannel？
    │   ├── 是 → 需要写 ets 原生实现 + 打 har 包
    │   └── 否 → 检查是否 FFI 插件
    │
    └── 使用 FFI？
        └── 是 → 需要编译鸿蒙版 .so + 配置 CMakeLists

纯 Dart 包特征

pubspec.yaml 无 flutter.plugin 声明
无 android/ ios/ windows/ 等原生目录
lib/ 下只有 .dart 文件
仅依赖 flutter SDK + 其他纯 Dart 包
使用 CustomPaint + Canvas 绘制（如 fl_chart）

原生插件特征

pubspec.yaml 有 flutter.plugin.platforms 声明
有 android/ ios/ 等原生目录
使用 MethodChannel / EventChannel 通信
涉及平台 API（文件系统、传感器、通知等）

七、参考文档

ohos平台适配flutter三方库指导.md — 原生插件适配完整流程
[开发FFI plugin.md](./开发FFI plugin.md) — FFI 插件开发指南
OpenHarmony应用如何集成Flutter模块.md — Flutter 模块集成到鸿蒙应用

八、已适配纯 Dart 包清单

8.1 fl_chart 适配记录

项目	内容
原版本	1.2.0
适配版本	1.2.0-ohos.1
适配日期	2026-04-09
适配类型	纯 Dart 包（零成本适配）
验证状态	✅ Android / ✅ HarmonyOS / ⚠️ Web

8.2 badges 适配记录

项目	内容
原版本	3.2.0
适配版本	3.2.0-ohos.1
适配日期	2026-04-10
适配类型	纯 Dart 包（零成本适配）
验证状态	✅ flutter pub get / ✅ flutter analyze

badges 适配步骤

# 1. 拉取源码
cd e:\project\flutter\f\mom_kitchen\packages
git clone --depth 1 --branch v3.2.0 https://github.com/yako-dev/flutter_badges.git badges

# 2. 修改版本号
# pubspec.yaml: version: 3.2.0 → 3.2.0-ohos.1

# 3. 创建空壳 ohos 目录
packages/badges/ohos/
├── Index.ets
├── oh-package.json5
├── build-profile.json5
├── libs/
└── src/main/
    ├── module.json5
    ├── resources/base/profile/
    └── ets/components/plugin/
        └── BadgesPlugin.ets

# 4. 项目引用
# pubspec.yaml: badges: path: packages/badges

# 5. 验证
flutter pub get
flutter analyze --no-pub

badges 文件内容

ohos/Index.ets

import BadgesPlugin from './src/main/ets/components/plugin/BadgesPlugin';
export default BadgesPlugin;

ohos/oh-package.json5

{
  "name": "badges",
  "version": "3.2.0-ohos.1",
  "description": "A package for creating badges - HarmonyOS adaptation",
  "main": "Index.ets",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

ohos/build-profile.json5

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

ohos/src/main/module.json5

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

ohos/src/main/ets/components/plugin/BadgesPlugin.ets

export default class BadgesPlugin {}

badges 使用示例

import 'package:badges/badges.dart' as badges;

badges.Badge(
  badgeContent: Text('3'),
  child: Icon(CupertinoIcons.shopping_cart),
)

8.3 flutter_staggered_grid_view 适配记录

项目	内容
原版本	0.7.0
适配版本	0.7.0-ohos.1
适配日期	2026-04-12
适配类型	纯 Dart 包（零成本适配）
验证状态	✅ flutter pub get / ✅ flutter analyze

flutter_staggered_grid_view 适配步骤

# 1. 拉取源码
cd e:\project\flutter\f\mom_kitchen\packages
git clone --depth 1 --branch v0.7.0 https://github.com/letsar/flutter_staggered_grid_view.git

# 2. 修改版本号
# pubspec.yaml: version: 0.7.0 → 0.7.0-ohos.1

# 3. 创建空壳 ohos 目录
packages/flutter_staggered_grid_view/ohos/
├── Index.ets
├── oh-package.json5
├── build-profile.json5
├── libs/
└── src/main/
    ├── module.json5
    ├── resources/base/profile/
    └── ets/components/plugin/
        └── FlutterStaggeredGridViewPlugin.ets

# 4. 项目引用
# pubspec.yaml:
# flutter_staggered_grid_view:
#   path: packages/flutter_staggered_grid_view

# 5. 验证
flutter pub get
flutter analyze --no-pub

flutter_staggered_grid_view 文件内容

ohos/Index.ets

import FlutterStaggeredGridViewPlugin from './src/main/ets/components/plugin/FlutterStaggeredGridViewPlugin';
export default FlutterStaggeredGridViewPlugin;

ohos/oh-package.json5

{
  "name": "flutter_staggered_grid_view",
  "version": "0.7.0-ohos.1",
  "description": "Provides a collection of Flutter grids layouts - HarmonyOS adaptation",
  "main": "Index.ets",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

ohos/build-profile.json5

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

ohos/src/main/module.json5

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

ohos/src/main/ets/components/plugin/FlutterStaggeredGridViewPlugin.ets

export default class FlutterStaggeredGridViewPlugin {}

flutter_staggered_grid_view 使用示例

import 'package:flutter_staggered_grid_view/flutter_staggered_grid_view.dart';

MasonryGridView.count(
  crossAxisCount: 2,
  mainAxisSpacing: 4,
  crossAxisSpacing: 4,
  itemCount: items.length,
  itemBuilder: (context, index) {
    return Tile(index: index);
  },
)

8.4 cached_network_image 适配记录

项目	内容
原版本	3.4.1
适配版本	3.4.1-ohos.1
适配日期	2026-04-12
适配类型	纯 Dart 包（使用条件导入）
验证状态	✅ flutter pub get / ✅ flutter analyze

cached_network_image 依赖链分析

cached_network_image
  ├── cached_network_image_platform_interface (纯 Dart)
  ├── cached_network_image_web (纯 Dart)
  ├── octo_image (纯 Dart)
  └── flutter_cache_manager
        ├── path_provider ✅ (项目已有鸿蒙版本)
        └── sqflite ✅ (已有鸿蒙适配版本)

说明：cached_network_image 使用条件导入实现跨平台，IO 平台使用 flutter_cache_manager，Web 平台使用 cached_network_image_web。鸿蒙平台走 IO 分支，依赖 flutter_cache_manager。

cached_network_image 适配步骤

# 1. 拉取源码（monorepo 结构）
cd e:\project\flutter\f\mom_kitchen\packages
git clone --depth 1 --branch v3.4.1 https://github.com/Baseflow/flutter_cached_network_image.git cached_network_image

# 2. 修改版本号
# packages/cached_network_image/cached_network_image/pubspec.yaml
# version: 3.4.1 → 3.4.1-ohos.1

# 3. 创建空壳 ohos 目录
packages/cached_network_image/cached_network_image/ohos/
├── Index.ets
├── oh-package.json5
├── build-profile.json5
├── libs/
└── src/main/
    ├── module.json5
    ├── resources/base/profile/
    └── ets/components/plugin/
        └── CachedNetworkImagePlugin.ets

# 4. 项目引用
# pubspec.yaml:
# cached_network_image:
#   path: packages/cached_network_image/cached_network_image

# 5. 验证
flutter pub get
flutter analyze --no-pub

cached_network_image 文件内容

ohos/Index.ets

import CachedNetworkImagePlugin from './src/main/ets/components/plugin/CachedNetworkImagePlugin';
export default CachedNetworkImagePlugin;

ohos/oh-package.json5

{
  "name": "cached_network_image",
  "version": "3.4.1-ohos.1",
  "description": "Flutter library to load and cache network images - HarmonyOS adaptation",
  "main": "Index.ets",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

ohos/build-profile.json5

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

ohos/src/main/module.json5

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

ohos/src/main/ets/components/plugin/CachedNetworkImagePlugin.ets

export default class CachedNetworkImagePlugin {}

cached_network_image 使用示例

import 'package:cached_network_image/cached_network_image.dart';

CachedNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
)

九、适配总结

包名	类型	适配方式	工作量	状态
fl_chart	纯 Dart	空壳 ohos 目录	5min	✅ 完成
badges	纯 Dart	空壳 ohos 目录	5min	✅ 完成
flutter_staggered_grid_view	纯 Dart	空壳 ohos 目录	5min	✅ 完成
cached_network_image	纯 Dart（条件导入）	空壳 ohos 目录	5min	✅ 完成

纯 Dart 包适配要点：

修改版本号加 -ohos.1 后缀

创建空壳 ohos 目录结构

项目 pubspec.yaml 使用 path: 引用

无需编写任何原生代码

无需 DevEco Studio 打 har 包

原生插件适配要点：

需要 ets 原生代码实现

需要 MethodChannel 通信

需要 DevEco Studio 打 har 包

工作量 1-3 天

参考 ohos平台适配flutter三方库指导.md

18 KiB Raw Blame History Unescape Escape

fl_chart 鸿蒙适配方案

一、适配结论

二、适配步骤

2.1 拉取源码到本地

2.2 修改版本号

2.3 创建 ohos 目录结构

各文件内容

2.4 项目引用本地依赖

2.5 验证

三、纯 Dart 包 vs 原生插件适配对比

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

四、Web 端白屏问题分析

4.1 现象

4.2 原因分析

4.3 关键阻塞

4.4 修复方案

方案 A：条件导入（推荐）

方案 B：运行时检查

方案 C：Web 端不初始化问题服务

4.5 修复优先级

五、项目依赖 Web 兼容性清单

六、快速判断：新包是否需要鸿蒙适配

纯 Dart 包特征

原生插件特征

七、参考文档

八、已适配纯 Dart 包清单

8.1 fl_chart 适配记录

8.2 badges 适配记录

badges 适配步骤

badges 文件内容

badges 使用示例

8.3 flutter_staggered_grid_view 适配记录

flutter_staggered_grid_view 适配步骤

flutter_staggered_grid_view 文件内容

flutter_staggered_grid_view 使用示例

8.4 cached_network_image 适配记录

cached_network_image 依赖链分析

cached_network_image 适配步骤

cached_network_image 文件内容

cached_network_image 使用示例

九、适配总结

18 KiB

Raw Blame History