feat(macos+flutter): 新增 Impeller 渲染引擎开关与 Intel Mac 渲染兼容修复

本次提交包含以下核心变更： 1. 修复 RawKeyboard 断言错误，添加 HardwareKeyboard 事件处理器 2. 实现 Intel Mac 自动降级玻璃渲染质量，避免黑屏闪烁 3. 新增 macOS 端 Impeller 渲染引擎开关设置，支持动态切换 4. 修复 macOS 双标题栏问题，隐藏系统原生交通灯按钮 5. 更新多语言国际化支持，新增 Impeller 相关翻译 6. 优化 WebRTC 依赖下载，使用国内镜像避免超时
2026-06-25 08:44:00 +08:00
parent f9401b99e7
commit 7ea4a068a1
39 changed files with 1196 additions and 83 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,137 @@

 ***

+## [v6.126.0] - 2026-06-25
+
+### 🐛 修复（键盘事件）
+
+#### RawKeyboard 断言错误修复
+
+- **Issue**: `[ERR-MQSQKCXW]` Flutter framework 断言失败：`'event is! RawKeyDownEvent || _keysPressed.isNotEmpty'`，出现在 `raw_keyboard.dart` 第 863 行
+- **根因**: Flutter 框架已知 bug（[#109677](https://github.com/flutter/flutter/issues/109677)、[#116530](https://github.com/flutter/flutter/issues/116530)）。`RawKeyboard`（已废弃）与 `HardwareKeyboard` 同时接收键盘事件，当修饰键标志未正确设置时，`RawKeyboard` 内部 `_keysPressed` 为空，收到 `RawKeyDownEvent` 时断言失败
+- **方案**: 在 `main()` 中 `WidgetsFlutterBinding.ensureInitialized()` 之后添加 `HardwareKeyboard.instance.addHandler((_) => false)` 处理器，确保键盘事件正确传播
+- **涉及文件**:
+  - `lib/main.dart` — 第 58-63 行新增 `HardwareKeyboard` 处理器
+
+---
+
+## [v6.125.0] - 2026-06-25
+
+### 🐛 修复（macOS 双标题栏）
+
+#### macOS 窗口"双标题栏"问题 — 隐藏系统红黄绿灯按钮
+
+- **Issue**: macOS 端软件窗口显示两个窗口栏，红黄绿灯那一栏上方还有一栏（Flutter 自绘的 `DesktopWindowTitleBar`），需去掉系统的红黄绿灯栏
+- **根因**:
+  1. Flutter 侧 `DesktopWindowTitleBar` 已自绘 macOS 风格的红黄绿三圆点按钮（`_MacOSTrafficButton`）
+  2. 原生侧 `awakeFromNib` 仅设置了 `titlebarAppearsTransparent = true` / `titleVisibility = .hidden` / `fullSizeContentView`，**未隐藏系统 `standardWindowButton`**
+  3. 隐藏系统按钮的逻辑仅写在 `setDarkMode` 方法中（`MainFlutterWindow.swift` 第 402-404 行），而 `setDarkMode` 经 `MacosPlatformService.syncTheme` 调用时有去重机制（`if (_themeInitialized && _lastIsDark == isDark) return`），仅主题变化时触发一次
+  4. 因此应用启动初期、全屏退出后、主题未变化时，系统红黄绿灯按钮始终可见，与 Flutter 自绘标题栏形成"双标题栏"
+- **方案**: 提取公共方法 `hideSystemTrafficButtons(of:)`，在三个时机统一隐藏系统红黄绿灯按钮
+- **实现**:
+  1. **新增 `hideSystemTrafficButtons(of window: NSWindow? = nil)`** — 隐藏 `closeButton`/`miniaturizeButton`/`zoomButton`；参数为 nil 时遍历所有窗口（兼容多窗口），指定窗口时仅操作该窗口（启动时性能更优）
+  2. **`awakeFromNib`** — 在设置透明属性后立即调用 `hideSystemTrafficButtons(of: self)`，确保启动时即隐藏（Intel Mac 也调用，因 Flutter 自绘标题栏在所有桌面平台一致显示）
+  3. **`setDarkMode`** — 将原内联的三行 `standardWindowButton?.isHidden = true` 替换为 `hideSystemTrafficButtons()` 调用，消除重复代码
+  4. **`handleFullScreenExit`** — 全屏退出后重新调用 `hideSystemTrafficButtons(of: self)`，防止系统重置按钮可见性
+- **举一反三**:
+  - 此前 `setDarkMode` 承担了"主题切换 + 隐藏按钮"两个职责，按钮隐藏依赖主题切换时机触发，属于隐式依赖。现提取为独立方法后，职责清晰，可在任意时机显式调用
+  - 类似的"启动时未初始化"问题排查方向：所有依赖 Dart 侧 MethodChannel 回调才执行的原生初始化逻辑，都应在 `awakeFromNib` 中有默认值或主动初始化，避免通道未就绪时显示异常
+- **涉及文件**:
+  - `macos/Runner/MainFlutterWindow.swift` — 新增 `hideSystemTrafficButtons(of:)` 方法；`awakeFromNib`/`setDarkMode`/`handleFullScreenExit` 三处调用；更新文件头注释
+
+---
+
+## [v6.124.0] - 2026-06-25
+
+### ✨ 增强（Impeller 开关对话框 — 架构/实时状态/业务提示）
+
+#### Impeller 开关对话框增强 — 显示 CPU 架构与引擎实时运行状态
+
+- **Issue**: 通用设置页 Impeller 开关对话框存在三个问题
+  1. "稍后重启"仅关闭对话框，无业务提示和状态反馈
+  2. "立即重启"只关闭应用未启动新实例（`NSApp.terminate` 执行过快）
+  3. 对话框缺少 CPU 架构和引擎实时运行状态信息
+- **方案**:
+  1. **原生侧新增 `currentImpellerEnabled` 静态缓存** — 区分"用户设置值"（UserDefaults，可能已修改未生效）和"引擎实际运行状态"（应用启动时固定）
+  2. **新增 `getImpellerRunningStatus` channel** — 返回当前引擎实际是否在用 Impeller
+  3. **新增 `getCpuArchitecture` channel** — 返回 `arm64`/`x86_64`，用于对话框显示
+  4. **`restartApp` 改进** — 添加 800ms 延迟、错误检查、日志；先启动新实例再终止当前实例
+  5. **对话框增强** — 显示三行状态：当前架构 / 当前引擎（实际运行）/ 重启后
+  6. **稍后重启增强** — 关闭对话框后显示 Toast 提示"设置已保存，重启后生效"
+  7. **副标题增强** — 用户修改设置未重启时，副标题显示"待重启生效"标记
+- **实现**:
+  1. **MainFlutterWindow.swift**: 新增 `currentImpellerEnabled` 静态变量，在 awakeFromNib 中缓存引擎实际运行状态
+  2. **AppDelegate.swift**: 新增 `getImpellerRunningStatus`/`getCpuArchitecture` channel 方法；`restartApp` 添加延迟+错误检查+日志
+  3. **MacosPlatformService.dart**: 新增 `getImpellerRunningStatus()`/`getCpuArchitecture()` 方法；`restartApp()` 改为返回 `Future<bool>`
+  4. **general_settings_page.dart**: 新增 `_impellerPendingRestart`/`_cpuArch`/`_impellerRunning` 状态变量；`_loadImpellerEnabled` 并行加载三个值；重写 `_onImpellerToggle` 增强对话框；新增 `_buildImpellerDialogContent`/`_buildStatusRow` 辅助方法
+  5. **general_settings_sections.dart**: 新增 `impellerPendingRestart` 参数，副标题动态显示"待重启生效"标记
+  6. **i18n**: 为 14 个语言文件添加 5 个新翻译键（impellerSavedToast/impellerPendingRestart/impellerDialogArch/impellerDialogRunning/impellerDialogAfterRestart）
+- **涉及文件**:
+  - `macos/Runner/MainFlutterWindow.swift` — 新增 currentImpellerEnabled 静态缓存
+  - `macos/Runner/AppDelegate.swift` — 新增 getImpellerRunningStatus/getCpuArchitecture channel，改进 restartApp
+  - `lib/core/services/device/macos_platform_service.dart` — 新增 getImpellerRunningStatus/getCpuArchitecture 方法
+  - `lib/features/settings/presentation/general/general_settings_page.dart` — 增强对话框显示架构+实时状态，稍后重启显示 Toast
+  - `lib/features/settings/presentation/general/general_settings_sections.dart` — 副标题显示待重启标记
+  - `lib/l10n/types/t_settings_advanced.dart` — 新增 5 个翻译键定义
+  - `lib/l10n/languages/*.dart` — 14 个语言文件添加新翻译键
+
+---
+
+## [v6.123.0] - 2026-06-25
+
+### 🐛 修复（Intel Mac 渲染色差/字体割裂）
+
+#### Impeller 渲染引擎开关 — 默认值策略 + 立即重启 + i18n
+
+- **Issue**: Intel Mac 上页面跳转动画闪烁、字体模糊割裂、色差（前几次跳转正常，累积后出现）
+- **根因**: Flutter Impeller 渲染引擎在 Intel Mac 的 Metal 驱动上有渲染资源累积 bug，导致色差/字体割裂
+- **验证方法**:
+  1. 原生 AppKit demo（纯 Cocoa 渲染）排除硬件问题 — 字体显示正常，无异常色彩
+  2. 禁用 Impeller 后问题消失，确认根因在 Impeller
+- **方案**: 默认值策略 — Apple Silicon 开启 Impeller（性能更好），Intel Mac 关闭（避免色差）。用户可在「通用设置 → 高级」中手动覆盖，修改后需重启应用生效
+- **实现**:
+  1. **Info.plist**: 移除 `FLTEnableImpeller` 声明，由原生代码根据用户设置动态控制
+  2. **MainFlutterWindow.swift**:
+     - 手动创建 `FlutterDartProject`，通过 KVC 设置 `commandLineArguments`（`--enable-impeller`/`--no-enable-impeller`）
+     - 命令行参数优先级高于 Info.plist，可动态控制 Impeller 开关
+     - 新增 `shouldEnableImpeller()` 方法，通过 `object(forKey:)` 判断用户是否已显式设置：
+       - 已设置：返回用户设置的值
+       - 未设置（首次启动）：Apple Silicon 默认开启，Intel Mac 默认关闭
+  3. **AppDelegate.swift**:
+     - 新增 `getImpellerEnabled`/`setImpellerEnabled` MethodChannel 方法
+     - `getImpellerEnabled` 使用 `getImpellerEnabledWithDefault()` 保持与 `shouldEnableImpeller()` 逻辑一致
+     - 新增 `restartApp` 原生方法 — 通过 `NSWorkspace.openApplication` 启动新实例后 `NSApp.terminate` 终止当前实例
+  4. **MacosPlatformService.dart**: 新增 `getImpellerEnabled()`/`setImpellerEnabled()`/`restartApp()` 方法
+  5. **general_settings_sections.dart**: 高级分组新增 Impeller 开关（仅 macOS），使用 i18n 翻译键
+  6. **general_settings_page.dart**: 加载/切换 Impeller 状态，切换后弹出重启提示对话框（含"立即重启"和"稍后重启"两个按钮）
+  7. **i18n**: 为 14 个语言文件添加 8 个 Impeller 翻译键（zh_cn/zh_tw/en/ja/ko/fr/de/es/pt/ru/ar/hi/bn/it）
+- **涉及文件**:
+  - `macos/Runner/Info.plist` — 移除 FLTEnableImpeller
+  - `macos/Runner/MainFlutterWindow.swift` — 手动创建引擎传递命令行参数 + 默认值策略
+  - `macos/Runner/AppDelegate.swift` — Impeller MethodChannel + restartApp 方法
+  - `lib/core/services/device/macos_platform_service.dart` — Impeller 开关 + restartApp 方法
+  - `lib/features/settings/presentation/general/general_settings_sections.dart` — 高级分组 Impeller 开关
+  - `lib/features/settings/presentation/general/general_settings_page.dart` — 加载/切换 Impeller 状态 + 重启对话框
+  - `lib/l10n/types/t_settings_advanced.dart` — 新增 8 个 Impeller 翻译键定义
+  - `lib/l10n/languages/*.dart` — 14 个语言文件添加 Impeller 翻译
+
+---
+
+## [v6.122.0] - 2026-06-24
+
+### 🔧 维护（pro_image_editor 版本锁定）
+
+#### 1. pro_image_editor 版本锁定为 12.4.4
+- **Issue**: 本地暂存修改将 `pro_image_editor` 从 12.4.4 改为 ^12.4.8，与远程代码产生冲突
+- **原因**: 12.5.x 版本与 Flutter 3.33 运行时不兼容，需锁定到 12.4.4 确保稳定性
+- **修复**:
+  - `pubspec.macos.yaml`: 锁定 `pro_image_editor: 12.4.4`
+  - `pubspec.ohos.yaml`: 锁定 `pro_image_editor: 12.4.4`
+  - 注释说明 12.5.x 与 Flutter 3.33 运行时不兼容
+- **涉及文件**: `pubspec.macos.yaml`, `pubspec.ohos.yaml`
+
+---
+
 ## [v6.121.0] - 2026-06-24

 ### 🐛 修复（macOS 启动期闪退）