520kiss/xianyan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

鸿蒙端作为拉取端提交配置

Browse Source
This commit is contained in:
Developer
2026-06-02 02:31:31 +08:00
parent ba60d8d5be
commit 1cb9bc8649
5 changed files with 667 additions and 3519 deletions
Download Patch File Download Diff File Expand all files Collapse all files

355
iOS_macOS_Developer_Guide.md
View File

@@ -6,6 +6,17 @@
---
## 文档更新日志
| 日期 | 版本 | 变更内容 |
|---|---|---|
| 2026-06-02 | v7 | **重大变更**：pubspec.yaml 拆分为双模板（pubspec.ohos.yaml + pubspec.macos.yaml），pubspec.yaml 不再提交到 Git；新增三方库变更通知机制；新增 setup_pubspec.ps1 脚本 |
| 2026-06-02 | v6 | 鸿蒙端 pubspec.yaml 同步 bitsdojo_window → window_manager 迁移；更新 file_picker 本地包版本注释(v8.3.7→v11.0.0-ohos.1)；更新 speech_to_text(^7.0.0→^7.4.0)、live_activities(^2.0.0→^2.4.9) 远程版本号；补充 dependency_overrides 中 bitsdojo_window_windows 移除说明 |
| 2026-06-01 | v5 | 新增 §2.6 pub cache 补丁说明；标记 bitsdojo_window 迁移完成；file_picker 升级到 12.x |
| 2026-05-30 | v4 | 初版完整指南 |
---
## 一、环境准备与项目拉取
### 1.1 Flutter SDK 选择
@@ -35,15 +46,21 @@ git checkout feature/xxx
git checkout main
```
### 1.3 修改 pubspec.yaml 并安装依赖
### 1.3 生成 pubspec.yaml 并安装依赖
MacBook Pro 端需要将 `pubspec.yaml` 中的本地包引用替换为远程版本号（详见 §2.2）。
> ⚠️ **`pubspec.yaml` 不再提交到 Git**。项目使用双模板机制：
> - `pubspec.ohos.yaml` — 鸿蒙端模板（使用本地 packages/ 目录）
> - `pubspec.macos.yaml` — MacBook Pro 端模板（使用远程版本号）
> - `pubspec.yaml` — 由脚本自动生成，已加入 `.gitignore`
```bash
# 1. 确认使用官方 Flutter SDK
flutter --version # 应显示官方版本，非 flutter-ohos
# 2. 修改 pubspec.yaml（参见 §2.2 替换清单）
# 2. 运行脚本生成 pubspec.yaml（MacBook Pro 端）
.\tools\setup_pubspec.ps1 -Platform macos
# 或自动检测平台
.\tools\setup_pubspec.ps1
# 3. 获取依赖
flutter pub get
@@ -53,23 +70,53 @@ flutter build ios --no-codesign
# 5. macOS 编译验证
flutter build macos
```
# 5. 防止误提交 pubspec.yaml
git stash push -m "macOS-local-pubspec" pubspec.yaml
鸿蒙端开发者：
```bash
# 1. 确认使用 flutter-ohos SDK
flutter --version # 应显示 ohos 版本
# 2. 运行脚本生成 pubspec.yaml（鸿蒙端）
.\tools\setup_pubspec.ps1 -Platform ohos
# 3. 获取依赖
flutter pub get
```
---
## 二、pubspec.yaml 与三方库
## 二、pubspec.yaml 双模板机制
### 2.1 MacBook Pro 端的核心原则
### 2.1 架构概述
> **`pubspec.yaml` 不再提交到 Git**，两端各自维护独立的模板文件。
```
项目根目录/
├── pubspec.ohos.yaml ← 鸿蒙端模板（tracked，使用本地 packages/ 目录）
├── pubspec.macos.yaml ← MacBook Pro 端模板（tracked，使用远程版本号）
├── pubspec.yaml ← 本地生成文件（.gitignore，不提交）
└── tools/
└── setup_pubspec.ps1 ← 自动生成脚本
```
**为什么这样做？**
之前鸿蒙端和 MacBook Pro 端共用一个 `pubspec.yaml`，MacBook Pro 端每次 `git pull` 后需要手动替换 82 行本地包引用，容易出错且经常互相覆盖。
现在：
- 鸿蒙端模板 `pubspec.ohos.yaml` 包含所有 `path: packages/` 引用
- MacBook Pro 端模板 `pubspec.macos.yaml` 使用远程版本号
- `pubspec.yaml` 由脚本自动生成，两边都不提交
### 2.2 MacBook Pro 端的核心原则
> **MacBook Pro 端不需要 `packages/` 目录，直接使用远程三方库即可。**
项目 `pubspec.yaml` 中的本地包引用（`path: packages/xxx`）是为鸿蒙端准备的。
MacBook Pro 端使用官方 Flutter SDK，需要将这些本地包引用替换为远程版本号。
`pubspec.macos.yaml` 已将所有本地包引用替换为远程版本号，无需手动修改。
**为什么不能直接用本地包？**
**为什么不能直接用鸿蒙端的本地包？**
本地包中包含 `TargetPlatform.ohos` 引用（鸿蒙SDK新增的枚举值），官方 SDK 没有此值，会导致编译报错：
@@ -89,154 +136,136 @@ Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'
**解决方案**：MacBook Pro 端使用远程版本，远程版本不含 `TargetPlatform.ohos`，编译正常。
### 2.2 MacBook Pro 端 pubspec.yaml 修改指南
### 2.3 双模板差异对照表
克隆项目后，需要修改 `pubspec.yaml`，将本地包引用替换为远程版本号。
#### 2.2.1 dependencies 区域 — 需要替换的包
将以下包从 `path: packages/xxx` 改为版本号：
```yaml
# ❌ 原始写法（鸿蒙端）
shared_preferences:
path: packages/shared_preferences
# ✅ MacBook Pro 端改为远程版本
shared_preferences: ^2.5.5
```
**完整替换清单：**
| 包名 | 远程版本号 | 说明 |
| 区域 | pubspec.ohos.yaml（鸿蒙端） | pubspec.macos.yaml（MacBook Pro端） |
|---|---|---|
| shared_preferences | ^2.5.5 | 轻量KV持久化 |
| flutter_secure_storage | ^10.2.0 | 加密安全存储 |
| hive_flutter | ^1.1.0 | Hive Flutter适配 |
| path_provider | ^2.1.5 | 系统目录路径获取 |
| package_info_plus | ^10.1.0 | 应用包信息读取 |
| connectivity_plus | ^7.1.1 | 网络连接状态监听 |
| device_info_plus | ^13.1.0 | 设备硬件信息读取 |
| permission_handler | ^12.0.1 | 运行时权限请求 |
| flutter_local_notifications | ^21.0.0 | 本地推送通知 |
| url_launcher | ^6.3.2 | 打开外部URL/应用 |
| app_links | ^7.0.0 | 深度链接处理 |
| home_widget | ^0.9.1 | iOS/Android桌面小组件 |
| file_picker | ^12.0.0-beta.5 | 文件选择器（⚠️ 12.x兼容win32 6.x，见§2.6） |
| image_picker | ^1.2.2 | 相机/相册选图 |
| share_plus | ^13.1.0 | 系统分享面板 |
| gal | ^2.3.0 | 保存图片/视频到相册 |
| pro_image_editor | ^12.4.4 | 图片编辑器核心（⚠️ 见§2.5） |
| flutter_quill | ^11.5.0 | Quill富文本编辑器 |
| flex_color_picker | ^3.8.0 | HSL颜色选择器 |
| flutter_image_compress | ^2.4.0 | 图片压缩 |
| wakelock_plus | ^1.4.0 | 屏幕常亮控制 |
| audioplayers | ^6.5.0 | 音频播放 |
| record | ^6.0.0 | 录音 |
| video_compress | ^3.1.2 | 视频压缩 |
| video_player | ^2.10.0 | 视频播放 |
| local_auth | ^3.0.1 | 生物识别认证 |
| sensors_plus | ^6.1.0 | 加速度传感器 |
| battery_plus | ^7.0.0 | 电池状态监听 |
| network_info_plus | ^8.1.0 | WiFi网络信息 |
| flutter_webrtc | ^1.4.0 | WebRTC音视频通信 |
| flutter_blue_plus | ^2.1.0 | 蓝牙BLE通信 |
| flutter_nfc_kit | ^3.6.0 | NFC读写 |
| mobile_scanner | ^7.1.4 | 二维码/条形码扫描 |
| wifi_iot | ^0.3.19 | WiFi IoT设备连接 |
| nearby_service | ^0.2.1 | 近场设备发现+通信 |
| sqflite | ^2.4.1 | SQLite轻量数据库 |
| receive_sharing_intent | git引用 | 接收外部分享内容（⚠️ gitcode引用，见§2.5） |
| workmanager | ^0.9.0 | 后台任务调度 |
| flutter_tts | ^4.2.0 | TTS文本转语音朗读 |
| speech_to_text | ^7.0.0 | 语音转文字 |
| live_activities | ^2.0.0 | 灵动岛/实时活动 |
| flutter_vibrate | git引用 | 跨平台触觉反馈（⚠️ gitcode引用，见§2.5） |
| bitsdojo_window | - | ❌ 已移除，替换为 window_manager（lib/代码已迁移完成） |
| window_manager | ^0.5.1 | 桌面端窗口管理（替代 bitsdojo_window，已集成） |
| shared_preferences | `path: packages/shared_preferences` | `^2.5.5` |
| flutter_secure_storage | `path: packages/flutter_secure_storage` | `^10.2.0` |
| hive_flutter | `path: packages/hive_flutter` | `^1.1.0` |
| path_provider | `path: packages/path_provider` | `^2.1.5` |
| package_info_plus | `path: packages/package_info_plus` | `^10.1.0` |
| connectivity_plus | `path: packages/connectivity_plus` | `^7.1.1` |
| device_info_plus | `path: packages/device_info_plus` | `^13.1.0` |
| permission_handler | `path: packages/permission_handler` | `^12.0.1` |
| flutter_local_notifications | `path: packages/flutter_local_notifications` | `^21.0.0` |
| url_launcher | `path: packages/url_launcher` | `^6.3.2` |
| app_links | `path: packages/app_links` | `^7.0.0` |
| home_widget | `git: gitcode.com/...` | `^0.9.1` |
| file_picker | `path: packages/file_picker` | `^12.0.0-beta.5` |
| image_picker | `path: packages/image_picker` | `^1.2.2` |
| share_plus | `path: packages/share_plus` | `^13.1.0` |
| gal | `path: packages/gal` | `^2.3.0` |
| flutter_quill | `path: packages/flutter_quill` | `^11.5.0` |
| flex_color_picker | `path: packages/flex_color_picker` | `^3.8.0` |
| flutter_image_compress | `path: packages/flutter_image_compress` | `^2.4.0` |
| wakelock_plus | `path: packages/wakelock_plus` | `^1.4.0` |
| audioplayers | `path: packages/audioplayers` | `^6.5.0` |
| record | `path: packages/record` | `^6.0.0` |
| video_compress | `path: packages/video_compress` | `^3.1.2` |
| video_player | `path: packages/video_player` | `^2.10.0` |
| local_auth | `path: packages/local_auth` | `^3.0.1` |
| sensors_plus | `path: packages/sensors_plus` | `^6.1.0` |
| battery_plus | `path: packages/battery_plus` | `^7.0.0` |
| network_info_plus | `path: packages/network_info_plus` | `^8.1.0` |
| flutter_webrtc | `path: packages/flutter_webrtc` | `^1.4.0` |
| flutter_blue_plus | `path: packages/flutter_blue_plus` | `^2.1.0` |
| flutter_nfc_kit | `path: packages/flutter_nfc_kit` | `^3.6.0` |
| mobile_scanner | `path: packages/mobile_scanner` | `^7.1.4` |
| wifi_iot | `path: packages/wifi_iot` | `^0.3.19` |
| nearby_service | `path: packages/nearby_service` | `^0.2.1` |
| sqflite | `path: packages/sqflite` | `^2.4.1` |
| workmanager | `path: packages/workmanager` | `^0.9.0` |
| flutter_tts | `path: packages/flutter_tts` | `^4.2.0` |
| speech_to_text | `path: packages/speech_to_text` | `^7.4.0` |
| live_activities | `path: packages/live_activities` | `^2.4.9` |
| dependency_overrides | 40+ 行（含本地包覆盖 + ohos 子包） | 4 行（仅版本号覆盖 + win32） |
#### 2.2.2 dependency_overrides 区域 — 整体替换
### 2.4 ⚠️ 新增三方库变更流程（必读）
MacBook Pro 端不需要 `dependency_overrides` 中的本地包覆盖，改为仅保留版本号覆盖：
```yaml
# MacBook Pro 端的 dependency_overrides（精简版）
dependency_overrides:
meta: ^1.17.0
web: ^1.1.0
timezone: ^0.11.0
win32: ^6.0.1
# 删除所有 path: packages/xxx 条目
```
#### 2.2.3 快速替换脚本
```bash
# 在项目根目录执行，自动将本地包引用替换为远程版本
# ⚠️ 执行前请备份 pubspec.yaml
# 方式1：手动替换（推荐，更可控）
# 用编辑器打开 pubspec.yaml，搜索 "path: packages/" 逐个替换
# 方式2：使用 sed 批量替换（macOS 终端）
# 将所有 "path: packages/xxx" 行替换为对应版本号
# 注意：此脚本仅作参考，请根据实际版本号调整
```
#### 2.2.4 ⚠️ 重要：不要提交修改后的 pubspec.yaml
```bash
# 修改 pubspec.yaml 后，使用 git stash 暂存，不要提交
git stash push -m "macOS-local-pubspec" pubspec.yaml
# 需要恢复时
git stash pop
# 或者将修改后的 pubspec.yaml 加入 .git/info/exclude
echo "pubspec.yaml" >> .git/info/exclude
```
> **铁律**：MacBook Pro 端对 `pubspec.yaml` 的修改**绝对不能提交到 Git**。
> 仓库中的 `pubspec.yaml` 必须保持鸿蒙端的本地包引用配置。
### 2.3 已迁移至远程版本的纯Dart包
以下包已从本地包迁移为远程版本依赖，两端无需额外操作：
> **铁律：新增三方库时，必须同时更新两个模板 + 本文档。**
```
badges ^3.2.0 | catcher_2 ^2.1.9 | flutter_card_swiper ^7.2.0
stupid_simple_sheet ^0.9.1+1 | liquid_glass_easy ^1.1.1
liquid_glass_widgets ^0.11.0 | flutter_shaders_ui ^0.1.0
flutter_spritesheet_animation ^1.0.1 | image_size_getter ^2.4.1
extended_image ^10.0.1 | photo_view ^0.15.0
新增三方库流程：
1. 在 pubspec.ohos.yaml 添加依赖（鸿蒙端优先）
2. 在 pubspec.macos.yaml 添加对应远程版本
3. 在本文档 §2.3 差异对照表添加一行
4. 在本文档顶部更新日志记录变更
5. 在 CHANGELOG.md 记录变更
6. git push 后通知另一端开发者
7. 另一端开发者: git pull → 运行 setup_pubspec.ps1 → flutter pub get
```
### 2.4 MacBook Pro 端完整操作流程
**鸿蒙端新增本地化包时额外步骤：**
- 将包放入 `packages/` 目录
- 在 `pubspec.ohos.yaml` 的 `dependency_overrides` 中添加覆盖
- 在 `pubspec.macos.yaml` 中使用远程版本号
- 更新本文档 §2.3 差异对照表
**升级三方库版本时：**
- 在对应模板中更新版本号
- 如果是鸿蒙本地包升级，同步更新 `pubspec.ohos.yaml` 中的版本注释
- 更新本文档 §2.3 差异对照表中的版本号
### 2.5 setup_pubspec.ps1 脚本说明
```powershell
# 鸿蒙端
.\tools\setup_pubspec.ps1 -Platform ohos
# MacBook Pro 端
.\tools\setup_pubspec.ps1 -Platform macos
# 自动检测（根据 flutter --version 或 packages/ 目录是否存在）
.\tools\setup_pubspec.ps1
```
脚本功能：
- 将对应模板复制为 `pubspec.yaml`
- 自动备份现有 `pubspec.yaml` → `pubspec.yaml.bak`
- 验证模板内容（鸿蒙端检查 `path: packages/`，MacBook Pro 端检查无本地包引用）
- 输出后续操作提示
### 2.6 MacBook Pro 端完整操作流程
```bash
# 1. 克隆仓库
git clone <仓库URL> xianyan
cd xianyan
# 2. 修改 pubspec.yaml（替换本地包为远程版本）
# 参见 §2.2 的替换清单
# 2. 生成 pubspec.yaml
.\tools\setup_pubspec.ps1 -Platform macos
# 3. 获取依赖
flutter pub get
# 4. 编译验证
# 4. 应用 pub cache 补丁（见 §2.8）
bash scripts/patch_pub_cache.sh
# 5. 编译验证
flutter build ios --no-codesign
flutter build macos
# 6. 防止误提交 pubspec.yaml
git stash push -m "macOS-local-pubspec" pubspec.yaml
# 或
echo "pubspec.yaml" >> .git/info/exclude
```
### 2.5 特殊包说明
### 2.7 鸿蒙端完整操作流程
#### 2.5.1 pro_image_editor（已迁移至远程版本）
```bash
# 1. 克隆仓库
git clone <仓库URL> xianyan
cd xianyan
# 2. 确保 packages/ 目录已准备好（从 zip 解压或 git submodule）
# 3. 生成 pubspec.yaml
.\tools\setup_pubspec.ps1 -Platform ohos
# 4. 获取依赖
flutter pub get
```
### 2.8 特殊包说明
#### 2.8.1 pro_image_editor（已迁移至远程版本）
`pro_image_editor` 已从本地包迁移为远程版本 `^12.4.4`，MacBook Pro 端直接使用远程版本即可：
@@ -249,7 +278,7 @@ echo "pubspec.yaml" >> .git/info/exclude
> 远程版本可能不包含此类型，需要检查兼容性。
> 如遇编译错误，可恢复使用本地包版本（`path: packages/pro_image_editor`）。
#### 2.5.2 file_picker（API 变更 + win32 6.x 兼容）
#### 2.8.2 file_picker（API 变更 + win32 6.x 兼容）
`file_picker` 已从 `^11.0.0` 升级为 `^12.0.0-beta.5`，原因：
@@ -268,15 +297,19 @@ final result = await FilePicker.pickFiles();
- `file_picker ^12.0.0-beta.5` 兼容 `win32 ^6.0.1`，解决 macOS 构建失败
- ⚠️ 12.x 为 beta 版本，如遇问题可回退到 11.x（需同时降级 win32 override，见§2.6）
项目代码已更新为新版 API。鸿蒙端如使用本地包版本（`file_picker ^8.x`），
需注意 API 差异，或升级本地包到 `^11.x`。
项目代码已更新为新版 API。鸿蒙端本地包版本已升级为 `11.0.0-ohos.1`（基于 file_picker 11.x 适配），
API 已与远程版本对齐，无需额外处理。
#### 2.5.3 flutter_secure_storage（版本升级）
#### 2.8.3 flutter_secure_storage（版本差异说明）
`flutter_secure_storage ^10.2.0` 的 Windows 平台实现兼容 `win32 ^6.0.1`，
MacBook Pro 端使用远程版本 `^10.2.0`，其 Windows 平台实现兼容 `win32 ^6.0.1`，
解决了之前版本与 `win32 6.x` 的编译冲突。
#### 2.5.4 receive_sharing_intent（gitcode 引用）
> **注意**：鸿蒙端本地包版本为 `9.2.4-ohos.1`（基于 9.x 适配），
> 与 MacBook Pro 端远程版本 `10.2.0` 存在主版本号差异。
> 两端 API 兼容，`lib/` 代码无需特殊处理。
#### 2.8.4 receive_sharing_intent（gitcode 引用）
`receive_sharing_intent` 在 pub.dev 上的版本与鸿蒙端不兼容，MacBook Pro 端需使用 gitcode 引用：
@@ -291,7 +324,7 @@ final result = await FilePicker.pickFiles();
> **注意**：gitcode 版本的 `SharedMediaFile` 构造函数可能包含 `ohosPath` 等鸿蒙特有参数，
> 官方 SDK 不存在这些参数。项目代码中已通过 `pu.isOhos` 条件分支隔离。
#### 2.5.5 flutter_vibrate（gitcode 引用）
#### 2.8.5 flutter_vibrate（gitcode 引用）
`flutter_vibrate` 在 pub.dev 上的版本不支持鸿蒙，MacBook Pro 端需使用 gitcode 引用：
@@ -302,7 +335,7 @@ final result = await FilePicker.pickFiles();
url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_vibrate.git
```
#### 2.5.6 home_widget（pub.dev 远程版本）
#### 2.8.6 home_widget（pub.dev 远程版本）
`home_widget` 的 gitcode 版本依赖 `path_provider` 的 git 版本，会与远程 `path_provider` 冲突。
MacBook Pro 端使用 pub.dev 版本 `^0.9.1`，鸿蒙端的 `ohosName` 参数通过 `pu.isOhos` + `dynamic` 调用隔离：
@@ -312,20 +345,20 @@ MacBook Pro 端使用 pub.dev 版本 `^0.9.1`，鸿蒙端的 `ohosName` 参数
home_widget: ^0.9.1
```
### 2.6 ⚠️ pub cache 补丁（MacBook Pro 端必读）
### 2.9 ⚠️ pub cache 补丁（MacBook Pro 端必读）
> **关键问题**：`dependency_overrides` 中 `win32: ^6.0.1` 导致部分依赖 `win32 ^5.x` 的三方包编译失败。
> 这些三方包的 Windows 平台代码在 macOS 构建时也会被编译（Dart 编译器不区分平台）。
> 需要手动修补 pub cache 中的文件，使它们兼容 win32 6.x API。
#### 2.6.1 需要修补的包
#### 2.9.1 需要修补的包
| 包名 | 版本 | 问题 | 修补文件 |
|---|---|---|---|
| quill_native_bridge_windows | 0.0.2 | 使用 win32 5.x API（`TEXT()`、`OpenClipboard(NULL)==FALSE` 等） | `lib/quill_native_bridge_windows.dart` + `lib/src/clipboard_html_format.dart` |
| flutter_vibrate | gitcode | `TARGET_OS_SIMULATOR` 在 Xcode 16+/Swift 6 中不可用 | `ios/Classes/SwiftVibratePlugin.swift` |
#### 2.6.2 补丁应用流程
#### 2.9.2 补丁应用流程
```bash
# 1. 确保 flutter pub get 已执行
@@ -341,7 +374,7 @@ flutter build ios --no-codesign
> ⚠️ `flutter clean` 或 `flutter pub cache repair` 会清除补丁，需重新执行步骤 2。
#### 2.6.3 补丁脚本
#### 2.9.3 补丁脚本
在项目根目录创建 `scripts/patch_pub_cache.sh`（已包含在仓库中），内容如下：
@@ -662,7 +695,7 @@ echo "🎉 All patches applied!"
echo "⚠️ Note: Run this script again after 'flutter clean' or 'flutter pub cache repair'"
```
#### 2.6.4 win32 5.x → 6.x API 迁移参考
#### 2.9.4 win32 5.x → 6.x API 迁移参考
如需修补其他使用 win32 的三方包，以下是关键 API 变更：
@@ -1010,10 +1043,14 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。
### 5.4 packages 目录说明
- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除
- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除（`/packages/`）
- MacBook Pro 端需要 `packages/pro_image_editor/`（含魔改的 `CanvasStyleModel`），从 zip 解压获取
- 其他本地包 MacBook Pro 端使用远程版本，无需放在 `packages/` 目录
- 鸿蒙开发者需手动维护本地 `packages/` 目录
- `packages/bitsdojo_window_windows/` 已随 bitsdojo_window 移除而废弃，可安全删除
- ⚠️ `pubspec.yaml` 已加入 `.gitignore`，不再提交到 Git
- 鸿蒙端模板：`pubspec.ohos.yaml`，MacBook Pro 端模板：`pubspec.macos.yaml`
- 使用 `tools/setup_pubspec.ps1` 生成 `pubspec.yaml`
### 5.5 MacBook Pro 修改 ios/macos 后，鸿蒙端是否需要同步？
@@ -1022,24 +1059,30 @@ iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。
| `ios/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
| `macos/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
| `lib/` 目录 | ✅ 需要同步 | Dart 代码所有平台共用 |
| `pubspec.yaml` | ✅ 需要同步 | 依赖配置共享（鸿蒙端自行维护本地包版本） |
| `pubspec.ohos.yaml` | ✅ 鸿蒙端模板 | 鸿蒙端依赖配置 |
| `pubspec.macos.yaml` | ✅ MacBook Pro端模板 | MacBook Pro端依赖配置 |
| `pubspec.yaml` | ❌ 不提交 | 已加入 .gitignore，本地生成 |
| `assets/` 目录 | ✅ 需要同步 | 资源文件共享 |
> **实际案例**：`bitsdojo_window → window_manager` 迁移时，MacBook Pro 端先完成代码和依赖替换，
> 鸿蒙端随后同步更新 `pubspec.yaml`（移除 `bitsdojo_window`，添加 `window_manager`），
> 并删除 `packages/bitsdojo_window_windows/` 废弃目录。
### 5.6 常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| `flutter pub get` 报 packages/xxx 目录不存在 | pubspec.yaml 中有 `path: packages/xxx` 引用 | 替换为远程版本号，参见 §2.2 |
| 编译报 `TargetPlatform.ohos` 不存在 | 使用了含 ohos 引用的本地包 | 使用远程版本，参见 §2.1 |
| `flutter pub get` 报 packages/xxx 目录不存在 | pubspec.yaml 是鸿蒙端模板 | MacBook Pro端运行 `.\tools\setup_pubspec.ps1 -Platform macos` |
| 编译报 `TargetPlatform.ohos` 不存在 | 使用了含 ohos 引用的本地包 | 确认使用 `pubspec.macos.yaml` 生成的 pubspec.yaml |
| iOS 编译报 ohos 相关错误 | 误用鸿蒙SDK编译iOS | 切换到官方 Flutter SDK |
| GoRouter 路由正常但鸿蒙端白屏 | 鸿蒙端不支持 GoRouter | 检查 OhosNavBridge 路由映射 |
| git pull 后 pubspec.yaml 被覆盖 | 仓库版本是鸿蒙端配置 | 重新替换为远程版本，参见 §3.3.4 |
| 误提交了 MacBook Pro 端的 pubspec.yaml | 删除了鸿蒙本地包引用 | 立即回退，恢复鸿蒙端配置 |
| git pull 后 pubspec.yaml 被覆盖 | pubspec.yaml 已在 .gitignore | 重新运行 `.\tools\setup_pubspec.ps1` |
| 新增依赖后另一端报错 | 只更新了一个模板 | 必须同时更新两个模板 + 文档，参见 §2.4 |
| 新增依赖后鸿蒙端报错 | 新增的三方库未适配鸿蒙 | 通知鸿蒙开发者评估，必要时本地化到 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 |
| `pro_image_editor` 报 `CanvasStyleModel` 不存在 | 远程版本不含魔改内容 | 使用本地包 `path: packages/pro_image_editor`，参见 §2.8.1 |
| `FilePicker.platform` 报错 | file_picker 11.x API 变更 | 使用 `FilePicker.pickFiles()`，参见 §2.8.2 |
---

3354
pubspec.lock
View File

File diff suppressed because it is too large Load Diff

323
pubspec.macos.yaml Normal file
View File

@@ -0,0 +1,323 @@
# ============================================================
# 闲言APP (Xianyan) — MacBook Pro端 pubspec 模板
# 创建时间: 2026-06-02
# 更新时间: 2026-06-02
# 作用: MacBook Pro端(iOS/macOS)依赖与资源配置模板（使用远程版本号）
# 上次更新: 从鸿蒙端模板派生，本地包替换为远程版本号，dependency_overrides精简
# 使用方式: 运行 tools/setup_pubspec.ps1 --platform macos 自动生成 pubspec.yaml
# ⚠️ 此文件为模板，不要直接重命名为 pubspec.yaml 使用
# ⚠️ 新增三方库时，必须同步更新 pubspec.ohos.yaml 和 pubspec.macos.yaml
# ============================================================
name: xianyan
description: "闲言 — 文字阅读更纯粹。句子阅读 + 壁纸制作 APP"
publish_to: 'none'
version: 6.6.2+26060202
# 年月日-次 8位
environment:
sdk: ^3.11.5
# ============================================================
# 依赖 — MacBook Pro端使用远程版本号
# ============================================================
dependencies:
flutter:
sdk: flutter
# iOS 风格图标
cupertino_icons: ^1.0.8 # iOS风格图标库
# --- 状态管理 + 依赖注入 ---
flutter_riverpod: ^3.0.0 # 响应式状态管理+依赖注入
riverpod_annotation: ^4.0.0 # Riverpod代码生成注解
# --- 路由 ---
go_router: ^17.2.3 # 声明式路由导航(纯Dart-鸿蒙零适配)
# --- 网络请求 ---
dio: ^5.4.0 # HTTP客户端+拦截器
dio_cache_interceptor: ^3.5.0 # Dio HTTP缓存拦截器
http_cache_file_store: ^2.0.1 # 文件系统缓存存储
# --- 本地数据库 ---
drift: ^2.16.0 # 类型安全SQLite ORM
sqlite3_flutter_libs: ^0.5.0 # SQLite原生库绑定
# --- 数据模型 ---
freezed_annotation: ^3.0.0 # 不可变数据类注解
json_annotation: ^4.9.0 # JSON序列化注解
# --- KV 存储 ---
shared_preferences: ^2.5.5 # 轻量KV持久化
flutter_secure_storage: ^10.2.0 # 加密安全存储
hive_ce: ^2.0.0 # 高性能NoSQL数据库(社区维护版)
hive_flutter: ^1.1.0 # Hive Flutter适配
# --- 文件路径 ---
path_provider: ^2.1.5 # 系统目录路径获取
path: ^1.9.0 # 路径操作工具
# --- 工具 ---
uuid: ^4.5.0 # UUID生成器
intl: ^0.20.2 # 国际化+日期格式化
timeago: ^3.7.0 # 相对时间格式化(国际化)
logger: ^2.5.0 # 分级日志输出
collection: ^1.19.0 # 集合操作扩展
dartx: ^1.2.0 # 集合安全扩展方法(firstOrNull/getOrNull等)
syncfusion_flutter_charts: ^28.1.36 # Syncfusion图表库(替代fl_chart)
# --- 设备信息 ---
package_info_plus: ^10.1.0 # 应用包信息读取
connectivity_plus: ^7.1.1 # 网络连接状态监听
device_info_plus: ^13.1.0 # 设备硬件信息读取
# --- 日历同步 ---
device_calendar: ^4.3.3 # 跨平台日历事件读写
# --- 权限 ---
permission_handler: ^12.0.1 # 运行时权限请求
# --- 本地通知 ---
flutter_local_notifications: ^21.0.0 # 本地推送通知
# --- 后台任务调度 ---
workmanager: ^0.9.0 # 后台任务调度
# --- 外部链接 ---
url_launcher: ^6.3.2 # 打开外部URL/应用
app_links: ^7.0.0 # 深度链接处理
# --- 快捷操作 ---
quick_actions: ^1.1.0 # 主屏幕快捷操作(iOS Quick Actions / Android App Shortcuts)
# --- 桌面小组件 ---
home_widget: ^0.9.1 # iOS/Android桌面小组件
# --- iOS 26 Liquid Glass 组件 ---
liquid_glass_widgets: ^0.11.0 # iOS26液态玻璃组件库
liquid_glass_easy: ^1.1.1 # 液态玻璃效果封装
# --- 底部面板 + Hero 动画 ---
stupid_simple_sheet: ^0.9.1+1 # 简易底部弹出面板
heroine: ^0.7.2 # Hero过渡动画增强
file_picker: ^12.0.0-beta.5 # 文件选择器(⚠️ 12.x兼容win32 6.x，见iOS_macOS_Developer_Guide.md §2.6)
image_picker: ^1.2.2 # 相机/相册选图
adaptive_palette: ^3.0.0 # 图片主色提取+流体背景
# --- UI 基础 ---
badges: ^3.2.0 # 角标/徽章组件
google_fonts: ^8.1.0 # Google字体加载
cached_network_image: ^3.3.0 # 网络图片缓存+占位
flutter_cache_manager: ^3.3.0 # 文件缓存管理
shimmer: ^3.0.0 # 骨架屏加载占位
# --- 分享 + 导出 ---
share_plus: ^13.1.0 # 系统分享面板
qr_flutter: ^4.1.0 # 二维码渲染
gal: ^2.3.0 # 保存图片/视频到相册
archive: ^4.0.0 # ZIP压缩/解压
crypto: ^3.0.0 # 加密哈希算法
encrypt: ^5.0.3 # 对称/非对称加密
mailer: ^7.1.0 # SMTP邮件发送
# --- 图片处理 ---
image: ^4.3.0 # 图片解码/编码/变换
# --- 图片编辑器 ---
pro_image_editor: ^12.4.4 # 图片编辑器核心(官方版)
# --- 桌面端增强 ---
desktop_drop: ^0.5.0 # 桌面端文件拖放接收
window_manager: ^0.5.1 # 桌面端窗口管理(替代bitsdojo_window)
# --- 异常捕获 ---
catcher_2: ^2.1.9 # 全局异常捕获+上报
# --- SVG 渲染 ---
flutter_svg: ^2.0.0 # SVG图片渲染
# --- 富文本编辑器 ---
flutter_quill: ^11.5.0 # Quill富文本编辑器
# --- 虚线边框 ---
dotted_border: ^3.1.0 # 虚线/点线边框装饰
# --- 颜色选择器 ---
flex_color_picker: ^3.8.0 # HSL颜色选择器
# --- 键盘可见性 ---
flutter_keyboard_visibility: ^6.0.0 # 键盘可见性监听(替代MediaQuery轮询)
# --- 屏幕适配 ---
flutter_screenutil: ^5.9.0 # 屏幕尺寸适配
# --- 动画 ---
rive: ^0.14.7 # Rive交互式动画引擎
flutter_animate: ^4.5.0 # 声明式动画库
flutter_card_swiper: ^7.2.0 # 卡片滑动切换
animations: ^2.0.11 # Material过渡动画
lottie: ^3.3.0 # Lottie动画播放
confetti: ^0.8.0 # 撒花/彩纸效果
animate_do: ^5.1.0 # 常用入场/出场动画
# --- 交互增强 ---
custom_refresh_indicator: ^4.0.1 # 自定义下拉刷新
# --- 列表交互 ---
flutter_slidable: ^4.0.3 # 列表项滑动操作
flutter_sticky_header: ^0.8.0 # 粘性头部
flutter_staggered_animations: ^1.1.1 # 列表交错入场动画
value_layout_builder: ^0.5.0 # 值变化触发布局重建
# --- 内容渲染 ---
flutter_markdown_plus: ^1.0.1 # Markdown渲染
flutter_html: ^3.0.0-beta.2 # HTML内容渲染
# --- RSS订阅 ---
rss_dart: ^1.0.12 # RSS/Atom订阅源解析(Dart3兼容webfeed分支)
# --- 拼音转换 ---
pinyin: ^3.3.0 # 汉字转拼音
# --- 语音朗读 ---
flutter_tts: ^4.2.0 # TTS文本转语音朗读
# --- 语音识别 ---
speech_to_text: ^7.4.0 # 语音转文字
# --- 灵动岛/实时活动 ---
live_activities: ^2.4.9 # 灵动岛/实时活动
# --- iOS风格组件 ---
pull_down_button: ^0.10.1 # iOS下拉菜单按钮
# --- 布局增强 ---
sliver_tools: ^0.2.12 # Sliver工具集
flutter_staggered_grid_view: ^0.7.0 # 瀑布流网格
visibility_detector: ^0.4.0+2 # 组件可见性检测
# --- 触觉反馈 ---
flutter_vibrate:
git:
url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_vibrate.git # 跨平台触觉反馈(iOS/Android/HarmonyOS)
# --- 提示反馈 ---
bot_toast: ^4.1.0 # Toast/通知弹窗
# --- Shader效果 ---
flutter_shaders_ui: ^0.1.0 # Fragment Shader效果
flutter_tilt: ^4.0.0 # 3D倾斜交互效果
flutter_3d_controller: 2.3.0 # 3D模型加载控制
flutter_advanced_canvas_editor: 2.1.0 # 高级画布编辑器
flutter_spritesheet_animation: ^1.0.1 # 精灵图帧动画
image_size_getter: ^2.4.1 # 图片尺寸读取(无需解码)
extended_image: ^10.0.1 # 图片缓存+缩放+裁剪
photo_view: ^0.15.0 # 图片缩放/平移查看
flutter_image_compress: ^2.4.0 # 图片压缩(保持EXIF)
vector_math: any # 向量数学运算
wakelock_plus: ^1.4.0 # 屏幕常亮控制
audioplayers: ^6.5.0 # 音频播放
record: ^6.0.0 # 录音
video_compress: ^3.1.2 # 视频压缩
video_player: ^2.10.0 # 视频播放
local_auth: ^3.0.1 # 生物识别认证
sensors_plus: ^6.1.0 # 加速度传感器
battery_plus: ^7.0.0 # 电池状态监听
# --- 文件传输助手 ---
shelf: ^1.4.0 # HTTP服务器框架
shelf_router: ^1.1.0 # 路由中间件
shelf_web_socket: ^3.0.0 # WebSocket支持
network_info_plus: ^8.1.0 # WiFi网络信息
flutter_webrtc: ^1.4.0 # WebRTC音视频通信
web_socket_channel: ^3.0.3 # WebSocket客户端
flutter_blue_plus: ^2.1.0 # 蓝牙BLE通信
flutter_nfc_kit: ^3.6.0 # NFC读写
mime: ^2.0.0 # MIME类型识别
mobile_scanner: ^7.1.4 # 二维码/条形码扫描
basic_utils: ^5.7.0 # 通用工具集(Base64/ASN1)
wifi_iot: ^0.3.19 # WiFi IoT设备连接
nearby_service: ^0.2.1 # 近场设备发现+通信
flutter_localizations:
sdk: flutter # Flutter国际化支持
timezone: ^0.11.0 # 时区数据库
sqflite: ^2.4.1 # SQLite轻量数据库
cross_file: any # 跨平台文件抽象
receive_sharing_intent:
git:
url: "https://gitcode.com/openharmony-sig/fluttertpc_receive_sharing_intent.git"
ref: "br_v1.8.1_ohos"
# ============================================================
# 开发依赖
# ============================================================
dev_dependencies:
flutter_test:
sdk: flutter
# 代码生成
build_runner: ^2.6.0 # 代码生成运行器
freezed: ^3.2.0 # 不可变数据类生成
json_serializable: ^6.11.0 # JSON序列化代码生成
drift_dev: ^2.31.0 # Drift数据库代码生成
riverpod_generator: ^4.0.0 # Riverpod Provider代码生成
# 代码规范
flutter_lints: ^5.0.0 # Flutter lint规则
riverpod_lint: ^3.0.0 # Riverpod专用lint
custom_lint: ^0.8.0 # 自定义lint插件
# 测试
mocktail: ^1.0.0 # Mock测试库
# ============================================================
# 依赖覆写 — MacBook Pro端（仅版本号覆盖，无本地包）
# 1. liquid_glass_widgets与flutter_test的meta版本冲突
# 2. share_plus 13.x / device_info_plus 13.x 需要win32 ^6.0.1
# 但 quill_native_bridge_windows 依赖 win32 ^5.5.0
# 3. device_calendar ^4.3.3 依赖 timezone ^0.9.0(<0.10.0)
# 但 flutter_local_notifications 依赖 timezone ^0.11.0(<0.12.0)
# timezone 0.9→0.11 API兼容(仅时区数据更新)，强制使用^0.11.0
# ============================================================
dependency_overrides:
meta: ^1.17.0
web: ^1.1.0
timezone: ^0.11.0
win32: ^6.0.1
# ============================================================
# Flutter 配置
# ============================================================
flutter:
uses-material-design: true
assets:
- assets/animations/
- assets/images/
- assets/templates/resized/
- assets/svgs/
- assets/svgs/categories/
- assets/svgs/editor/
- assets/spritesheets/builtin/
- assets/spritesheets/builtin/emotions/
- assets/spritesheets/builtin/gestures/
- assets/spritesheets/builtin/nature/
- assets/spritesheets/builtin/festive/
- assets/models/3d/
- assets/models/thumbnails/
- assets/model_catalog.json
- assets/data/
- assets/data/leisure/
- assets/sounds/
- assets/sounds/sfx/
- assets/sounds/sfx/sfx/
- assets/sounds/sfx/sfx_soft/
- assets/sounds/sfx/sfx_crisp/
- assets/shaders/

17
pubspec.yaml → pubspec.ohos.yaml
View File

@@ -1,10 +1,11 @@
# ============================================================
# 闲言APP (Xianyan) — Flutter 版 pubspec.yaml
# 闲言APP (Xianyan) — 鸿蒙端 pubspec 模板
# 创建时间: 2026-04-20
# 更新时间: 2026-06-02
# 作用: 项目依赖与资源配置
# 上次更新: bitsdojo_window替换为window_manager桌面端窗口管理
# **python**: C:\Users\无书\AppData\Local\Python\pythoncore-3.14-64\python.exe
# 作用: 鸿蒙端依赖与资源配置模板（使用本地 packages/ 目录）
# 上次更新: pubspec.yaml 拆分为双模板（ohos/macos），pubspec.yaml 不再提交
# 使用方式: 运行 tools/setup_pubspec.ps1 --platform ohos 自动生成 pubspec.yaml
# ⚠️ 此文件为模板，不要直接重命名为 pubspec.yaml 使用
# ============================================================
name: xianyan
@@ -320,12 +321,10 @@ dev_dependencies:
# ============================================================
# 依赖覆写 — 解决版本冲突
# 依赖覆写 — 鸿蒙端（本地包覆盖 + 版本冲突解决）
# 1. liquid_glass_widgets与flutter_test的meta版本冲突
# 2. share_plus 13.x / device_info_plus 13.x 需要win32 ^6.0.1
# 但 quill_native_bridge_windows 依赖 win32 ^5.5.0
# 3. 本地化包覆写：让远程依赖的库也使用本地path版本
# 4. device_calendar ^4.3.3 依赖 timezone ^0.9.0(<0.10.0)
# 2. 本地化包覆写：让远程依赖的库也使用本地path版本
# 3. device_calendar ^4.3.3 依赖 timezone ^0.9.0(<0.10.0)
# 但 flutter_local_notifications 依赖 timezone ^0.11.0(<0.12.0)
# timezone 0.9→0.11 API兼容(仅时区数据更新)，强制使用^0.11.0
# ============================================================

137
tools/setup_pubspec.ps1 Normal file
View File

@@ -0,0 +1,137 @@
# ============================================================
# 闲言APP — pubspec.yaml 平台模板生成脚本
# 创建时间: 2026-06-02
# 更新时间: 2026-06-02
# 作用: 根据平台选择模板生成 pubspec.yaml
# 上次更新: 初始版本
# 用法:
# .\tools\setup_pubspec.ps1 -Platform ohos # 鸿蒙端
# .\tools\setup_pubspec.ps1 -Platform macos # MacBook Pro端
# .\tools\setup_pubspec.ps1 # 自动检测平台
# ============================================================
param(
[ValidateSet("ohos", "macos", "auto")]
[string]$Platform = "auto"
)
$ErrorActionPreference = "Stop"
$ProjectRoot = $PSScriptRoot
if ($ProjectRoot) {
$ProjectRoot = Split-Path -Parent $ProjectRoot
}
if (-not $ProjectRoot) {
$ProjectRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition
if ($ProjectRoot) {
$ProjectRoot = Split-Path -Parent $ProjectRoot
}
}
if (-not $ProjectRoot) {
$ProjectRoot = (Get-Location).Path
}
$OhosTemplate = Join-Path $ProjectRoot "pubspec.ohos.yaml"
$MacosTemplate = Join-Path $ProjectRoot "pubspec.macos.yaml"
$OutputFile = Join-Path $ProjectRoot "pubspec.yaml"
function Write-Status {
param([string]$Message)
Write-Host "[setup_pubspec] $Message" -ForegroundColor Cyan
}
function Write-Warning {
param([string]$Message)
Write-Host "[setup_pubspec] WARNING: $Message" -ForegroundColor Yellow
}
function Write-Error {
param([string]$Message)
Write-Host "[setup_pubspec] ERROR: $Message" -ForegroundColor Red
}
# --- 自动检测平台 ---
if ($Platform -eq "auto") {
Write-Status "Auto-detecting platform..."
$flutterPath = Get-Command flutter -ErrorAction SilentlyContinue
if ($flutterPath) {
$flutterVersion = & flutter --version 2>&1 | Select-String -Pattern "ohos|HarmonyOS" -Quiet
if ($flutterVersion) {
$Platform = "ohos"
Write-Status "Detected flutter-ohos SDK -> ohos"
} else {
$Platform = "macos"
Write-Status "Detected official Flutter SDK -> macos"
}
} else {
# 检查 packages 目录是否存在
$packagesDir = Join-Path $ProjectRoot "packages"
if (Test-Path $packagesDir) {
$Platform = "ohos"
Write-Status "Found packages/ directory -> ohos"
} else {
$Platform = "macos"
Write-Status "No packages/ directory -> macos"
}
}
}
# --- 选择模板 ---
$TemplateFile = switch ($Platform) {
"ohos" { $OhosTemplate }
"macos" { $MacosTemplate }
}
if (-not (Test-Path $TemplateFile)) {
Write-Error "Template file not found: $TemplateFile"
Write-Error "Expected: pubspec.ohos.yaml or pubspec.macos.yaml in project root"
exit 1
}
# --- 备份现有 pubspec.yaml ---
if (Test-Path $OutputFile) {
$BackupFile = Join-Path $ProjectRoot "pubspec.yaml.bak"
Copy-Item $OutputFile $BackupFile -Force
Write-Status "Backed up existing pubspec.yaml -> pubspec.yaml.bak"
}
# --- 复制模板 ---
Copy-Item $TemplateFile $OutputFile -Force
$PlatformLabel = switch ($Platform) {
"ohos" { "鸿蒙端 (HarmonyOS)" }
"macos" { "MacBook Pro端 (iOS/macOS)" }
}
Write-Status "========================================"
Write-Status "Generated pubspec.yaml for: $PlatformLabel"
Write-Status "Template: $(Split-Path $TemplateFile -Leaf)"
Write-Status "Output: pubspec.yaml"
Write-Status "========================================"
# --- 验证关键差异 ---
if ($Platform -eq "ohos") {
$hasPathRef = Select-String -Path $OutputFile -Pattern "path: packages/" -Quiet
if (-not $hasPathRef) {
Write-Warning "ohos template has no 'path: packages/' references - check template!"
}
Write-Status "Next steps:"
Write-Status " 1. flutter pub get"
Write-Status " 2. flutter build hap (or your ohos build command)"
} else {
$hasPathRef = Select-String -Path $OutputFile -Pattern "path: packages/" -Quiet
if ($hasPathRef) {
Write-Warning "macos template still has 'path: packages/' references - check template!"
}
Write-Status "Next steps:"
Write-Status " 1. flutter pub get"
Write-Status " 2. Apply pub cache patches (see iOS_macOS_Developer_Guide.md section 2.6)"
Write-Status " 3. flutter build ios --no-codesign"
Write-Status " 4. flutter build macos"
}
Write-Status ""
Write-Status "NOTE: pubspec.yaml is in .gitignore and will NOT be committed."
Write-Status "When adding a new dependency, update BOTH pubspec.ohos.yaml AND pubspec.macos.yaml"
Write-Status "Then update iOS_macOS_Developer_Guide.md to notify the other platform developer."