# iOS / macOS 开发者指南

> 本项目同时支持 iOS、macOS、Android、鸿蒙(HarmonyOS) 四端。
> 鸿蒙端使用定制 Flutter SDK（`flutter-ohos`），在 `TargetPlatform` 枚举中新增了 `TargetPlatform.ohos`，
> 并对大量三方库做了本地化适配。iOS/macOS 开发者需了解以下关键事项，避免踩坑。

---

## 一、环境准备与项目拉取

### 1.1 Flutter SDK 选择

| 平台 | 推荐SDK | 说明 |
|---|---|---|
| iOS / macOS | **官方 Flutter SDK** | 标准 stable/beta 渠道即可 |
| 鸿蒙 | flutter-ohos 定制SDK | 包含 `TargetPlatform.ohos` 等扩展，仅在鸿蒙开发机上使用 |
| Android | 官方 Flutter SDK | 同 iOS |

> ⚠️ **iOS/macOS 开发使用官方 Flutter SDK 即可**，无需安装鸿蒙定制SDK。
> 不要用鸿蒙SDK编译iOS/macOS，反之亦然，SDK不兼容会导致编译错误。

### 1.2 克隆仓库

```bash
# 克隆项目仓库
git clone <仓库URL> xianyan
cd xianyan

# 查看当前分支
git branch -a

# 切换到开发分支（如需）
git checkout feature/xxx
# 或直接在 main 分支开发
git checkout main
```

### 1.3 修改 pubspec.yaml 并安装依赖

MacBook Pro 端需要将 `pubspec.yaml` 中的本地包引用替换为远程版本号（详见 §2.2）。

```bash
# 1. 确认使用官方 Flutter SDK
flutter --version   # 应显示官方版本，非 flutter-ohos

# 2. 修改 pubspec.yaml（参见 §2.2 替换清单）

# 3. 获取依赖
flutter pub get

# 4. iOS 编译验证
flutter build ios --no-codesign

# 5. macOS 编译验证
flutter build macos

# 5. 防止误提交 pubspec.yaml
git stash push -m "macOS-local-pubspec" pubspec.yaml
```

---

## 二、pubspec.yaml 与三方库

### 2.1 MacBook Pro 端的核心原则

> **MacBook Pro 端不需要 `packages/` 目录，直接使用远程三方库即可。**

项目 `pubspec.yaml` 中的本地包引用（`path: packages/xxx`）是为鸿蒙端准备的。
MacBook Pro 端使用官方 Flutter SDK，需要将这些本地包引用替换为远程版本号。

**为什么不能直接用本地包？**

本地包中包含 `TargetPlatform.ohos` 引用（鸿蒙SDK新增的枚举值），官方 SDK 没有此值，会导致编译报错：

```
Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'
```

受影响的本地包有 5 个：

| 包名 | 引用次数 | 引用类型 |
|---|---|---|
| flex_color_picker | 2 | `case TargetPlatform.ohos:` (switch) |
| flutter_quill | 2 | `case TargetPlatform.ohos:` (switch) |
| flutter_local_notifications | 8 | `== TargetPlatform.ohos` (if比较) |
| mobile_scanner | 3 | `== / != TargetPlatform.ohos` (if比较) |
| audioplayers | 1 | `!= TargetPlatform.ohos` (if比较) |

**解决方案**：MacBook Pro 端使用远程版本，远程版本不含 `TargetPlatform.ohos`，编译正常。

### 2.2 MacBook Pro 端 pubspec.yaml 修改指南

克隆项目后，需要修改 `pubspec.yaml`，将本地包引用替换为远程版本号。

#### 2.2.1 dependencies 区域 — 需要替换的包

将以下包从 `path: packages/xxx` 改为版本号：

```yaml
# ❌ 原始写法（鸿蒙端）
  shared_preferences:
    path: packages/shared_preferences

# ✅ MacBook Pro 端改为远程版本
  shared_preferences: ^2.5.5
```

**完整替换清单：**

| 包名 | 远程版本号 | 说明 |
|---|---|---|
| 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，已集成） |

#### 2.2.2 dependency_overrides 区域 — 整体替换

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
```

### 2.4 MacBook Pro 端完整操作流程

```bash
# 1. 克隆仓库
git clone <仓库URL> xianyan
cd xianyan

# 2. 修改 pubspec.yaml（替换本地包为远程版本）
#    参见 §2.2 的替换清单

# 3. 获取依赖
flutter pub get

# 4. 编译验证
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.5.1 pro_image_editor（已迁移至远程版本）

`pro_image_editor` 已从本地包迁移为远程版本 `^12.4.4`，MacBook Pro 端直接使用远程版本即可：

```yaml
# MacBook Pro 端使用远程版本
  pro_image_editor: ^12.4.4
```

> **注意**：如果项目代码中使用了自定义的 `CanvasStyleModel` 类，
> 远程版本可能不包含此类型，需要检查兼容性。
> 如遇编译错误，可恢复使用本地包版本（`path: packages/pro_image_editor`）。

#### 2.5.2 file_picker（API 变更 + win32 6.x 兼容）

`file_picker` 已从 `^11.0.0` 升级为 `^12.0.0-beta.5`，原因：

1. **API 变更**（11.x → 12.x 通用）：

```dart
// ❌ 旧版 API（file_picker ^8.x）
final result = await FilePicker.platform.pickFiles();

// ✅ 新版 API（file_picker ^11.x / ^12.x）
final result = await FilePicker.pickFiles();
```

2. **win32 6.x 兼容**（12.x 专属）：
   - `file_picker ^11.0.0` 依赖 `win32: ^5.9.0`，与 `dependency_overrides` 中的 `win32: ^6.0.1` 冲突
   - `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`。

#### 2.5.3 flutter_secure_storage（版本升级）

`flutter_secure_storage ^10.2.0` 的 Windows 平台实现兼容 `win32 ^6.0.1`，
解决了之前版本与 `win32 6.x` 的编译冲突。

#### 2.5.4 receive_sharing_intent（gitcode 引用）

`receive_sharing_intent` 在 pub.dev 上的版本与鸿蒙端不兼容，MacBook Pro 端需使用 gitcode 引用：

```yaml
# MacBook Pro 端使用 gitcode 引用
  receive_sharing_intent:
    git:
      url: "https://gitcode.com/openharmony-sig/fluttertpc_receive_sharing_intent.git"
      ref: "br_v1.8.1_ohos"
```

> **注意**：gitcode 版本的 `SharedMediaFile` 构造函数可能包含 `ohosPath` 等鸿蒙特有参数，
> 官方 SDK 不存在这些参数。项目代码中已通过 `pu.isOhos` 条件分支隔离。

#### 2.5.5 flutter_vibrate（gitcode 引用）

`flutter_vibrate` 在 pub.dev 上的版本不支持鸿蒙，MacBook Pro 端需使用 gitcode 引用：

```yaml
# MacBook Pro 端使用 gitcode 引用
  flutter_vibrate:
    git:
      url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_vibrate.git
```

#### 2.5.6 home_widget（pub.dev 远程版本）

`home_widget` 的 gitcode 版本依赖 `path_provider` 的 git 版本，会与远程 `path_provider` 冲突。
MacBook Pro 端使用 pub.dev 版本 `^0.9.1`，鸿蒙端的 `ohosName` 参数通过 `pu.isOhos` + `dynamic` 调用隔离：

```yaml
# MacBook Pro 端使用 pub.dev 远程版本
  home_widget: ^0.9.1
```

### 2.6 ⚠️ 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 需要修补的包

| 包名 | 版本 | 问题 | 修补文件 |
|---|---|---|---|
| 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 补丁应用流程

```bash
# 1. 确保 flutter pub get 已执行
flutter pub get

# 2. 运行补丁脚本（见 §2.6.3）
bash scripts/patch_pub_cache.sh

# 3. 验证构建
flutter build macos
flutter build ios --no-codesign
```

> ⚠️ `flutter clean` 或 `flutter pub cache repair` 会清除补丁，需重新执行步骤 2。

#### 2.6.3 补丁脚本

在项目根目录创建 `scripts/patch_pub_cache.sh`（已包含在仓库中），内容如下：

```bash
#!/bin/bash
# patch_pub_cache.sh — 修补 pub cache 中的兼容性问题
# 创建时间: 2026-06-01
# 作用: 修补 quill_native_bridge_windows (win32 6.x) 和 flutter_vibrate (Swift 6)

set -e

echo "🔧 Applying pub cache patches..."

# ── Patch 1: quill_native_bridge_windows — clipboard_html_format.dart ──
QNBW_DIR="$HOME/.pub-cache/hosted/pub.dev/quill_native_bridge_windows-0.0.2"
if [ -d "$QNBW_DIR" ]; then
  echo "  Patching clipboard_html_format.dart..."
  cat > "$QNBW_DIR/lib/src/clipboard_html_format.dart" << 'DART_EOF'
import 'package:ffi/ffi.dart';
import 'package:win32/win32.dart';

import '../quill_native_bridge_windows.dart';

const _kHtmlFormatName = 'HTML Format';

int? _cfHtml;

extension ClipboardHtmlFormatExt on QuillNativeBridgeWindows {
  int? get cfHtml {
    _cfHtml ??= _registerHtmlFormat();
    return _cfHtml;
  }

  int? _registerHtmlFormat() {
    final htmlFormatPointer = _kHtmlFormatName.toPcwstr();
    final result = RegisterClipboardFormat(htmlFormatPointer);
    free(htmlFormatPointer);

    if (result.error.isError) {
      return null;
    }
    return result.value;
  }
}
DART_EOF
  echo "  ✅ clipboard_html_format.dart patched"
else
  echo "  ⚠️ quill_native_bridge_windows not found in pub cache"
fi

# ── Patch 2: quill_native_bridge_windows — quill_native_bridge_windows.dart ──
if [ -d "$QNBW_DIR" ]; then
  echo "  Patching quill_native_bridge_windows.dart..."
  cat > "$QNBW_DIR/lib/quill_native_bridge_windows.dart" << 'DART_EOF'
// Patched for win32 6.x compatibility (2026-06-01)
// Changes: Win32Result API, HGLOBAL/HANDLE extension types, TEXT() → toPcwstr()

import 'dart:ffi';
import 'dart:io';

import 'package:ffi/ffi.dart';
import 'package:file_selector_platform_interface/file_selector_platform_interface.dart';
import 'package:flutter/foundation.dart';
import 'package:quill_native_bridge_platform_interface/quill_native_bridge_platform_interface.dart';
import 'package:win32/win32.dart';

import 'src/clipboard_html_format.dart';
import 'src/html_cleaner.dart';
import 'src/html_formatter.dart';
import 'src/image_saver.dart';

class QuillNativeBridgeWindows extends QuillNativeBridgePlatform {
  static void registerWith() {
    QuillNativeBridgePlatform.instance = QuillNativeBridgeWindows();
  }

  @override
  Future<bool> isSupported(QuillNativeBridgeFeature feature) async => {
        QuillNativeBridgeFeature.getClipboardHtml,
        QuillNativeBridgeFeature.copyHtmlToClipboard,
        QuillNativeBridgeFeature.saveImage,
      }.contains(feature);

  @override
  Future<String?> getClipboardHtml() async {
    final openResult = OpenClipboard(null);
    if (openResult.error.isError) {
      assert(false, 'Unknown error while opening the clipboard. Error code: ${GetLastError()}');
      return null;
    }

    try {
      final htmlFormatId = cfHtml;
      if (htmlFormatId == null) {
        assert(false, 'Failed to register clipboard HTML format.');
        return null;
      }

      final availableResult = IsClipboardFormatAvailable(htmlFormatId);
      if (availableResult.error.isError) {
        return null;
      }

      final getDataResult = GetClipboardData(htmlFormatId);
      if (getDataResult.error.isError) {
        assert(false, 'Failed to get clipboard data. Error code: ${GetLastError()}');
        return null;
      }

      final clipboardDataHandle = getDataResult.value;
      final hglobal = HGLOBAL(clipboardDataHandle);
      final lockResult = GlobalLock(hglobal);
      if (lockResult.error.isError) {
        assert(false, 'Failed to lock global memory. Error code: ${GetLastError()}');
        return null;
      }

      final lockedMemoryPointer = lockResult.value;
      final windowsHtmlWithMetadata = lockedMemoryPointer.cast<Utf8>().toDartString();
      GlobalUnlock(hglobal);

      final cleanedHtml = stripWindowsHtmlDescriptionHeaders(windowsHtmlWithMetadata);
      return cleanedHtml;
    } finally {
      CloseClipboard();
    }
  }

  @override
  Future<void> copyHtmlToClipboard(String html) async {
    final openResult = OpenClipboard(null);
    if (openResult.error.isError) {
      assert(false, 'Unknown error while opening the clipboard. Error code: ${GetLastError()}');
      return;
    }

    final windowsClipboardHtml = constructWindowsHtmlDescriptionHeaders(html);
    final htmlPointer = windowsClipboardHtml.toNativeUtf8();

    try {
      final emptyResult = EmptyClipboard();
      if (emptyResult.error.isError) {
        assert(false, 'Failed to empty the clipboard. Error code: ${GetLastError()}');
        return;
      }

      final htmlFormatId = cfHtml;
      if (htmlFormatId == null) {
        assert(false, 'Failed to register clipboard HTML format. Error code: ${GetLastError()}');
        return;
      }

      final unitSize = sizeOf<Uint8>();
      final htmlSize = (htmlPointer.length + 1) * unitSize;

      final allocResult = GlobalAlloc(GMEM_MOVEABLE, htmlSize);
      if (allocResult.error.isError) {
        assert(false, 'Failed to allocate memory for the clipboard content. Error code: ${GetLastError()}');
        return;
      }

      final clipboardMemoryHandle = allocResult.value;
      final lockResult = GlobalLock(clipboardMemoryHandle);
      if (lockResult.error.isError) {
        GlobalFree(clipboardMemoryHandle);
        assert(false, 'Failed to lock global memory. Error code: ${GetLastError()}');
        return;
      }

      final lockedMemoryPointer = lockResult.value;
      final targetMemoryPointer = lockedMemoryPointer.cast<Uint8>();
      final sourcePointer = htmlPointer.cast<Uint8>();

      for (var i = 0; i < htmlPointer.length; i++) {
        targetMemoryPointer[i] = (sourcePointer + i).value;
      }
      (targetMemoryPointer + htmlPointer.length).value = 0;

      GlobalUnlock(clipboardMemoryHandle);

      final setResult = SetClipboardData(htmlFormatId, HANDLE(clipboardMemoryHandle));
      if (setResult.error.isError) {
        GlobalFree(clipboardMemoryHandle);
        assert(false, 'Failed to set the clipboard data: ${GetLastError()}');
      }
    } finally {
      CloseClipboard();
      calloc.free(htmlPointer);
    }
  }

  @visibleForTesting
  static ImageSaver imageSaver = ImageSaver();

  @override
  Future<ImageSaveResult> saveImage(Uint8List imageBytes, {required ImageSaveOptions options}) async {
    final typeGroup = XTypeGroup(label: 'Images', extensions: [options.fileExtension]);
    final saveLocation = await imageSaver.fileSelector.getSaveLocation(
      options: SaveDialogOptions(
        suggestedName: '${options.name}.${options.fileExtension}',
        initialDirectory: imageSaver.picturesDirectoryPath,
      ),
      acceptedTypeGroups: [typeGroup],
    );
    final imageFilePath = saveLocation?.path;
    if (imageFilePath == null) {
      return ImageSaveResult.io(filePath: null);
    }
    final imageFile = File(imageFilePath);
    await imageFile.writeAsBytes(imageBytes);
    return ImageSaveResult.io(filePath: imageFile.path);
  }

  @override
  Future<void> openGalleryApp() async {
    final uriPtr = 'ms-photos:'.toPcwstr();
    final openPtr = 'open'.toPcwstr();
    ShellExecute(null, openPtr, uriPtr, null, null, SW_SHOWNORMAL);
    free(uriPtr);
    free(openPtr);
  }
}
DART_EOF
  echo "  ✅ quill_native_bridge_windows.dart patched"
fi

# ── Patch 3: flutter_vibrate — SwiftVibratePlugin.swift ──
FV_DIR=$(find "$HOME/.pub-cache/git" -path "*/fluttertpc_flutter_vibrate*" -maxdepth 2 -type d 2>/dev/null | head -1)
if [ -n "$FV_DIR" ]; then
  echo "  Patching SwiftVibratePlugin.swift..."
  cat > "$FV_DIR/ios/Classes/SwiftVibratePlugin.swift" << 'SWIFT_EOF'
import Flutter
import UIKit
import AudioToolbox

// Patched for Xcode 16+/Swift 6 compatibility (2026-06-01)
// TARGET_OS_SIMULATOR removed; using #if targetEnvironment(simulator)

#if targetEnvironment(simulator)
private let isDevice = false
#else
private let isDevice = true
#endif

public class SwiftVibratePlugin: NSObject, FlutterPlugin {
  public static func register(with registrar: FlutterPluginRegistrar) {
    let channel = FlutterMethodChannel(name: "vibrate", binaryMessenger: registrar.messenger())
    let instance = SwiftVibratePlugin()
    registrar.addMethodCallDelegate(instance, channel: channel)
  }

    public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
      switch (call.method) {
          case "canVibrate":
              if isDevice { result(true) } else { result(false) }
          case "vibrate":
            AudioServicesPlaySystemSound(kSystemSoundID_Vibrate)
          case "impact":
            if #available(iOS 10.0, *) {
              let impact = UIImpactFeedbackGenerator()
              impact.prepare()
              impact.impactOccurred()
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          case "selection":
            if #available(iOS 10.0, *) {
              let selection = UISelectionFeedbackGenerator()
              selection.prepare()
              selection.selectionChanged()
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          case "success":
            if #available(iOS 10.0, *) {
              let notification = UINotificationFeedbackGenerator()
              notification.prepare()
              notification.notificationOccurred(.success)
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          case "warning":
            if #available(iOS 10.0, *) {
              let notification = UINotificationFeedbackGenerator()
              notification.prepare()
              notification.notificationOccurred(.warning)
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          case "error":
            if #available(iOS 10.0, *) {
              let notification = UINotificationFeedbackGenerator()
              notification.prepare()
              notification.notificationOccurred(.error)
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          case "heavy":
            if #available(iOS 10.0, *) {
              let generator = UIImpactFeedbackGenerator(style: .heavy)
              generator.prepare()
              generator.impactOccurred()
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
         case "medium":
            if #available(iOS 10.0, *) {
              let generator = UIImpactFeedbackGenerator(style: .medium)
              generator.prepare()
              generator.impactOccurred()
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
         case "light":
            if #available(iOS 10.0, *) {
              let generator = UIImpactFeedbackGenerator(style: .light)
              generator.prepare()
              generator.impactOccurred()
            } else { AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) }
          default:
              result(FlutterMethodNotImplemented)
      }
    }
}
SWIFT_EOF
  echo "  ✅ SwiftVibratePlugin.swift patched"
else
  echo "  ⚠️ flutter_vibrate not found in pub cache"
fi

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 迁移参考

如需修补其他使用 win32 的三方包，以下是关键 API 变更：

| win32 5.x | win32 6.x | 说明 |
|---|---|---|
| `OpenClipboard(NULL) == FALSE` | `OpenClipboard(null).error.isError` | 返回 `Win32Result<bool>` |
| `CloseClipboard()` | `CloseClipboard()` | 返回 `Win32Result<bool>`，忽略即可 |
| `EmptyClipboard() == FALSE` | `EmptyClipboard().error.isError` | 返回 `Win32Result<bool>` |
| `IsClipboardFormatAvailable(id) == FALSE` | `IsClipboardFormatAvailable(id).error.isError` | 返回 `Win32Result<bool>` |
| `GetClipboardData(id) == NULL` | `GetClipboardData(id).error.isError` | 返回 `Win32Result<HANDLE>` |
| `GlobalAlloc(flags, size) == nullptr` | `GlobalAlloc(flags, size).error.isError` | 返回 `Win32Result<HGLOBAL>` |
| `GlobalLock(handle) == nullptr` | `GlobalLock(HGLOBAL(handle)).error.isError` | 返回 `Win32Result<Pointer>` |
| `GlobalUnlock(handle)` | `GlobalUnlock(HGLOBAL(handle))` | 返回 `Win32Result<bool>` |
| `GlobalFree(handle)` | `GlobalFree(HGLOBAL(handle))` | 返回 `Win32Result<HGLOBAL>` |
| `SetClipboardData(id, addr) == NULL` | `SetClipboardData(id, HANDLE(hglobal)).error.isError` | 返回 `Win32Result<HANDLE>` |
| `TEXT('str')` | `'str'.toPcwstr()` | `TEXT()` 已移除 |
| `RegisterClipboardFormat(ptr)` 返回 `int` | `RegisterClipboardFormat(ptr)` 返回 `Win32Result<int>` | 检查 `.error.isError` |
| `ShellExecute(NULL, ...)` | `ShellExecute(null, ...)` | `NULL` → `null`，`nullptr` → `null`（PCWSTR? 类型） |
| `HGLOBAL` 为 `int` | `HGLOBAL` 为 `extension type const HGLOBAL(Pointer _)` | 需类型转换 |
| `HANDLE` 为 `int` | `HANDLE` 为 `extension type const HANDLE(Pointer _)` | 需类型转换 |

> **类型转换**：`HANDLE` 和 `HGLOBAL` 都 `implements Pointer`，可互相转换：
> - `HANDLE → HGLOBAL`：`HGLOBAL(handle)`
> - `HGLOBAL → HANDLE`：`HANDLE(hglobal)`

---

## 三、Git 提交与合并规范

### 3.1 分支策略

```
main (受保护)                 ← 所有平台共用
 ├── feature/xxx              ← 功能开发（所有平台共用）
 ├── fix/xxx                  ← Bug修复
 └── hotfix/xxx               ← 紧急修复
```

> **不需要按平台创建长期分支**。`lib/` 代码所有平台共用，独立平台分支会导致大量合并冲突。
> 平台原生代码已天然隔离（`ios/`、`macos/`、`ohos/` 各自独立），不会互相污染。

### 3.2 iOS/macOS 开发者提交规则

**✅ 应该提交的文件：**
- `lib/` 目录下的所有 Dart 代码
- `ios/` 目录下的原生代码
- `macos/` 目录下的原生代码
- `assets/` 目录下的资源文件
- `test/` 目录下的测试代码

**❌ 不要提交的文件：**
- `pubspec.yaml`（MacBook Pro 端已替换为远程版本，**绝不能提交**）
- `packages/` 目录（已在 `.gitignore` 中排除）
- `ohos/` 目录下的鸿蒙原生代码
- 鸿蒙SDK特有的配置文件

**⚠️ pubspec.yaml 提交铁律：**
1. **MacBook Pro 端修改的 `pubspec.yaml` 绝对不能提交** — 仓库中的版本必须保持鸿蒙端本地包引用
2. **使用 `git stash` 或 `.git/info/exclude` 隔离修改** — 防止误提交
3. **如果必须提交 `pubspec.yaml`**（如新增了远程依赖），先 `git stash pop` 恢复原始版本，在原始版本上修改，再提交

### 3.3 pubspec.yaml 处理策略（⭐ 重点）

由于 MacBook Pro 端和鸿蒙端使用不同的 `pubspec.yaml` 配置，需要特别注意。

#### 3.3.1 两端 pubspec.yaml 差异

| 区域 | 鸿蒙端（仓库版本） | MacBook Pro 端（本地版本） |
|---|---|---|
| dependencies 中的本地包 | `path: packages/xxx` | 远程版本号（如 `^2.5.5`） |
| dependency_overrides | 包含所有 `path: packages/xxx` | 仅保留 `meta`、`web` 等版本号覆盖 |

#### 3.3.2 MacBook Pro 端日常操作

```bash
# 开发前：恢复 MacBook Pro 本地版本
git stash list  # 查看暂存
git stash pop   # 恢复修改后的 pubspec.yaml

# 开发中：正常编码，不涉及 pubspec.yaml 的提交

# 提交代码时：先暂存本地 pubspec.yaml
git stash push -m "macOS-local-pubspec" pubspec.yaml
git add lib/ ios/ macos/ assets/
git commit -m "feat: xxx"
git push origin feature/xxx

# 提交后：恢复本地 pubspec.yaml
git stash pop
```

#### 3.3.3 需要新增依赖时

MacBook Pro 端新增依赖时，需要在**两端**分别操作：

```bash
# ── MacBook Pro 端 ──
# 1. 在本地 pubspec.yaml 中添加新依赖
echo "  new_package: ^1.0.0" >> pubspec.yaml
flutter pub get

# 2. 恢复仓库版本的 pubspec.yaml
git stash push -m "macOS-local-pubspec" pubspec.yaml
git stash pop  # 如果之前有暂存，先恢复

# 3. 在仓库版本的 pubspec.yaml 中也添加新依赖
#    （保持鸿蒙端的本地包引用格式）
# 4. 提交仓库版本
git add pubspec.yaml
git commit -m "feat: add new_package dependency"

# ── 通知鸿蒙开发者 ──
# 告知新增了 new_package，评估是否需要鸿蒙适配
# 如果需要适配 → 鸿蒙端添加本地包引用
# 如果不需要适配 → 两端都使用远程版本
```

#### 3.3.4 git pull 后 pubspec.yaml 被覆盖

```bash
# git pull 后，仓库版本的 pubspec.yaml 覆盖了本地修改
# 重新替换为远程版本即可：

# 方式1：从备份恢复
git stash pop  # 如果之前有暂存

# 方式2：重新手动替换（参见 §2.2）
# 搜索 "path: packages/" 逐个替换为远程版本号
```

#### 3.3.5 减少冲突的最佳实践

| 做法 | 说明 |
|---|---|
| **MacBook Pro 端不提交 pubspec.yaml** | 从根本上避免冲突 |
| **使用 git stash 隔离** | 每次提交前 stash，提交后 pop |
| **新增依赖时通知鸿蒙开发者** | 让鸿蒙端同步评估适配 |
| **版本号升级单独提交** | 不要和功能代码混在一起提交 |

### 3.4 其他合并注意事项

1. **不要删除 `pu.isOhos` 相关代码**：这些条件分支在 iOS/macOS 上不会执行，但删除会导致鸿蒙端编译失败
2. **不要修改 `OhosAppShell`、`OhosNavBridge` 等鸿蒙专用类**：这些类仅在鸿蒙端使用
3. **新增页面路由时**：需同时在 `app_router.dart`（GoRouter路由表）和 `ohos_nav_bridge.dart`（鸿蒙路由映射表）中注册

### 3.5 PR 审查要点

- [ ] 未提交 MacBook Pro 端修改的 `pubspec.yaml`（仓库版本保持鸿蒙本地包引用）
- [ ] 未引入 `TargetPlatform` exhaustive switch 问题
- [ ] 新增路由已在 `ohos_nav_bridge.dart` 中同步
- [ ] `lib/` 代码无平台特定硬编码（应使用 `platform_utils.dart`）
- [ ] 新增依赖已通知鸿蒙开发者评估适配

---

## 四、TargetPlatform.ohos 处理

### 4.1 问题背景

鸿蒙定制 Flutter SDK 在 `TargetPlatform` 枚举中新增了 `TargetPlatform.ohos`。
官方 SDK 不包含此值。本地包中引用了 `TargetPlatform.ohos`，在官方 SDK 下会编译报错。

**MacBook Pro 端的解决方案**：使用远程版本的三方库，远程版本不含 `TargetPlatform.ohos`，无需关心此问题。

### 4.2 lib/ 代码中的平台判断

`lib/` 目录下的项目代码使用 `platform_utils.dart` 进行平台判断，**不依赖 `TargetPlatform.ohos` 枚举**，
在官方 SDK 下编译完全正常：

```dart
// lib/ 代码使用 Platform.operatingSystem 字符串比较，不依赖枚举
// platform_io_native.dart:
bool _isOhos() {
  try {
    return Platform.operatingSystem == 'ohos';  // 字符串比较，官方SDK也支持
  } catch (_) {
    return false;
  }
}
```

### 4.3 iOS/macOS 开发者规范

**规则1：不要使用 `switch(TargetPlatform)` 穷举匹配**

```dart
// ❌ 错误 — 官方SDK没有 ohos，鸿蒙SDK缺少 ohos 会报错
switch (defaultTargetPlatform) {
  case TargetPlatform.iOS:
    // ...
  case TargetPlatform.android:
    // ...
  case TargetPlatform.macOS:
    // ...
  case TargetPlatform.windows:
    // ...
  case TargetPlatform.linux:
    // ...
  case TargetPlatform.fuchsia:
    // ...
}

// ✅ 正确 — 使用 if-else 或添加 default
if (defaultTargetPlatform == TargetPlatform.iOS) {
  // iOS 逻辑
} else if (defaultTargetPlatform == TargetPlatform.macOS) {
  // macOS 逻辑
} else {
  // 其他平台
}

// ✅ 正确 — switch 加 default
switch (defaultTargetPlatform) {
  case TargetPlatform.iOS:
  case TargetPlatform.android:
    return mobileLayout;
  default:
    return desktopLayout;
}
```

**规则2：使用 `platform_utils.dart` 判断平台**

```dart
import 'package:xianyan/core/utils/platform_utils.dart' as pu;

// ✅ 推荐方式 — 内部使用字符串比较，两端都安全
if (pu.isIOS) { /* iOS */ }
if (pu.isMacOS) { /* macOS */ }
if (pu.isOhos) { /* 鸿蒙 */ }
if (pu.isMobile) { /* 移动端 */ }
if (pu.isDesktop) { /* 桌面端 */ }
```

### 4.4 已知的 TargetPlatform.ohos 适配点（仅本地包）

以下文件在本地包中引用了 `TargetPlatform.ohos`，MacBook Pro 端使用远程版本不受影响：

| 文件 | 位置 | 引用类型 |
|---|---|---|
| `packages/flex_color_picker/.../picker_functions.dart` | L49, L65 | `case TargetPlatform.ohos:` |
| `packages/flutter_quill/.../raw_editor_state.dart` | L309 | `case TargetPlatform.ohos:` |
| `packages/flutter_quill/.../link.dart` | L58 | `case TargetPlatform.ohos:` |
| `packages/flutter_local_notifications/.../plugin.dart` | 8处 | `== TargetPlatform.ohos` |
| `packages/mobile_scanner/.../method_channel.dart` | 3处 | `== / != TargetPlatform.ohos` |
| `packages/audioplayers/.../audioplayer.dart` | L178 | `!= TargetPlatform.ohos` |

> 以上文件均在 `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`）

---

## 五、其他注意事项

### 5.1 应用入口架构差异

项目在 `app.dart` 中根据平台选择不同的应用架构：

| 平台 | 应用架构 | 导航方式 | 入口Widget |
|---|---|---|---|
| iOS/macOS/Android | `MaterialApp.router` + GoRouter | GoRouter 声明式路由 | `AppShell` |
| 鸿蒙 | `MaterialApp(home:)` + Navigator | `CupertinoTabView` + Navigator.push | `OhosAppShell` |

**原因**：鸿蒙端 `MaterialApp.router` 白屏，无法使用 GoRouter，因此使用传统 Navigator 导航。

### 5.2 路由注册双写

新增页面时，必须在两处注册路由：

1. **`lib/core/router/app_router.dart`** — GoRouter 路由表（iOS/macOS/Android 使用）
2. **`lib/core/router/ohos_nav_bridge.dart`** — 鸿蒙路由映射表

```dart
// app_router.dart
GoRoute(
  path: AppRoutes.newPage,
  name: 'new-page',
  parentNavigatorKey: rootNavigatorKey,
  pageBuilder: (context, state) =>
      iosSlideTransition(state: state, child: const NewPage()),
),

// ohos_nav_bridge.dart
AppRoutes.newPage: (_) => const NewPage(),
```

### 5.3 平台特性检测

使用 `OhosDeviceCapabilities` 检测鸿蒙设备特性（毛玻璃、液态玻璃、重度动画、折叠屏等），
iOS/macOS 端这些检测不会执行（`isOhos` 为 false），无需关心。

### 5.4 packages 目录说明

- `packages/` 目录存放鸿蒙适配的本地三方库，已在 `.gitignore` 中排除
- MacBook Pro 端需要 `packages/pro_image_editor/`（含魔改的 `CanvasStyleModel`），从 zip 解压获取
- 其他本地包 MacBook Pro 端使用远程版本，无需放在 `packages/` 目录
- 鸿蒙开发者需手动维护本地 `packages/` 目录

### 5.5 MacBook Pro 修改 ios/macos 后，鸿蒙端是否需要同步？

| 修改内容 | 鸿蒙端是否需要同步 | 原因 |
|---|---|---|
| `ios/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
| `macos/` 目录 | ❌ 不需要 | 平台原生代码，鸿蒙不使用 |
| `lib/` 目录 | ✅ 需要同步 | Dart 代码所有平台共用 |
| `pubspec.yaml` | ✅ 需要同步 | 依赖配置共享（鸿蒙端自行维护本地包版本） |
| `assets/` 目录 | ✅ 需要同步 | 资源文件共享 |

### 5.6 常见问题

| 问题 | 原因 | 解决方案 |
|---|---|---|
| `flutter pub get` 报 packages/xxx 目录不存在 | pubspec.yaml 中有 `path: packages/xxx` 引用 | 替换为远程版本号，参见 §2.2 |
| 编译报 `TargetPlatform.ohos` 不存在 | 使用了含 ohos 引用的本地包 | 使用远程版本，参见 §2.1 |
| iOS 编译报 ohos 相关错误 | 误用鸿蒙SDK编译iOS | 切换到官方 Flutter SDK |
| GoRouter 路由正常但鸿蒙端白屏 | 鸿蒙端不支持 GoRouter | 检查 OhosNavBridge 路由映射 |
| 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 |

---

## 六、快速检查清单

MacBook Pro 开发前，确认以下事项：

- [ ] 使用官方 Flutter SDK（非 flutter-ohos）
- [ ] 已 `git clone` 拉取最新代码
- [ ] 已将 `pubspec.yaml` 中的本地包替换为远程版本（参见 §2.2）
- [ ] 已解压 `pro_image_editor` 到 `packages/` 目录（参见 §2.5.1）
- [ ] `flutter pub get` 无报错
- [ ] `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-06-01 v6 | 维护者: 闲言APP开发团队*
*更新内容: win32 6.x兼容修复(file_picker升级+pub cache补丁)；flutter_vibrate Swift 6修复；新增§2.6 pub cache补丁文档*