520kiss/kitchen

Fork 0

Files

Developer 8d27c67d3a api实现

2026-04-09 08:54:36 +08:00

9.1 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 模块集成到鸿蒙应用

9.1 KiB Raw Blame History Unescape Escape