fix: 隔离鸿蒙SDK特有类型，解决官方SDK编译冲突
- 新增 notification_init_stub.dart 桥接文件，隔离 OhosInitializationSettings - 通知服务使用 buildNotificationInitSettings() 和 requestOhosNotificationPermission() - HomeWidget 的 ohosName 参数通过 dynamic 调用隔离 - file_picker 升级到 ^11.0.0，API 从 FilePicker.platform.pickFiles 改为 FilePicker.pickFiles - flutter_secure_storage 升级到 ^10.2.0 - macos/Podfile 部署目标从 10.15 升级到 13.0 - 更新 iOS_macOS_Developer_Guide.md v3
This commit is contained in:
Developer
@@ -111,7 +111,7 @@ Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'
|
||||
| 包名 | 远程版本号 | 说明 |
|
||||
|---|---|---|
|
||||
| shared_preferences | ^2.5.5 | 轻量KV持久化 |
|
||||
| flutter_secure_storage | ^9.2.4 | 加密安全存储 |
|
||||
| flutter_secure_storage | ^10.2.0 | 加密安全存储 |
|
||||
| hive_flutter | ^1.1.0 | Hive Flutter适配 |
|
||||
| path_provider | ^2.1.5 | 系统目录路径获取 |
|
||||
| package_info_plus | ^10.1.0 | 应用包信息读取 |
|
||||
@@ -122,11 +122,11 @@ Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'
|
||||
| url_launcher | ^6.3.2 | 打开外部URL/应用 |
|
||||
| app_links | ^7.0.0 | 深度链接处理 |
|
||||
| home_widget | ^0.9.1 | iOS/Android桌面小组件 |
|
||||
| file_picker | ^8.3.7 | 文件选择器 |
|
||||
| file_picker | ^11.0.0 | 文件选择器（⚠️ API变更，见§2.5） |
|
||||
| image_picker | ^1.2.2 | 相机/相册选图 |
|
||||
| share_plus | ^13.1.0 | 系统分享面板 |
|
||||
| gal | ^2.3.0 | 保存图片/视频到相册 |
|
||||
| pro_image_editor | ^12.4.4 | 图片编辑器核心 |
|
||||
| pro_image_editor | 本地包（含魔改） | 图片编辑器核心（⚠️ 需本地包，见§2.5） |
|
||||
| flutter_quill | ^11.5.0 | Quill富文本编辑器 |
|
||||
| flex_color_picker | ^3.8.0 | HSL颜色选择器 |
|
||||
| flutter_image_compress | ^2.4.0 | 图片压缩 |
|
||||
@@ -157,6 +157,7 @@ MacBook Pro 端不需要 `dependency_overrides` 中的本地包覆盖，改为
|
||||
dependency_overrides:
|
||||
meta: ^1.17.0
|
||||
web: ^1.1.0
|
||||
win32: ^6.0.1
|
||||
# 删除所有 path: packages/xxx 条目
|
||||
```
|
||||
|
||||
@@ -209,22 +210,64 @@ extended_image ^10.0.1 | photo_view ^0.15.0
|
||||
git clone <仓库URL> xianyan
|
||||
cd xianyan
|
||||
|
||||
# 2. 修改 pubspec.yaml（替换本地包为远程版本）
|
||||
# 参见 §2.2 的替换清单
|
||||
# 2. 解压 pro_image_editor 本地包到 packages/ 目录
|
||||
# （从共享位置获取 pro_image_editor.zip）
|
||||
unzip pro_image_editor.zip -d packages/
|
||||
# 确保 packages/pro_image_editor/ 目录存在且包含 pubspec.yaml
|
||||
|
||||
# 3. 获取依赖
|
||||
# 3. 修改 pubspec.yaml（替换本地包为远程版本）
|
||||
# 参见 §2.2 的替换清单
|
||||
# 注意：pro_image_editor 保持本地包引用（path: packages/pro_image_editor）
|
||||
|
||||
# 4. 获取依赖
|
||||
flutter pub get
|
||||
|
||||
# 4. 编译验证
|
||||
# 5. 编译验证
|
||||
flutter build ios --no-codesign
|
||||
flutter build macos
|
||||
|
||||
# 5. 防止误提交 pubspec.yaml
|
||||
# 6. 防止误提交 pubspec.yaml
|
||||
git stash push -m "macOS-local-pubspec" pubspec.yaml
|
||||
# 或
|
||||
echo "pubspec.yaml" >> .git/info/exclude
|
||||
```
|
||||
|
||||
### 2.5 特殊包说明
|
||||
|
||||
#### 2.5.1 pro_image_editor（含魔改，需本地包）
|
||||
|
||||
`pro_image_editor` 包含项目自定义的 `CanvasStyleModel` 类，远程版本不包含此类型。
|
||||
MacBook Pro 端必须使用本地包版本：
|
||||
|
||||
```yaml
|
||||
# pubspec.yaml 中保持本地包引用
|
||||
pro_image_editor:
|
||||
path: packages/pro_image_editor
|
||||
```
|
||||
|
||||
需要将 `pro_image_editor.zip` 解压到 `packages/pro_image_editor/` 目录。
|
||||
该本地包不包含 `TargetPlatform.ohos` 引用，官方 SDK 编译正常。
|
||||
|
||||
#### 2.5.2 file_picker（API 变更）
|
||||
|
||||
`file_picker ^11.0.0` 的 API 发生了变更：
|
||||
|
||||
```dart
|
||||
// ❌ 旧版 API（file_picker ^8.x）
|
||||
final result = await FilePicker.platform.pickFiles();
|
||||
|
||||
// ✅ 新版 API（file_picker ^11.x）
|
||||
final result = await FilePicker.pickFiles();
|
||||
```
|
||||
|
||||
项目代码已更新为新版 API。鸿蒙端如使用本地包版本（`file_picker ^8.x`），
|
||||
需注意 API 差异，或升级本地包到 `^11.x`。
|
||||
|
||||
#### 2.5.3 flutter_secure_storage（版本升级）
|
||||
|
||||
`flutter_secure_storage ^10.2.0` 的 Windows 平台实现兼容 `win32 ^6.0.1`，
|
||||
解决了之前版本与 `win32 6.x` 的编译冲突。
|
||||
|
||||
---
|
||||
|
||||
## 三、Git 提交与合并规范
|
||||
@@ -449,6 +492,61 @@ if (pu.isDesktop) { /* 桌面端 */ }
|
||||
|
||||
> 以上文件均在 `packages/` 目录中，MacBook Pro 端使用远程版本，不会编译这些文件。
|
||||
|
||||
### 4.5 lib/ 代码中的鸿蒙SDK类型桥接
|
||||
|
||||
鸿蒙端本地包中某些类有官方 SDK 不存在的额外参数或类型（如 `OhosInitializationSettings`、`ohosName`）。
|
||||
项目通过桥接文件和 `dynamic` 调用隔离这些差异，确保两端编译正常。
|
||||
|
||||
#### 4.5.1 通知服务桥接
|
||||
|
||||
**桥接文件**：`lib/core/services/notification/notification_init_stub.dart`
|
||||
|
||||
| 方法 | 官方SDK行为 | 鸿蒙端行为 |
|
||||
|---|---|---|
|
||||
| `buildNotificationInitSettings()` | 构建 `InitializationSettings`（无 ohos 参数） | 鸿蒙端本地包的 `InitializationSettings` 自带 ohos 参数，官方端不传即可 |
|
||||
| `requestOhosNotificationPermission()` | 返回 `false`（不执行） | 动态调用 `OhosFlutterLocalNotificationsPlugin` |
|
||||
|
||||
**使用此桥接的文件**：
|
||||
- `lib/core/services/notification/notification_service.dart`
|
||||
- `lib/core/services/notification/local_notification_service.dart`
|
||||
- `lib/features/file_transfer/services/notification_service.dart`
|
||||
|
||||
#### 4.5.2 HomeWidget 桥接
|
||||
|
||||
鸿蒙端本地包的 `HomeWidget.updateWidget()` 和 `HomeWidget.requestPinWidget()` 有 `ohosName` 参数，
|
||||
官方 SDK 不存在此参数。项目通过 `pu.isOhos` 条件 + `dynamic` 调用隔离：
|
||||
|
||||
```dart
|
||||
// 官方SDK：标准调用
|
||||
await HomeWidget.updateWidget(
|
||||
androidName: type.androidProviderName,
|
||||
iOSName: type.iosWidgetKind,
|
||||
);
|
||||
|
||||
// 鸿蒙端：dynamic 调用，传入 ohosName
|
||||
if (pu.isOhos) {
|
||||
final dynamic updateWidget = HomeWidget.updateWidget;
|
||||
await updateWidget(
|
||||
androidName: type.androidProviderName,
|
||||
iOSName: type.iosWidgetKind,
|
||||
ohosName: type.ohosFormName,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**涉及文件**：
|
||||
- `lib/core/services/data/home_widget_service.dart`
|
||||
- `lib/features/widget/providers/widget_provider.dart`
|
||||
|
||||
#### 4.5.3 新增鸿蒙SDK特有类型的规范
|
||||
|
||||
如果鸿蒙端本地包新增了官方 SDK 不存在的类型或参数，按以下规范处理：
|
||||
|
||||
1. **在 `lib/` 代码中不直接 import 鸿蒙专用类型**（如 `OhosInitializationSettings`）
|
||||
2. **使用 `pu.isOhos` 条件分支**：鸿蒙端逻辑仅在 `pu.isOhos` 为 true 时执行
|
||||
3. **使用 `dynamic` 调用**：绕过官方 SDK 的静态类型检查
|
||||
4. **优先创建桥接文件**：将鸿蒙特有逻辑封装在独立文件中（如 `notification_init_stub.dart`）
|
||||
|
||||
---
|
||||
|
||||
## 五、其他注意事项
|
||||
@@ -493,7 +591,8 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。
|
||||
### 5.4 packages 目录说明
|
||||
|
||||
- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除
|
||||
- **MacBook Pro 端不需要 `packages/` 目录**，直接使用远程版本即可
|
||||
- MacBook Pro 端需要 `packages/pro_image_editor/`（含魔改的 `CanvasStyleModel`），从 zip 解压获取
|
||||
- 其他本地包 MacBook Pro 端使用远程版本，无需放在 `packages/` 目录
|
||||
- 鸿蒙开发者需手动维护本地 `packages/` 目录
|
||||
|
||||
### 5.5 MacBook Pro 修改 ios/macos 后，鸿蒙端是否需要同步？
|
||||
@@ -517,6 +616,10 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。
|
||||
| git pull 后 pubspec.yaml 被覆盖 | 仓库版本是鸿蒙端配置 | 重新替换为远程版本，参见 §3.3.4 |
|
||||
| 误提交了 MacBook Pro 端的 pubspec.yaml | 删除了鸿蒙本地包引用 | 立即回退，恢复鸿蒙端配置 |
|
||||
| 新增依赖后鸿蒙端报错 | 新增的三方库未适配鸿蒙 | 通知鸿蒙开发者评估，必要时本地化到 packages/ |
|
||||
| 编译报 `OhosInitializationSettings` 不存在 | 官方SDK无此类型 | 使用 `notification_init_stub.dart` 桥接，参见 §4.5 |
|
||||
| 编译报 `ohosName` 参数不存在 | 官方SDK的 HomeWidget 无此参数 | 使用 `dynamic` 调用，参见 §4.5.2 |
|
||||
| `pro_image_editor` 报 `CanvasStyleModel` 不存在 | 远程版本不含魔改内容 | 使用本地包 `path: packages/pro_image_editor`，参见 §2.5.1 |
|
||||
| `FilePicker.platform` 报错 | file_picker 11.x API 变更 | 使用 `FilePicker.pickFiles()`，参见 §2.5.2 |
|
||||
|
||||
---
|
||||
|
||||
@@ -527,13 +630,15 @@ MacBook Pro 开发前，确认以下事项：
|
||||
- [ ] 使用官方 Flutter SDK（非 flutter-ohos）
|
||||
- [ ] 已 `git clone` 拉取最新代码
|
||||
- [ ] 已将 `pubspec.yaml` 中的本地包替换为远程版本（参见 §2.2）
|
||||
- [ ] 已解压 `pro_image_editor` 到 `packages/` 目录（参见 §2.5.1）
|
||||
- [ ] `flutter pub get` 无报错
|
||||
- [ ] `flutter build ios --no-codesign` 或 `flutter build macos` 编译通过
|
||||
- [ ] `dart analyze lib/` 无 error
|
||||
- [ ] 新增代码未使用 `switch(TargetPlatform)` 穷举匹配
|
||||
- [ ] 新增鸿蒙SDK特有类型已通过桥接文件隔离（参见 §4.5）
|
||||
- [ ] 新增路由已在 `app_router.dart` 和 `ohos_nav_bridge.dart` 双写
|
||||
- [ ] 已使用 `git stash` 隔离本地 `pubspec.yaml`，不会误提交
|
||||
- [ ] Git 提交未删除 `pu.isOhos` 相关代码
|
||||
|
||||
---
|
||||
|
||||
*文档创建时间: 2026-05-21 | 更新时间: 2026-05-21 v2 | 维护者: 闲言APP开发团队*
|
||||
*文档创建时间: 2026-05-21 | 更新时间: 2026-05-22 v3 | 维护者: 闲言APP开发团队*
|
||||
|
||||
Reference in New Issue
Block a user