refactor: update README and project structure for native integration and OHOS support
- Enhanced README to clarify native integration methods for Android/iOS and OHOS. - Updated project structure documentation to reflect changes in native capabilities and dependencies. - Revised native integration documentation to specify transport methods for Android/iOS and OHOS. - Documented the current implementation strategy for OHOS, emphasizing the use of MethodChannel for ArkTS. - Adjusted SDK versioning notes to clarify the separation between Android/iOS and OHOS SDKs.
This commit is contained in:
Guangfei.Zhao
@@ -2,13 +2,13 @@
|
||||
|
||||
## 决策
|
||||
|
||||
原生能力（扫码、支付、蓝牙等）统一封装成独立的 `native_*` Dart package（结构见 [01-project-structure.md](./01-project-structure.md)），跨语言接口用 **[Pigeon](https://pub.dev/packages/pigeon)**（`^27.3.0`，2026-08 快照）生成，不手写裸 `MethodChannel`/`invokeMethod` 字符串调用。
|
||||
原生能力（扫码、支付、蓝牙等）统一由独立的 `native_*` Dart package 暴露稳定公共 API（结构见 [01-project-structure.md](./01-project-structure.md)）。**Android/iOS** 跨语言接口使用 [Pigeon](https://pub.dev/packages/pigeon)（锁定 `26.3.1`）生成；`harmony` 分支的首期 **OHOS** 实现是经过约束的例外：`native_*` 内部通过手写 `MethodChannel` 调用 App 宿主 `app/ohos/entry` 中的 ArkTS，而不是将 OHOS 再包装成独立 Flutter plugin。
|
||||
|
||||
## 依赖
|
||||
|
||||
```yaml
|
||||
dev_dependencies:
|
||||
pigeon: ^27.3.0
|
||||
pigeon: 26.3.1
|
||||
```
|
||||
|
||||
## 包结构规则
|
||||
@@ -32,7 +32,28 @@ native_scan/
|
||||
Classes/NativeScanPlugin.swift # 手写：插件注册入口
|
||||
```
|
||||
|
||||
首版只有 `android/` 和 `ios/`（OHOS 不在首版范围，见文末「OHOS 后续演进」）。
|
||||
插件包中的原生目录目前只有 `android/` 和 `ios/`；这不是遗漏。OHOS 的首期 ArkTS 实现位于宿主 App 的 `app/ohos/entry`，见下节。
|
||||
|
||||
### 平台实现归属：Android/iOS 插件，OHOS 宿主桥接
|
||||
|
||||
```
|
||||
feature_* / core_webview（JSBridge）
|
||||
↓ 只依赖公共 Dart API
|
||||
native_scan
|
||||
┌─────────┴──────────┐
|
||||
│ │
|
||||
Android / iOS OHOS（harmony）
|
||||
Pigeon + plugin 手写 MethodChannel
|
||||
Kotlin / Swift ↓
|
||||
app/ohos/entry ArkTS
|
||||
```
|
||||
|
||||
| 平台 | Dart 到原生 transport | 原生代码归属 | 原因 |
|
||||
| --- | --- | --- | --- |
|
||||
| Android / iOS | Pigeon 生成的强类型桩代码 | `packages/native_scan/android`、`ios` | 复用成熟的 Flutter plugin 注册和 Kotlin/Swift 生成链路 |
|
||||
| OHOS（首期） | `native_scan` 内部的手写 `MethodChannel` | `app/ohos/entry/src/main/ets/` | Pigeon 不生成 ArkTS；不手抄其 `BasicMessageChannel` / 自定义 codec 协议，降低漂移风险 |
|
||||
|
||||
这不会增加 Dart `main` 文件，也不会新增 HAP module。`entry` 是已有 OHOS 应用模块；这里只是在其中增加本 App 的原生能力实现。业务代码和 H5 均不得直接调用 channel、ArkTS 或做 OHOS 平台判断。
|
||||
|
||||
### `pubspec.yaml` 必须声明 plugin platforms
|
||||
|
||||
@@ -250,24 +271,35 @@ pigeon:
|
||||
- Dart 生成物在根 `analysis_options.yaml` 里排除 lint（`analyzer: exclude: - "**/*.g.dart"`）。
|
||||
- CI 要有一步"重新生成后 `git diff --exit-code`"，防止有人改了 schema 但忘了提交生成物。
|
||||
|
||||
## OHOS 后续演进
|
||||
## OHOS 当前实现策略（`harmony`）
|
||||
|
||||
鸿蒙（OpenHarmony）**不在首版范围**，但基线决策是为它留了口子的，这里记录清楚，避免后面接的时候重新走一遍弯路。
|
||||
OHOS 不是 Android 的另一种 plugin platform。当前 Flutter_OH 工具链没有可直接复用的 Pigeon ArkTS 生成链路；而现有 Pigeon API 在 Dart 侧使用 `BasicMessageChannel`、自定义 codec、类型 tag 和生成的错误/结果 envelope。让 ArkTS 人工复刻该私有 wire protocol，维护成本和接口漂移风险都不值得。
|
||||
|
||||
接 OHOS 需要处理三件事：
|
||||
因此，OHOS 在 `native_scan` 的**内部**新增一条简洁、独立的 `MethodChannel` transport。它接收和返回仅用于该 transport 的基础 Map/List/标量，再映射回既有的 `ScanOptions`、`ScanResult` 与 `NativeScanException`；Android/iOS Pigeon schema、生成物与注册逻辑不因此改变。
|
||||
|
||||
1. **SDK 分支不同**：OHOS 用的是 OpenHarmony 社区维护的 Flutter 分支，版本落后于官方 stable 一段时间。这正是 [01-project-structure.md](./01-project-structure.md) 里 SDK 基线刻意停在 **3.44.9** 而不追 3.47.0 的原因——基线跑太前，OHOS 分支跟不上就接不进来。
|
||||
2. **Pigeon 没有 ArkTS 生成器**：Pigeon 官方只生成 Kotlin/Java、Swift/Objective-C、C++、GObject，**没有 ArkTS/OHOS**。所以 OHOS 侧的 channel 代码只能**手写**，需要人工保证方法名、参数结构与 Pigeon 生成的 Dart 端编解码格式一致——这是一份实打实的额外维护成本，接 OHOS 时要预留出来。
|
||||
3. **`native_*` 包要加 `ohos:` 平台声明**，并新增 `ohos/` 目录。
|
||||
ArkTS 按职责拆分，避免把业务实现写进默认入口：
|
||||
|
||||
在此之前，`native_*` 的公共 API 类里遇到不支持的平台，一律抛明确的 `UnsupportedPlatformException`，不静默返回空值或占位假数据——静默返回会让"这个平台其实没实现"的问题一直藏到用户手里。
|
||||
```
|
||||
app/ohos/entry/src/main/ets/
|
||||
entryability/EntryAbility.ets # 生命周期、Flutter engine 与 bridge 注册
|
||||
native_scan/NativeScanChannel.ets # 方法分发、参数/结果序列化、错误映射
|
||||
native_scan/OhosScanService.ets # 相机/扫码 API 调用
|
||||
native_scan/ScanPermissionService.ets # 相机权限检查与申请
|
||||
```
|
||||
|
||||
`NativeScanChannel` 必须集中维护 channel 名、方法名、参数、成功返回值与错误码；Dart facade 捕获 `PlatformException` 并继续转为 `NativeScanException`。取消、拒绝权限、能力不可用、超时和未知方法必须分别有明确错误码，不能返回空值或伪造扫描结果。
|
||||
|
||||
**延后抽取独立 OHOS plugin。** 只有出现第二个 OHOS App 的复用需求、扫描实现和契约已稳定、Flutter_OH plugin 注册/模板已成熟并经验证，或 SDK 化收益明确超过维护成本时，才评审将 ArkTS 从 `app/ohos/entry` 抽到 `packages/native_scan/ohos`。在此之前，不添加 `ohos:` plugin 声明或额外 `ohos/` 目录。
|
||||
|
||||
**SDK 收敛条件。** 当前 Android/iOS 使用 Flutter 3.44.9，OHOS 使用 Flutter_OH 3.41.10-ohos-1.0.0；当 Flutter_OH 出现经验证可用的 Flutter 3.44.x / Dart 3.12.x 对齐版本时，可评审统一基线。升级前必须以该候选 SDK 完成依赖解析、Pigeon 与 Riverpod 生成物核验、`flutter build hap --debug -t lib\\main_dev.dart` 和真机原生能力回归；不能仅因版本号相同就替换工具链。
|
||||
|
||||
|
||||
## 使用规则
|
||||
|
||||
- `pigeons/xxx_api.dart` 是**唯一手写**的接口定义文件，Dart 端和两端原生的桩代码全部由 `dart run pigeon --input pigeons/xxx_api.dart` 生成，生成产物不手动修改，改需求就改 schema 重新生成。
|
||||
- Android/iOS 的 `pigeons/xxx_api.dart` 是**唯一手写**的 Pigeon 接口定义文件；Dart 端及 Kotlin/Swift 桩代码全部由 `dart run pigeon --input pigeons/xxx_api.dart` 生成，生成产物不手动修改。OHOS 不手抄 Pigeon wire protocol，而是维护独立、文档化的 `MethodChannel` 契约。
|
||||
- Dart 调原生用 `@HostApi()`；原生主动推事件给 Dart（比如扫码结果的持续回调）用 `@FlutterApi()`——不允许为了图省事用 `@HostApi()` 硬凑双向通信。
|
||||
- **调用方只允许依赖 `native_*` 包 `lib/native_xxx.dart` 导出的公共 API 类**，不允许直接 import `src/generated/` 里的生成代码。调用方包括 `feature_*` 和 `core_webview`（JSBridge）。
|
||||
- `native_*` 是平台分派和异常收敛的唯一位置；Feature、`core_webview`、H5 与 Dart entrypoint 均不得直接创建 OHOS `MethodChannel` 或 import ArkTS 对应实现。
|
||||
- 原生侧异常需要在生成的 host API 实现里捕获并转换成 Pigeon schema 里声明的错误类型，Dart 侧统一映射成 [05-networking.md](./05-networking.md) 里同一套 `AppException` 体系，不让原生异常类型（如 `PlatformException`）直接抛到业务代码里。
|
||||
- 某一端暂未实现的能力，公共 API 类里对应平台分支抛明确的 `UnsupportedPlatformException`，不允许静默返回空值或占位假数据。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user