520kiss/xianyan

Fork 0

Files

Developer 1bca322600 鸿蒙白屏问题

2026-05-18 03:07:50 +08:00

61 KiB

Raw Blame History

Changelog

所有重要变更均记录于此文件。格式基于 Keep a Changelog。

[6.0.0] - 2026-05-18

🐛 修复鸿蒙端白屏问题 — 错误可见性 + ErrorBoundary + OHOS动画守卫

诊断Demo 27级测试全部通过，确认所有组件单独运行正常。白屏根因为 Catcher2 SilentReportMode 吞掉渲染错误 + 多处动画/BackdropFilter无OHOS守卫。本次修复让OHOS端错误可见、添加ErrorBoundary防白屏、所有动画加OHOS守卫。

核心修复

修改	文件	说明
Catcher2 OHOS错误可见	`lib/main.dart`	OHOS端添加 `_OhosConsoleHandler`，替代 SilentReportMode 吞错误
ErrorBoundary防白屏	`lib/shared/widgets/app_error_boundary.dart`	新建渲染错误边界组件，捕获异常显示错误页而非白屏
RootApp ErrorBoundary	`lib/app/app.dart`	OHOS端用 AppErrorBoundary 包裹根组件，渲染异常时显示重试按钮
OHOS调试日志	`lib/app/app.dart`	XianyanApp build 时输出主题/动画/字体配置日志

OHOS动画守卫（预防性修复）

修改	文件	说明
句子卡片入场动画	`home_page.dart`	`_SentenceCardWithSkeleton` OHOS端跳过 fadeIn+slideY+scale+shimmer
骨架屏shimmer	`home_page.dart`	`_LoadingSkeletonCard` OHOS端跳过 shimmer，使用静态骨架
每日推荐加载动画	`home_daily_card.dart`	OHOS端 rotate/fadeIn/scale/shimmer 参数归零或跳过
创作卡片BackdropFilter	`quick_card_sheet.dart`	OHOS端用纯色Container替代 BackdropFilter+blur

诊断Demo v3

文件	说明
`lib/main_ohos_diagnostic.dart`	27级测试覆盖：基础渲染(1-7)、依赖链(8-14)、深度测试(15-21)、主应用渲染模式(22-27)

[5.19.0] - 2026-05-18

♻️ 重构：设置Provider拆分 — 网络设置与隐私设置独立

从 general_settings_provider.dart 拆分出网络设置和隐私设置为独立子Provider，遵循单一职责原则，降低单文件复杂度，便于后续维护和扩展。

新增文件

文件	作用
`lib/features/settings/providers/sub/network_settings_provider.dart`	网络设置状态管理（代理/缓存策略/WiFi自动播放）
`lib/features/settings/providers/sub/privacy_settings_provider.dart`	隐私设置状态管理（应用锁/剪贴板读取/搜索历史）

拆分字段对照

子Provider	字段	原属
NetworkSettingsState	proxyEnabled, proxyHost, proxyPort, cacheStrategyId, autoPlayWifiOnly	GeneralSettingsState
PrivacySettingsState	appLockEnabled, clipboardReadEnabled, searchHistoryEnabled	GeneralSettingsState

设计说明

两个子Provider均使用 Notifier<State> 模式，与现有 GeneralSettingsNotifier 风格一致
存储键名保持 general_ 前缀不变，与原 GeneralSettingsState 的 KvStorage 键名兼容
NetworkSettingsState 通过 CacheStrategy.fromId() 引用 general_settings_provider.dart 中的枚举
setProxyEnabled/setProxyHost/setProxyPort 同步调用 NetworkProxyService 对应方法
setAppLockEnabled 同步调用 AppLockService.setEnabled()

[5.18.0] - 2026-05-18

🐛 修复系统状态栏颜色与软件主题不一致

移动端屏幕顶部系统状态栏背景色硬编码为黑色，导致浅色模式下状态栏与软件背景色不一致。同时导航栏颜色也硬编码为黑色，与主题不匹配。

问题根因

statusBarColor 硬编码 Colors.black：3处代码将状态栏背景色写死为黑色，浅色模式下与 #FAFAFA 背景色冲突
导航栏颜色硬编码：systemNavigationBarColor 和 systemNavigationBarDividerColor 同样写死为黑色
图标亮度不跟随主题：app_shell.dart 中状态栏图标亮度固定为亮色，浅色模式下黑色背景上显示深色图标不可见

修复方案

statusBarColor → Colors.transparent：透明状态栏，让应用实际背景色自然透出（现代 edge-to-edge 方案）
导航栏颜色 → Colors.transparent：透明导航栏，与毛玻璃底部栏配合
图标亮度跟随主题：浅色模式显示深色图标，深色模式显示浅色图标

修复文件清单

文件	修复内容
`main.dart`	启动时 SystemUiOverlayStyle: statusBarColor/navBarColor 改透明，图标亮度默认深色
`app.dart`	AnnotatedRegion: statusBarColor/navBarColor 改透明，图标亮度跟随 isDark 动态切换
`app_shell.dart`	AnnotatedRegion: 去掉 const，statusBarColor/navBarColor 改透明，图标亮度跟随 ext.isDark

🐛 修复 Riverpod Notifier 构造函数中使用 ref/state 导致鸿蒙端崩溃

鸿蒙端启动时崩溃：Bad state: Tried to use a notifier in an uninitialized state 根因：多个 Notifier 在构造函数中调用了使用 ref/state 的方法，但 Riverpod 的 Notifier 在构造函数执行时 ref 尚未初始化，只有 build() 被调用后 ref/state 才可用。

问题根因

构造函数中使用 ref/state：Riverpod Notifier 的 ref 和 state 在构造函数阶段不可用
影响范围：8个 Notifier 存在此反模式，其中 ToolCenterNotifier 是当前崩溃的直接原因

修复方案

将构造函数中的初始化逻辑移至 build() 方法
异步初始化使用 Future.microtask() 延迟到 build() 返回后执行
CanvasNotifier 的 late final 字段初始化器使用 ref.read() 也移至 build()

修复文件清单

文件	Notifier	修复内容
`tool_center_provider.dart`	ToolCenterNotifier	构造函数 `_loadPersistedData()`+`_initConnectivity()` → `build()` 中 `Future.microtask()`
`chat_attachment_provider.dart`	ChatAttachmentNotifier	构造函数 `_init()` → `build()` 中 `Future.microtask()`
`search_provider.dart`	SearchNotifier	构造函数 `_init()` → `build()` 中 `Future.microtask()`
`pomodoro_provider.dart`	PomodoroNotifier	构造函数 `_loadRecords()` → `build()` 中 `Future.microtask()`
`auth_provider.dart`	AuthNotifier	构造函数 `_init()` → `build()` 中 `Future.microtask()`
`chat_session_provider.dart`	ChatSessionNotifier	构造函数 `_init()` → `build()` 中 `Future.microtask()`
`device_discovery_provider.dart`	DeviceDiscoveryNotifier	构造函数 `Future.microtask(_init)` → `build()` 中 `Future.microtask(_init)`
`canvas_provider.dart`	CanvasNotifier	构造函数中 `ref.read()`+初始化 → `build()` 中执行

[5.17.8] - 2026-05-17

🐛 鸿蒙端白屏修复 — 数据库Migration未执行 + INSERT OR IGNORE兼容性

鸿蒙端依旧白屏，根因：SqfliteDelegate.open()传入version=14给sqflite.openDatabase()，导致sqflite自动将PRAGMA user_version设为14，Drift读取后认为数据库已是最新版本，跳过migration，结果所有表从未创建。同时INSERT OR IGNORE语法也不被OpenHarmony RDB支持。

白屏根因分析

sqflite.openDatabase(version:14) 跳过 Migration：sqflite打开新数据库时，自动执行PRAGMA user_version=14，Drift读取版本=14=schemaVersion，认为不需要创建表
INSERT OR IGNORE 不支持：OpenHarmony RDB不支持INSERT OR IGNORE语法，报syntax error

修复方案

去掉version参数：sqflite.openDatabase(_path) 不传version，让Drift通过_SqfliteVersionDelegate自行管理schema版本
INSERT OR IGNORE → INSERT OR REPLACE：在_adaptSql()中转换，OpenHarmony RDB支持REPLACE但不支持IGNORE
pu.isOhos替代Platform.operatingSystem：统一使用项目封装的平台检测方法

修复文件清单

文件	修复内容
`sqflite_delegate.dart`	去掉`_version`字段和`openDatabase(version:)`参数；添加INSERT OR IGNORE→REPLACE转换
`ohos.dart`	去掉`SqfliteDelegate(dbPath, 14)`中的version参数
`native.dart`	`Platform.operatingSystem=='ohos'` → `pu.isOhos`
`app_shell.dart`	自实现`_isOhos` → `pu.isOhos`；移除多余`dart:io`和`logger.dart`导入

版本管理流程（修复后）

1. sqflite.openDatabase(_path) — 不传version，数据库版本保持0
2. Drift读取 PRAGMA user_version → 0
3. Drift判断 0 < 14 → 执行 onCreate → m.createAll() → 创建所有表
4. Drift通过 _SqfliteVersionDelegate.setSchemaVersion(14) 设置版本
5. sqflite_ohos拦截 PRAGMA user_version = 14 → 使用 db.version = 14 API

[5.17.7] - 2026-05-17

🐛 鸿蒙端白屏修复 — SQL双引号标识符 + PRAGMA兼容性

鸿蒙端依旧白屏，根因：OpenHarmony RDB引擎不支持SQL双引号标识符（如"sentences"、"id"）， Drift生成的SQL使用双引号包裹标识符，导致所有数据库操作报syntax error。同时PRAGMA user_version = N写入和pragma_table_info(?)虚拟表函数也不被RDB支持。

白屏根因分析

双引号标识符不支持：OpenHarmony RDB的relationalStore不支持"table_name"语法，Drift生成的SQL全部使用双引号
PRAGMA写入不支持：PRAGMA user_version = N在RDB中无法执行，导致Drift schema版本写入失败
pragma_table_info虚拟表不支持：SELECT ... FROM pragma_table_info(?)在RDB中无法执行，导致migration中_safeAddColumn失败

修复方案

SqfliteDelegate._adaptSql()：在所有SQL执行前预处理，去除双引号标识符（正确处理字符串值中的转义单引号）
- SELECT * FROM "sentences" → SELECT * FROM sentences
- INSERT INTO "sentences" ("id", "content") → INSERT INTO sentences (id, content)
- 事务内_SqfliteTransactionQueryDelegate同样使用_adaptSql()
sqflite_ohos PRAGMA写入支持：在Database.execute()中拦截PRAGMA user_version = N，使用db.version = N API替代
sqflite_ohos pragma_table_info支持：在Database.doQuery()中拦截pragma_table_info(?)查询，转换为PRAGMA table_info(tableName)并在结果中筛选

修复文件清单

文件	修复内容
`sqflite_delegate.dart`	添加`_adaptSql()`方法，去除SQL双引号标识符；事务代理同样适配
`Database.ets` (sqflite_ohos)	添加`PRAGMA user_version = N`特殊处理（使用db.version API）
`Database.ets` (sqflite_ohos)	添加`pragma_table_info(?)`查询特殊处理（转换为PRAGMA table_info）
`OhosConstant.ets` (sqflite_ohos)	添加`SQL_PRAGMA_USER_VERSION_SET_PREFIX`常量

SQL适配示例

原始SQL:  SELECT * FROM "sentences" WHERE "id" = ?;
适配后:   SELECT * FROM sentences WHERE id = ?;

原始SQL:  INSERT OR IGNORE INTO "sentences" ("id", "content") VALUES (?, ?)
适配后:   INSERT OR IGNORE INTO sentences (id, content) VALUES (?, ?)

原始SQL:  PRAGMA user_version = 14
适配后:   db.version = 14 (使用RDB API)

原始SQL:  SELECT COUNT(*) AS cnt FROM pragma_table_info(?) WHERE name = ?
适配后:   PRAGMA table_info(tableName) + 结果筛选

[5.17.6] - 2026-05-17

🐛 鸿蒙端白屏修复 — Drift数据库适配 + 通知初始化修复

鸿蒙端启动白屏，根因：Drift数据库使用NativeDatabase(dart:ffi + sqlite3)在鸿蒙端无法加载SQLite原生库，导致Unsupported platform: ohos异常，数据库操作全部失败。同时通知服务缺少OhosInitializationSettings。

白屏根因分析

Drift数据库引擎不兼容：NativeDatabase依赖sqlite3包通过dart:ffi加载SQLite，鸿蒙端无此原生库
sqflite_ohos已注册但未桥接：sqflite_ohos作为鸿蒙端SQLite插件已注册，但Drift未使用它
通知初始化缺少Ohos配置：InitializationSettings未传入ohos参数，导致鸿蒙端通知初始化失败

修复方案

SqfliteDelegate适配器：创建SqfliteDelegate类，将sqflite的API桥接为Drift的DatabaseDelegate
- 实现DatabaseDelegate抽象方法（runSelect/runInsert/runUpdate/runCustom/runBatched）
- 实现DynamicVersionDelegate（通过PRAGMA user_version管理schema版本）
- 实现SupportedTransactionDelegate（利用sqflite的transaction API）
- 事务内使用_SqfliteTransactionQueryDelegate代理QueryDelegate
运行时平台检测：在native.dart中检测Platform.operatingSystem == 'ohos'，自动切换到sqflite后端
通知服务修复：三个通知服务文件均增加OhosInitializationSettings

修复文件清单

文件	修复内容
`database_connection/sqflite_delegate.dart`	🆕 新建 — SqfliteDelegate适配器，桥接sqflite→Drift DatabaseDelegate
`database_connection/ohos.dart`	🆕 新建 — OpenHarmony数据库连接，使用sqflite_ohos后端
`database_connection/native.dart`	运行时检测`Platform.operatingSystem == 'ohos'`，自动切换到sqflite后端
`app_database.dart`	更新文件头注释
`local_notification_service.dart`	增加`OhosInitializationSettings`配置
`notification_service.dart` (core)	增加`OhosInitializationSettings`配置
`notification_service.dart` (file_transfer)	增加`OhosInitializationSettings`配置

架构说明

Drift (ORM层)
  ├── NativeDatabase (Android/iOS/macOS/Windows/Linux) — dart:ffi + sqlite3
  └── SqfliteDelegate (OpenHarmony) — sqflite_ohos 插件
        ├── DatabaseDelegate → sqflite.Database
        ├── DynamicVersionDelegate → PRAGMA user_version
        └── SupportedTransactionDelegate → sqflite.transaction()

[5.17.5] - 2026-05-17

🐛 鸿蒙端白屏修复 — 全量平台兼容性适配

鸿蒙端启动白屏，根因：Platform.isAndroid在鸿蒙端返回true，导致Android专属API被调用后崩溃。新增pu.isOhos平台检测，全量扫描修复38处Platform.isXxx使用，增加鸿蒙端分支处理。

白屏根因分析

main.dart无try-catch的初始化：LiquidGlassWidgets.initialize()和Platform3DService.detectDeviceCapability()在鸿蒙端可能失败，未捕获异常导致整个App崩溃白屏
通知服务Platform.isAndroid：鸿蒙端走Android分支获取AndroidFlutterLocalNotificationsPlugin，但实际应使用OhosFlutterLocalNotificationsPlugin
设备信息服务：鸿蒙端设备ID前缀应为ohos_而非android_

修复文件清单

文件	修复内容
`main.dart`	为`LiquidGlassWidgets`/`Platform3DService`/`_validatePageRegistry`增加try-catch
`local_notification_service.dart`	通知权限请求增加鸿蒙分支(`OhosFlutterLocalNotificationsPlugin`)
`notification_service.dart` (core)	通知权限请求增加鸿蒙分支
`notification_service.dart` (file_transfer)	平台检测+通知权限+进度通知增加鸿蒙处理
`device_info_service.dart`	设备ID/名称/型号/平台识别增加鸿蒙分支
`permission_service.dart`	存储权限鸿蒙端跳过(无需Android存储权限)
`share_sheet.dart`	分享功能平台检测增加鸿蒙
`sharing_receiver_service.dart`	分享接收平台分支增加鸿蒙
`device_discovery_provider.dart`	BLE/NFC/USB平台能力检测增加鸿蒙
`nearby_service_adapter.dart`	Wi-Fi Direct平台支持+权限检查增加鸿蒙
`localsend_service.dart`	设备型号检测增加HarmonyOS
`hotspot_service.dart`	WiFi热点平台支持+SDK版本检测增加鸿蒙
`bluetooth_pairing_service.dart`	BLE平台支持+广播检测增加鸿蒙
`qr_pairing_service.dart`	QR扫码平台支持增加鸿蒙
`usb_discovery_service.dart`	USB发现平台检测增加鸿蒙
`usb_transport_service.dart`	USB传输6处平台检测全部增加鸿蒙
`transfer_file_handler.dart`	Wi-Fi Direct权限+USB传输平台检测增加鸿蒙

核心平台检测机制

platform_io_native.dart：_isOhos()通过Platform.operatingSystem == 'ohos'检测
platform_io_stub.dart：Web端isOhosImpl返回false
platform_utils.dart：暴露isOhos属性
device_detection.dart：_isHarmonyOS()使用pu.isOhos
关键：isAndroidImpl已排除鸿蒙(Platform.isAndroid && !_isOhos())

[5.17.4] - 2026-05-17

🔧 ArkTS编译错误全量修复 — 45→0个ERROR

从45个ArkTS编译错误逐步修复至0个，HAP构建成功。涉及6个原生插件的API兼容性修复。

修复清单

插件	错误	修复方案
network_info_plus_ohos	`WifiLinkedInfo`无`gateway`/`netMask`属性	`getWifiSubmask`/`getWifiGatewayAddress`/`getWifiBroadcast`返回null
nearby_service	`wifiP2p`不在`@kit.ConnectivityKit`中	改用`wifiManager`（P2P API的正确入口）
nearby_service	`socket.NetFamily`/`NetFamilyType`不存在	TCP连接family参数改为数字`1`(IPv4)
home_widget	`FormInfo`无`id`/`formId`属性	改用`formProvider.getPublishedRunningFormInfos()`获取`RunningFormInfo`
home_widget	`preferences.get`返回`ValueType`不能`as string`	改用`.toString()`
home_widget	`call.argument()`返回`any`类型	显式标注`as number`
home_widget	`Record<string, Object>`不匹配`startAbility`参数	改用`Want`类型
gal	`showAssetsCreationRequest`不存在	改用`showAssetsCreationDialog`（系统弹窗授权保存）
gal	`Record<string, Object>`不匹配`startAbility`参数	改用`Want`类型
gal	`Error \| unknown`不允许	改用`ESObject`
EntryAbility	`MethodCall`导入路径错误	从`MethodCall.ets`独立导入
EntryAbility	`app_links_ohos`模块路径不存在	移除未使用的导入和变量
EntryAbility	`MIME_TEXT_PLAIN`不存在	改为`MIMETYPE_TEXT_PLAIN`

关键API变更说明

wifiP2p → wifiManager: HarmonyOS 5中P2P API通过import { wifiManager } from '@kit.ConnectivityKit'导入，方法名也有变化（p2pConnect而非connect）
FormInfo → RunningFormInfo: FormInfo是卡片配置信息（无formId），RunningFormInfo是运行时信息（有formId），需用getPublishedRunningFormInfos()获取
showAssetsCreationDialog: 替代showAssetsCreationRequest，通过系统弹窗授权保存媒体文件，无需WRITE_IMAGEVIDEO权限

[5.17.3] - 2026-05-17

🔒 受限ACL权限优化 — 5→0个受限权限

DevEco Studio警告5个受限ACL权限需要审核。通过安全组件替代方案，全部移除受限权限，无需ACL审核即可发布。

受限权限	替代方案	说明
WRITE_IMAGEVIDEO	`showAssetsCreationRequest`	gal插件改用系统安全弹窗授权保存媒体
READ_IMAGEVIDEO	`PhotoViewPicker`	image_picker已使用系统选择器
READ_WRITE_DOWNLOAD_DIRECTORY	`DocumentViewPicker`	file_picker已使用系统文件选择器
FILE_ACCESS_PERSIST	`DocumentViewPicker`	file_picker已使用系统文件选择器
READ_PASTEBOARD	`ClipboardBridge` + 原生MethodChannel	通过EntryAbility原生桥接读取剪贴板

gal插件改造

createAssetRequest → showAssetsCreationRequest：系统弹出授权对话框
putImageBytes：先写入临时文件，再通过系统安全组件保存
hasAccess / requestAccess：直接返回true，由系统安全组件处理授权
移除 abilityAccessCtrl / bundleManager 依赖

剪贴板桥接

新增 ClipboardBridge (lib/core/utils/clipboard_bridge.dart)
EntryAbility 注册 clipboard_ohos MethodChannel
通过 pasteboard.getSystemPasteboard().getDataSync() 读取剪贴板

代码修复

nfc_pairing_service.dart: NdefRecord(ndef_record) → ndef.NDEFRecord(ndef)，修复类型不匹配
pro_image_editor/hvigorfile.ts: 移除未使用的 path 导入
pubspec.yaml: 移除已弃用的 ndef_record 依赖

[5.17.2] - 2026-05-17

🔌 鸿蒙适配 — 全量审计 + 构建修复

对pubspec.yaml所有依赖进行全量鸿蒙适配审计，分类为本地化原生插件(32个)、TPC远程适配(3个)、纯Dart包(50个)。修复构建错误，补全宿主应用权限声明和资源字符串。

全量依赖审计

分类	数量	说明
本地化原生插件	32个	packages/目录下已有ohos适配代码
TPC远程适配	3个	flutter_image_compress_ohos/device_info_plus/package_info_plus
纯Dart包	50个	无需ohos适配

构建错误修复

文件	修复内容
video_compress/oh-package.json5	`@ohos/flutter_ohos` 行末缺少逗号导致JSON5解析失败
home_widget/ohos/hvigorfile.ts	缺失构建文件，创建 `export { harTasks } from '@ohos/hvigor-ohos-plugin'`
nearby_service/ohos/hvigorfile.ts	缺失构建文件，同上

宿主应用权限补全

修复项	说明
Entry module.json5	添加tablet设备类型 + 补全12项权限声明
base/string.json	添加9个权限描述字符串(英文)
zh_CN/string.json	添加9个权限描述字符串(中文)

鸿蒙适配计划文档更新

鸿蒙适配计划-第三批次.md 新增"全量依赖审计"章节(2.1-2.5)
包含32个本地化插件审计表、3个TPC远程包、50个纯Dart包清单
宿主应用17项权限审计对照表
15项审计修复记录汇总

[5.17.1] - 2026-05-17

🔌 鸿蒙适配 — 第三方包审计修复 + NFC迁移TPC

对所有鸿蒙适配的第三方包进行全面审计，修复空实现方法、缺失权限、配置不一致等问题。将NFC包从自适配的nfc_manager迁移到TPC官方适配的flutter_nfc_kit。统一所有包的HAR引用路径。

NFC包迁移: nfc_manager → flutter_nfc_kit (TPC官方适配)

变更	说明
新增 flutter_nfc_kit	TPC官方适配包 (v3.6.0-rc.6-ohos)，支持标签轮询/数据传输/NDEF读写
pubspec.yaml 更新	`nfc_manager: path: packages/nfc_manager` → `flutter_nfc_kit: path: packages/flutter_nfc_kit`
nfc_pairing_service.dart	迁移到 FlutterNfcKit API (poll/transceive)

空实现方法修复

包名	修复方法	实现方式
gal	hasAccess()	使用 abilityAccessCtrl.verifyAccessTokenSync 检查权限
gal	requestAccess()	使用 abilityAccessCtrl.requestPermissionsFromUser 请求权限
gal	open()	使用 context.startAbility 打开图库
home_widget	requestPinWidget()	使用 context.startAbility + ADD_FORM action
home_widget	registerBackgroundCallback()	持久化回调句柄到 Preferences
home_widget	isRequestPinWidgetSupported()	检测 formInfo.FormVisibility 可用性
nearby_service	send()	使用 @ohos.net.socket TCP Socket 传输数据
nearby_service	startAdvertising()	使用 wifiP2p.createGroup 创建P2P组
nearby_service	stopAdvertising()	使用 wifiP2p.removeGroup 移除P2P组
nearby_service	openServicesSettings()	使用 context.startAbility 打开WiFi设置

module.json5 权限和设备类型修复

包名	修复内容
gal	添加 READ/WRITE_IMAGEVIDEO 权限 + tablet 设备类型
nearby_service	添加 SET_WIFI_INFO/GET_WIFI_INFO/LOCATION/INTERNET 权限
network_info_plus_ohos	添加 GET_WIFI_INFO 权限
video_compress	添加 tablet 设备类型
mobile_scanner	添加 tablet 设备类型 + 修复JSON尾部逗号
flutter_blue_plus_ohos	添加 ACCESS_BLUETOOTH/LOCATION 权限
wifi_iot	添加 GET_WIFI_INFO/SET_WIFI_INFO/LOCATION 权限
nfc_manager_ohos	deviceTypes phone→default + 添加 NFC_TAG 权限
home_widget	添加 FormExtension 声明 + grid 卡片配置

HAR引用路径统一

将所有包的 @ohos/flutter_ohos 依赖路径统一为 file:./har/flutter.har（TPC标准路径），涉及15个包的 oh-package.json5 修复：

nfc_manager_ohos: file:./har/flutter_ohos.har → file:./har/flutter.har
video_compress: file:./libs/flutter_embedding.har → file:./har/flutter.har
connectivity_plus: file:./libs/flutter_embedding.har → file:./har/flutter.har
pro_image_editor: file:../../../libs/flutter.har → file:./har/flutter.har
nearby_service: file:../../../libs/flutter.har → file:./har/flutter.har
home_widget: file:../../../libs/flutter.har → file:./har/flutter.har
app_links_ohos: file:../../../libs/flutter.har → file:./har/flutter.har
flutter_webrtc: file:../libs/flutter.har → file:./har/flutter.har
mobile_scanner: file:libs/flutter.har → file:./har/flutter.har
sqflite_ohos: file:har/flutter.har → file:./har/flutter.har
audioplayers_ohos: file:har/flutter.har → file:./har/flutter.har
fluttertoast_ohos: file:../../../libs/flutter.har → file:./har/flutter.har
image_picker_ohos: file:libs/flutter.har → file:./har/flutter.har
path_provider_ohos: file:libs/flutter.har → file:./har/flutter.har
shared_preferences_ohos: file:libs/flutter.har → file:./har/flutter.har

app_links 深度链接集成

EntryAbility.ets 添加 onCreate/onNewWant 回调处理深度链接URI

[5.17.0] - 2026-05-16

🔌 鸿蒙适配 — flutter_webrtc 完整WebRTC音视频通信

完成flutter_webrtc鸿蒙ohos完整适配。合并TPC社区 fluttertpc_flutter_webrtc 的完整实现，包含预编译的 libohos_webrtc.so C++库（基于WebRTC M120），69个MethodChannel方法全部实现。Dart端新增ohos平台视图渲染和音频配置支持。

新增本地化鸿蒙适配包

库	版本	适配模式	本地路径	用途
`flutter_webrtc`	v1.4.0-ohos.1	直接插件	packages/flutter_webrtc	WebRTC音视频通信
`webrtc_interface`	v1.5.1	纯Dart接口	packages/webrtc_interface	WebRTC平台接口定义

TPC社区库合并

源仓库	版本	说明
`openharmony-sig/fluttertpc_flutter_webrtc`	v0.9.48+hotfix.1	TPC社区完整ohos适配
`openharmony-sig/ohos_webrtc`	M120	预编译WebRTC C++库

flutter_webrtc ohos原生实现功能

功能模块	方法数	ohos支持	说明
initialize	1	✅	PeerConnectionFactory初始化
createPeerConnection	1	✅	创建PC对象+Observer
createOffer/Answer	2	✅	SDP协商
setLocal/RemoteDescription	2	✅	设置本地/远端描述
addIceCandidate	1	✅	添加ICE候选
getUserMedia	1	✅	摄像头+麦克风采集
getDisplayMedia	1	✅	屏幕共享
DataChannel	3	✅	create/send/close
MediaStream管理	6	✅	getTracks/addTrack/removeTrack等
视频渲染	3	✅	Texture+PlatformView双模式
RTP管理	10	✅	Sender/Receiver/Transceiver
音频管理	7	✅	音量/静音/扬声器/蓝牙
getStats	1	✅	统计信息
FrameCryptor	5	✅	帧加密
录制	2	⏳ TODO	startRecordToFile/stopRecordToFile
其他方法	24	✅/⏳	大部分已实现，少量TODO

MethodChannel: FlutterWebRTC.Method EventChannel: FlutterWebRTC.Event

ohos/目录结构

ohos/
├── Index.ets
├── oh-package.json5          ← 引用 libohos_webrtc.so + flutter.har
├── build-profile.json5
├── hvigorfile.ts
├── libs/
│   └── arm64-v8a/
│       └── libohos_webrtc.so ← 预编译WebRTC C++库(50MB)
├── src/main/
│   ├── module.json5          ← INTERNET/CAMERA/MICROPHONE权限
│   ├── libohos_webrtc/
│   │   ├── index.d.ts
│   │   ├── webrtc.d.ts       ← 1030行WebRTC API类型定义
│   │   └── oh-package.json5
│   ├── ets/
│   │   ├── FlutterWebRTCPlugin.ets      ← 主插件入口
│   │   ├── MethodCallHandlerImpl.ets    ← 1662行方法处理器
│   │   ├── MethodHandlers.ets           ← 方法路由表
│   │   ├── PeerConnectionObserver.ets   ← PC事件观察者
│   │   ├── DataChannelObserver.ets      ← DC事件观察者
│   │   ├── GetUserMediaImpl.ets         ← 媒体采集
│   │   ├── FlutterRTCVideoRenderer.ets  ← 视频渲染
│   │   ├── FlutterRTCFrameCryptor.ets   ← 帧加密
│   │   ├── SurfaceTextureRenderer.ets   ← 纹理渲染
│   │   ├── StateProvider.ets            ← 状态管理
│   │   ├── LifeCycleObserver.ets        ← 生命周期
│   │   ├── DependencyRelated.ets        ← 依赖管理
│   │   ├── AudioSwitchManager.ets       ← 音频切换
│   │   ├── AudioChannel.ets             ← 音频录制
│   │   ├── components/                  ← PlatformView组件
│   │   └── utils/                       ← 工具类(12个文件)
│   └── resources/

Dart端修改

文件	修改内容
`lib/src/native/utils.dart`	新增 `platformIsOhos` 平台检测
`lib/src/native/camera_utils.dart`	5处平台判断添加ohos分支
`lib/src/native/rtc_video_view_impl.dart`	ohos PlatformView视频渲染
`lib/src/native/rtc_video_renderer_impl.dart`	surfaceId字段(ohos渲染必需)
`lib/src/native/ohos/audio_configuration.dart`	ohos音频配置(新增)
`lib/src/native/ohos/video_render.dart`	ohos视频渲染组件(新增)
`lib/src/helper.dart`	setOhosAudioConfiguration方法
`lib/src/web/utils.dart`	platformIsOhos返回false

使用的鸿蒙API

libohos_webrtc.so — 预编译WebRTC C++库(基于M120)
@kit.CameraKit — 摄像头采集
@kit.AudioKit — 音频采集/播放/设备管理
@kit.AbilityKit — UIAbility生命周期管理

已完成鸿蒙适配的包汇总（共31个）

#	包名	适配模式	批次
1	shared_preferences	联合插件	1
2	path_provider	联合插件	1
3	url_launcher	联合插件	1
4	image_picker	联合插件	1
5	local_auth	联合插件	1
6	video_player	联合插件	1
7	permission_handler	联合插件	1
8	flutter_secure_storage	联合插件	1
9	share_plus	联合插件	1
10	battery_plus	联合插件	1
11	connectivity_plus	直接插件	1
12	flutter_local_notifications	直接插件	2
13	file_picker	直接插件	2
14	receive_sharing_intent	直接插件	2
15	wakelock_plus	直接插件	2
16	mobile_scanner	直接插件	2
17	wifi_iot	直接插件	2
18	audioplayers	联合插件	2
19	record	联合插件	2
20	sqflite	联合插件	2
21	fluttertoast	直接插件	1
22	video_compress	直接插件	3
23	flutter_blue_plus	联合插件	3
24	gal	直接插件	3
25	network_info_plus	联合插件	3
26	app_links	联合插件	3
27	pro_image_editor	直接插件	3
28	home_widget	直接插件	3
29	nfc_manager	联合插件	3
30	nearby_service	直接插件	3
31	flutter_webrtc	直接插件	4

[5.16.0] - 2026-05-16

🔌 鸿蒙适配 — app_links 深度链接 + pro_image_editor 图片编辑

新增 app_links 和 pro_image_editor 鸿蒙适配。app_links 采用联合插件模式，支持深度链接获取和监听；pro_image_editor 采用直接插件模式，支持emoji可用性检测。

新增本地化鸿蒙适配包

库	版本	适配模式	本地路径	用途
`app_links`	v7.0.0-ohos.1	联合插件	packages/app_links + app_links_ohos	深度链接/Universal Links
`pro_image_editor`	v12.4.4-ohos.1	直接插件	packages/pro_image_editor	图片编辑器

app_links ohos原生实现功能

MethodChannel方法	功能	ohos支持
`getInitialLink`	获取启动时的初始链接	✅
`getLatestLink`	获取最新深度链接	✅
EventChannel	监听onNewWant新链接事件	✅

MethodChannel: com.llfbandit.app_links/messages EventChannel: com.llfbandit.app_links/events

使用的鸿蒙API

UIAbility.onCreate(want) → want.uri 获取初始链接
UIAbility.onNewWant(want) → want.uri 获取新链接
module.json5中的 skills 配置声明URL scheme

pro_image_editor ohos原生实现功能

MethodChannel方法	功能	ohos支持
`getSupportedEmojis`	检测emoji是否被系统字体支持	✅ 简化实现，全部返回true

MethodChannel: pro_image_editor

已完成鸿蒙适配的包汇总（共24个）

#	包名	适配模式
1	shared_preferences	联合插件
2	path_provider	联合插件
3	url_launcher	联合插件
4	image_picker	联合插件
5	local_auth	联合插件
6	video_player	联合插件
7	permission_handler	联合插件
8	flutter_secure_storage	联合插件
9	share_plus	联合插件
10	battery_plus	联合插件
11	connectivity_plus	直接插件
12	flutter_local_notifications	直接插件
13	file_picker	直接插件
14	receive_sharing_intent	直接插件
15	wakelock_plus	直接插件
16	mobile_scanner	直接插件
17	wifi_iot	直接插件
18	audioplayers	联合插件
19	record	联合插件
20	sqflite	联合插件
21	fluttertoast	直接插件
22	network_info_plus	联合插件
23	app_links	联合插件
24	pro_image_editor	直接插件

[5.15.0] - 2026-05-16

🔌 鸿蒙适配 — network_info_plus WiFi网络信息

新增 network_info_plus 鸿蒙适配，采用联合插件模式。支持获取WiFi SSID、BSSID、IPv4地址、子网掩码、网关IP和广播地址。

新增本地化鸿蒙适配包

库	版本	适配模式	本地路径	用途
`network_info_plus`	v8.1.0-ohos.1	联合插件	packages/network_info_plus + network_info_plus_ohos	WiFi网络信息

ohos原生实现功能

MethodChannel方法	功能	ohos支持
`wifiName`	WiFi SSID	✅
`wifiBSSID`	WiFi BSSID	✅
`wifiIPAddress`	IPv4地址	✅
`wifiIPv6Address`	IPv6地址	❌ 返回null
`wifiSubmask`	子网掩码	✅
`wifiGatewayAddress`	网关IP	✅
`wifiBroadcast`	广播地址	✅

使用的鸿蒙API

@kit.ConnectivityKit → wifiManager.getLinkedInfo() 获取WiFi连接信息
@kit.NetworkKit → connection 网络连接（预留）

所需权限

"requestPermissions": [
  { "name": "ohos.permission.GET_WIFI_INFO" }
]

已完成鸿蒙适配的包汇总（共22个）

#	包名	适配模式
1	shared_preferences	联合插件
2	path_provider	联合插件
3	url_launcher	联合插件
4	image_picker	联合插件
5	local_auth	联合插件
6	video_player	联合插件
7	permission_handler	联合插件
8	flutter_secure_storage	联合插件
9	share_plus	联合插件
10	battery_plus	联合插件
11	connectivity_plus	直接插件
12	flutter_local_notifications	直接插件
13	file_picker	直接插件
14	receive_sharing_intent	直接插件
15	wakelock_plus	直接插件
16	mobile_scanner	直接插件
17	wifi_iot	直接插件
18	audioplayers	联合插件
19	record	联合插件
20	sqflite	联合插件
21	fluttertoast	直接插件
22	network_info_plus	联合插件

[5.15.0] - 2026-05-16

🔌 鸿蒙适配 — 第三批次（无TPC官方适配包自行编写）

9个无TPC官方适配的包完成鸿蒙ohos适配，其中2个使用TPC已有适配合并，7个自行编写ohos原生代码。

TPC已有适配包合并

库	版本	适配模式	本地路径	用途
`video_compress`	v3.1.2-ohos.1	直接插件	packages/video_compress	视频压缩（含FFmpeg C/C++原生库）
`flutter_blue_plus`	v2.1.0-ohos.1	联合插件	packages/flutter_blue_plus + flutter_blue_plus_ohos	蓝牙BLE通信

自行编写ohos适配代码

库	版本	适配模式	本地路径	用途	鸿蒙API
`gal`	v2.3.0-ohos.1	直接插件	packages/gal	保存图片/视频到相册	@ohos.file.photoAccessHelper
`network_info_plus`	v8.1.0-ohos.1	联合插件	packages/network_info_plus + network_info_plus_ohos	WiFi网络信息	@ohos.wifi.wifiManager
`app_links`	v7.0.0-ohos.1	联合插件	packages/app_links + app_links_ohos	深度链接处理	@ohos.app.ability.Want
`pro_image_editor`	v12.4.4-ohos.1	直接插件	packages/pro_image_editor	图片编辑器(emoji检测)	简化实现
`home_widget`	v0.9.1-ohos.1	直接插件	packages/home_widget	桌面小组件	@ohos.app.form.formProvider
`nfc_manager`	v4.2.1-ohos.1	联合插件	packages/nfc_manager + nfc_manager_ohos	NFC读写	@ohos.nfc.tag / @ohos.nfc.ndef
`nearby_service`	v0.2.1-ohos.1	直接插件	packages/nearby_service	近场设备发现	@ohos.wifi.p2p

pubspec.yaml 变更

9个库从pub.dev远程引用改为 path: packages/xxx 本地引用
dependency_overrides 新增9个本地包及其_ohos子包覆写

版本兼容性修复

包	问题	修复
`app_links`	monorepo结构导致pubspec name不匹配	提取子目录为独立包，移除workspace配置
`nfc_manager_ohos`	依赖nfc_manager导致循环引用	改为依赖nfc_manager_platform_interface

待完善功能 (TODO)

home_widget: requestPinWidget、registerBackgroundCallback
nearby_service: send消息传输、startAdvertising
nfc_manager: 标签发现监听、NDEF读写、标签类型操作
gal: open打开相册
flutter_webrtc: 暂缓适配（需编译WebRTC C++库）

已完成鸿蒙适配的包汇总（共30个）

#	包名	适配模式	批次
1	shared_preferences	联合插件	1
2	path_provider	联合插件	1
3	url_launcher	联合插件	1
4	image_picker	联合插件	1
5	local_auth	联合插件	1
6	video_player	联合插件	1
7	permission_handler	联合插件	1
8	flutter_secure_storage	联合插件	1
9	share_plus	联合插件	1
10	battery_plus	联合插件	1
11	connectivity_plus	直接插件	1
12	flutter_local_notifications	直接插件	2
13	file_picker	直接插件	2
14	receive_sharing_intent	直接插件	2
15	wakelock_plus	直接插件	2
16	mobile_scanner	直接插件	2
17	wifi_iot	直接插件	2
18	audioplayers	联合插件	2
19	record	联合插件	2
20	sqflite	联合插件	2
21	fluttertoast	直接插件	1
22	video_compress	直接插件	3
23	flutter_blue_plus	联合插件	3
24	gal	直接插件	3
25	network_info_plus	联合插件	3
26	app_links	联合插件	3
27	pro_image_editor	直接插件	3
28	home_widget	直接插件	3
29	nfc_manager	联合插件	3
30	nearby_service	直接插件	3

🔌 鸿蒙适配 — 全量TPC包合并（第二批次）

将9个TPC鸿蒙适配包合并到本地packages目录，涵盖直接插件模式和联合插件模式两种适配方案。同时修复版本兼容性问题。

新增本地化鸿蒙适配包

库	版本	适配模式	本地路径	用途
`flutter_local_notifications`	v21.0.0-ohos.1	直接插件	packages/flutter_local_notifications	本地推送通知
`file_picker`	v8.3.7-ohos.1	直接插件	packages/file_picker	文件选择器
`receive_sharing_intent`	v1.8.1-ohos.1	直接插件	packages/receive_sharing_intent	接收外部分享
`wakelock_plus`	v1.4.0-ohos.1	直接插件	packages/wakelock_plus	屏幕常亮控制
`mobile_scanner`	v7.1.4-ohos.1	直接插件	packages/mobile_scanner	二维码/条形码扫描
`wifi_iot`	v0.3.19-ohos.1	直接插件	packages/wifi_iot	WiFi IoT设备连接
`audioplayers`	v6.5.0-ohos.1	联合插件	packages/audioplayers + audioplayers_ohos	音频播放
`record`	v6.0.0-ohos.1	联合插件	packages/record + record_ohos	录音
`sqflite`	v2.4.1-ohos.1	联合插件	packages/sqflite + sqflite_ohos + sqflite_common + sqflite_platform_interface	SQLite数据库

适配模式说明

直接插件模式: ohos原生代码直接放在主包的 ohos/ 目录中，pubspec.yaml声明 ohos: pluginClass: XXXPlugin
联合插件模式: 主包声明 ohos: default_package: xxx_ohos，独立的 *_ohos 子包包含Dart端和原生端实现

版本兼容性修复

包	问题	修复
`share_plus_ohos`	share_plus_platform_interface 版本冲突 (^6.1.0 vs ^7.1.0)	放宽为 ">=6.1.0 <8.0.0"
`record_ohos`	uuid 版本冲突 (^3.0.7 vs ^4.5.0)	放宽为 ">=3.0.7 <5.0.0"
`video_player_ohos`	pigeon 版本冲突导致 analyzer 不兼容	升级 pigeon ^22.6.0 → ^26.0.0

pubspec.yaml 变更

6个库从pub.dev远程引用改为 path: packages/xxx 本地引用
dependency_overrides 新增9个本地包及其_ohos子包覆写
sqflite 从 any 改为本地路径引用

已完成鸿蒙适配的包汇总（共21个）

#	包名	适配模式
1	shared_preferences	联合插件
2	path_provider	联合插件
3	url_launcher	联合插件
4	image_picker	联合插件
5	local_auth	联合插件
6	video_player	联合插件
7	permission_handler	联合插件
8	flutter_secure_storage	联合插件
9	share_plus	联合插件
10	battery_plus	联合插件
11	connectivity_plus	直接插件
12	flutter_local_notifications	直接插件
13	file_picker	直接插件
14	receive_sharing_intent	直接插件
15	wakelock_plus	直接插件
16	mobile_scanner	直接插件
17	wifi_iot	直接插件
18	audioplayers	联合插件
19	record	联合插件
20	sqflite	联合插件
21	fluttertoast	直接插件

待适配包（无TPC官方适配）

home_widget — 桌面小组件
pro_image_editor — 图片编辑器
nearby_service — 近场设备发现
gal — 保存图片/视频到相册
nfc_manager — NFC读写
video_compress — 视频压缩
flutter_blue_plus — 蓝牙BLE通信
app_links — 深度链接处理
network_info_plus — WiFi网络信息
flutter_webrtc — WebRTC音视频通信

[5.13.0] - 2026-05-16

🔌 鸿蒙适配 — local_auth_ohos 平台实现合并

将 TPC 仓库的 local_auth_ohos 子包合并到本地 packages 目录，完成 local_auth 插件的鸿蒙平台适配。

变更内容

操作	说明
复制 `local_auth_ohos`	从 `_tpc_temp/flutter_packages_la/packages/local_auth/local_auth_ohos` → `packages/local_auth_ohos`
删除 example 目录	移除 `packages/local_auth_ohos/example/`（不需要本地示例）
更新 `local_auth` pubspec.yaml	添加 `ohos` 平台声明、`local_auth_ohos` 本地路径依赖、版本号 `3.0.1` → `3.0.1-ohos.1`

local_auth pubspec.yaml 变更明细

version: 3.0.1 → 3.0.1-ohos.1
flutter.plugin.platforms 新增: ohos: default_package: local_auth_ohos
dependencies 新增: local_auth_ohos: path: ../local_auth_ohos

local_auth_ohos 包结构

packages/local_auth_ohos/
├── lib/           # Dart 端实现 (LocalAuthOhos, AuthMessagesOhos, OhosAuthErrorCode)
├── ohos/          # 鸿蒙原生端实现 (LocalAuthPlugin.ets, AuthenticationHelper.ets)
├── test/          # 单元测试
└── pubspec.yaml   # 版本 2.0.0

[5.12.0] - 2026-05-16

📦 关键库本地化 — 鸿蒙适配准备 + font_management_page恢复

将10个含原生代码的关键库下载到本地packages/目录，方便后续鸿蒙适配魔改。恢复font_management_page完整功能并完成Riverpod 3.x迁移。

本地化关键库（鸿蒙适配准备）

库	远程版本	本地路径	用途
`shared_preferences`	v2.5.5	packages/shared_preferences	轻量KV持久化
`flutter_secure_storage`	v9.2.4	packages/flutter_secure_storage	加密安全存储
`path_provider`	v2.1.5	packages/path_provider	系统目录路径获取
`connectivity_plus`	v7.1.1	packages/connectivity_plus	网络连接状态监听
`permission_handler`	v12.0.1	packages/permission_handler	运行时权限请求
`flutter_local_notifications`	v21.0.0	packages/flutter_local_notifications	本地推送通知
`url_launcher`	v6.3.2	packages/url_launcher	打开外部URL/应用
`file_picker`	v8.3.7	packages/file_picker	文件选择器
`image_picker`	v1.2.2	packages/image_picker	相机/相册选图
`local_auth`	v3.0.1	packages/local_auth	生物识别认证

pubspec.yaml 变更

10个库从远程版本引用改为 path: packages/xxx 本地引用
dependency_overrides 新增10个本地包覆写，确保远程依赖也使用本地版本
nearby_service 本地包的 path_provider 依赖改为本地路径引用

font_management_page 恢复与迁移

恢复完整版字体管理页面（1623行，含字体下载/导入/动态加载/主题集成）
Riverpod 3.x迁移：StateNotifier → Notifier，_ref → ref
添加缺失import：cupertino、material、riverpod、AppSpacing、AppTheme、AppTypography
context.pop() → Navigator.of(context).pop()

FilePicker API 适配

本地化 file_picker v8.3.7 使用 FilePicker.platform.pickFiles()
所有 FilePicker.pickFiles() 回退为 FilePicker.platform.pickFiles()
影响文件：xycard_io_native、image_import_service、transfer_chat_page、chat_attachment_provider、data_management_page、font_management_page

flutter analyze 结果

17 issues found (零Error，仅Warning/Info级别)

[5.11.0] - 2026-05-16

⬆️ 依赖升级 + 警告清理 — Riverpod 3.x迁移 + 大版本API适配 + Dart 3.11废弃API修复

基于Flutter SDK 3.41.10-ohos升级，完成核心依赖大版本升级、69个文件Riverpod 3.x迁移、大版本API破坏性变更适配、Dart 3.11废弃API批量修复，flutter analyze 零Error

核心依赖升级

依赖	旧版本	新版本	破坏性变更
`flutter_riverpod`	^2.x	^3.0.0	StateNotifier移除→Notifier
`riverpod_annotation`	^2.x	^4.0.0	注解API调整
`riverpod_generator`	^2.x	^4.0.0	代码生成适配
`riverpod_lint`	^2.x	^3.0.0	规则更新
`go_router`	^14.x	^17.0.0	类型安全路由
`freezed`	^2.x	^3.0.0	Union类型简化
`freezed_annotation`	^2.x	^3.0.0	注解适配
`fl_chart`	^0.69	^1.2.0	SideTitleWidget/tooltipRoundedRadius API变更
`file_picker`	^8.x	^11.0.0	FilePicker.platform移除→静态方法
`flutter_local_notifications`	^17.x	^21.0.0	命名参数+uiLocalNotificationDateInterpretation移除
`local_auth`	^2.x	^3.0.0	authenticate()参数变更
`share_plus`	^10.x	^13.0.0	Share.shareXFiles→SharePlus.instance.share
`archive`	^3.x	^4.0.0	encode/decode返回List
`shelf_web_socket`	^2.x	^3.0.0	WebSocketAdapter API变更
`tilt`	^3.x	^4.0.0	Tilt→Tilt.base
29个安全小版本	各版本	最新兼容版	无破坏性变更

大版本API破坏性变更适配

库	变更	修复方式	影响文件
fl_chart 1.2	`SideTitleWidget(axisSide:)`移除	→`SideTitleWidget(meta:)`	learning_progress_page, statistics相关6文件
fl_chart 1.2	`tooltipRoundedRadius: int`移除	→`tooltipBorderRadius: BorderRadius.circular()`	statistics相关6文件
file_picker 11	`FilePicker.platform`移除	→`FilePicker.pickFiles()`静态方法	chat_attachment, data_management, transfer_chat等
flutter_local_notifications 21	位置参数→命名参数	全部改为命名参数传递	local_notification_service, notification_service
flutter_local_notifications 21	`uiLocalNotificationDateInterpretation`移除	移除该参数	local_notification_service
share_plus 13	`Share.shareXFiles()`移除	→`SharePlus.instance.share(ShareParams(files:))`	data_management_page
local_auth 3	`authenticate()`参数变更	适配新API签名	my_devices_page, app_lock_service
archive 4	`encode()`返回`List<int>`	适配类型变更	xycard_service
shelf_web_socket 3	WebSocketAdapter API变更	适配新签名	web_transfer_handler
tilt 4	`Tilt`→`Tilt.base`	组件名变更	chat_bubble

Riverpod 3.x 迁移（69个文件）

StateNotifier → Notifier: 所有StateNotifier<XState>迁移为Notifier<XState>
StateNotifierProvider → NotifierProvider: StateNotifierProvider<X, S>((ref) => X()) → NotifierProvider<X, S>(X.new)
构造函数参数移除: Notifier不再接受构造参数，原参数改为通过ref.read()获取
build()方法: 原构造函数初始化逻辑迁移至build()方法，返回初始状态
ref引用: Notifier内置ref属性，无需构造参数传递
mounted状态: Notifier无内置mounted，添加bool _mounted标志位管理
onDispose: 使用ref.onDispose()注册清理回调
family provider调用: chatAttachmentProvider需传参chatAttachmentProvider(conversationId)

关键迁移文件:

weather_provider.dart — 标准Notifier迁移模板
transfer_notifier.dart — 复杂Notifier（构造参数→ref.read、mounted管理、onDispose）
home_feed_mixin.dart — mixin约束从on StateNotifier改为on Notifier
home_interaction_mixin.dart — 交互mixin适配Notifier约束
chat_flow_input_bar.dart — family provider传参修复
chat_flow_page.dart — family provider传参修复

Dart 3.11 废弃API修复

废弃API	替代方案	影响文件数
`RegExp(source)`	`regex(source)` 封装函数	20+
`FontWeight.index`	`FontWeight.value` 计算	1
`TextAlignMode.index`	`TextAlignMode.name` 序列化	1
`AdaptivePalette.fromImage()`	`FluidPaletteExtractor.extractColors()`	1
`BuildContext`跨异步间隙	`context.mounted` 检查	5+
`encryptedSharedPreferences`	移除该参数	1

新增工具文件:

lib/core/utils/pattern_utils.dart — regex()和regexEscape()封装，消除RegExp废弃警告

新增占位文件（开发中功能）

文件	作用
`lib/editor/services/core/spritesheet_service.dart`	精灵图贴纸加载/解析/预览
`lib/editor/services/image/image_import_service.dart`	图片导入/预处理
`lib/core/services/data/settings_export_service.dart`	设置导出/导入
`lib/features/settings/presentation/font_management_page.dart`	字体管理页面+Provider

flutter analyze 结果

24 issues found (零Error，仅Warning/Info级别)
- prefer_final_fields: 3个
- unnecessary_null_comparison: 2个
- dead_code: 2个
- unnecessary_non_null_assertion: 1个
- avoid_redundant_argument_values: 1个
- avoid_dynamic_calls: 5个
- inference_failure: 2个
- 其他info: 8个

[5.10.0] - 2026-05-16

⬆️ SDK升级 — Flutter OpenHarmony oh-3.41.9-dev

升级内容

Flutter SDK: 3.35.8-ohos-0.0.3 → 3.41.10-ohos-0.0.1-canary1
Dart SDK: 3.9.2 → 3.11.5
DevTools: 2.48.0 → 2.54.1
SDK分支: oh-3.35.7-dev → oh-3.41.9-dev
SDK来源: https://gitcode.com/openharmony-tpc/flutter_flutter (oh-3.41.9-dev)

修改文件

文件	修改内容
`pubspec.yaml`	SDK约束从 `^3.9.2` 更新为 `^3.11.5`
Flutter SDK (`E:\sdk\flutter-ohos\flutter_flutter`)	切换分支至 `oh-3.41.9-dev`

注意事项

旧分支 oh-3.35.7-dev 的本地修改已 stash 保存，可通过 git stash list 查看
flutter pub get 已验证通过，所有依赖兼容新 SDK
114 个依赖包有更新版本可用，后续可按需升级

[5.9.0] - 2026-05-15

🐛 Bug修复 — 6项关键问题

修复清单

系统分享白屏 — sharing_receiver_service.dart
- 根因: _navigateToReadlater() 使用 Navigator.pushNamed('/readlater-chat') 导航，但App使用GoRouter管理路由
- 修复: 改用 GoRouter.of(ctx).go(AppRoutes.readlaterChat) 导航
- 影响: 从其他App分享内容到闲言时不再白屏
画布ref disposed报错 — canvas_page.dart
- 根因: dispose() 中调用 ref.read(canvasProvider.notifier) 访问已销毁的widget
- 修复: 在 initState 中缓存 CanvasNotifier 引用到 _cachedNotifier，dispose 中使用缓存引用
- 影响: 退出画布页面不再抛出 StateError: Cannot use "ref" after the widget was disposed
画布画线无法同步 — canvas_sync_service.dart + canvas_provider.dart
- 根因: 收到 canvasSnapshot request 时只打日志，不回复snapshot response
- 修复: 新增 SnapshotRequestCallback，收到request时通过 sendSnapshotResponse 回复当前画布笔迹
- 影响: 后加入画布的用户可以看到先加入者已画的笔迹
屏幕共享不可用 — transfer_chat_page.dart
- 根因: _startScreenShare() 手动构造 SignalingMessage 发送，未使用 screenShareProvider.startSharing()
- 修复: 改用 screenShareProvider.notifier.startSharing() 正确发起共享，并导航到 ScreenSharePage
- 影响: 发起屏幕共享后对方可收到请求并显示接受按钮
稍后读消息未显示 — home_interaction_mixin.dart + chat_provider.dart + chat_flow_page.dart
- 根因: toggleReadLater 写入DB后未通知 ChatNotifier 刷新消息列表
- 修复: 新增 notifyReadlaterRefresh() 全局事件总线，ChatFlowPage 在稍后读模式下监听刷新事件
- 影响: 主页点击"稍后读"后，稍后读会话流页面实时显示新消息气泡
稍后读显示无关消息 — chat_provider.dart
- 根因: _addInitialSentencesIfNeeded() 对所有会话（包括readlater）都添加初始句子如"山有木兮木有枝"
- 修复: 在方法开头增加 if (conversationId == 'readlater') return; 跳过
- 影响: 稍后读会话流不再显示无关的初始句子
输入法自动弹出 — keyboard_safe_sheet.dart + chat_flow_page.dart + chat_flow_input_bar.dart
- 根因: 缺乏全局键盘管理，页面切换/返回/按钮点击时FocusNode意外获焦
- 修复: 新增 KeyboardManager 全局键盘管理器，跟踪用户是否主动点击输入框
- 强化: 点击空白区域/输入法上方区域自动收起键盘
- 强化: 页面切换时自动收起键盘并清除焦点
- 强化: App进入后台时自动收起键盘
- 影响: 输入法不再意外弹出，只有用户主动点击输入框才弹出

修改文件

文件	修改内容
`sharing_receiver_service.dart`	GoRouter导航替代Navigator.pushNamed
`canvas_page.dart`	缓存notifier引用，避免dispose中访问ref
`canvas_sync_service.dart`	新增SnapshotRequestCallback，响应snapshot请求
`canvas_provider.dart`	绑定onSnapshotRequest回调，发送snapshot响应
`transfer_chat_page.dart`	使用screenShareProvider.startSharing()发起共享
`home_interaction_mixin.dart`	toggleReadLater后触发notifyReadlaterRefresh
`chat_provider.dart`	新增readlater刷新事件总线 + _addInitialSentencesIfNeeded跳过readlater
`chat_flow_page.dart`	监听readlater刷新 + KeyboardManager集成 + 焦点管理
`chat_flow_input_bar.dart`	输入框onTap标记KeyboardManager用户点击
`keyboard_safe_sheet.dart`	新增KeyboardManager全局键盘管理器 + ManagedCupertinoTextField

[6.1.0] - 2026-05-14

🔌 新功能 — USB OTG有线传输 (F7-01~06)

内容: USB OTG Host模式文件传输，两台Android设备通过USB线缆高速传输文件

UsbDevice 模型 — lib/features/file_transfer/services/transport/usb_transport_service.dart
- UsbDevice: deviceId/vendorId/productId/deviceName/usbVersion/isConnected
- isXianyanDevice: 通过VendorID自动识别闲言APP认证设备
- toMap/fromMap序列化
UsbTransportService 重构 — lib/features/file_transfer/services/transport/usb_transport_service.dart
- MethodChannel xianyan/usb_transport 桥接原生USB操作
- isUsbHostSupported(): 检测USB Host模式支持(Android only)
- detectUsbDevice()/detectAllUsbDevices(): 枚举已连接USB设备
- connectDevice(): 建立USB连接(claim interface/endpoint)
- sendFileWithProgress(): 块传输发送+进度回调
- receiveFileWithProgress(): 块传输接收+进度回调
- disconnect(): 断开USB连接
- getTransferSpeed(): 按USB版本返回理论最大速度(USB2.0=480Mbps/3.0=5Gbps/3.1=10Gbps)
- Stream: onUsbDeviceAttached/onUsbDeviceDetached/onConnectionChanged
- 块大小适配: USB 2.0→64KB / USB 3.0→256KB / USB 3.1→512KB
UsbDiscoveryService 重构 — lib/features/file_transfer/services/discovery/usb_discovery_service.dart
- EventChannel xianyan/usb_events 监听原生USB插入/拔出事件
- startMonitoring()/stopMonitoring(): USB设备监听生命周期
- getConnectedDevices(): 获取当前已连接USB设备列表
- getXianyanDevices(): 过滤闲言APP认证设备
- Stream: onDeviceFound/onDeviceRemoved/onDevicesChanged
- 自动扫描已连接设备(_scanExistingDevices)
UsbConfirmDialog — lib/features/file_transfer/presentation/widgets/usb_confirm_dialog.dart
- iOS风格CupertinoAlertDialog
- 显示: 设备名称/协议版本/最大速度/认证状态
- [取消] [开始传输] 按钮
- showUsbConfirmDialog() 便捷方法
TransferFileHandler USB集成 — lib/features/file_transfer/providers/transfer_file_handler.dart
- sendFilesUsb(): USB OTG文件发送(连接→传输→进度→完成)
- cancelTask/pauseTask/resumeTask: usbTether case实现(disconnect/handleUsbDisconnected/handleUsbConnected)
TransferNotifier USB集成 — lib/features/file_transfer/providers/transfer_notifier.dart
- UsbDiscoveryService实例+生命周期管理
- startUsbMonitoring()/stopUsbMonitoring(): USB监听控制
- getUsbConnectedDevices: 获取USB设备列表
- sendFilesUsb(): 委托FileHandler USB传输
- _setupUsbDiscoveryListeners(): USB设备发现/移除→discoveredDevices状态更新+系统消息
- dispose中清理USB资源

[11.0.0] - 2026-05-12

🚀 传输扩展功能 — 送达回执 + 断点续传 + 文件分流

已归档版本

12.4.0(Tab栏个性交互) / 12.3.0(搜索三大问题修复) / 12.2.0(收藏双向同步) / 12.1.1(快捷按钮导航) / 12.1.0(USB OTG传输) / 6.4.1(句子卡片空白修复) / 6.3.2(登录加载闪烁修复) / 6.3.1(TextPainter异常修复) / 6.2.0(协作画布) / 6.2.1(剪贴板同步) / 11.2.0(云端暂存) / 11.0.0(送达回执+断点续传) / 5.33.0(智能推荐+标签云+智能模式) / 5.32.0(离线浏览缓存) / 5.31.0(通知设置) / 5.30.0(二维码登录) / 5.29.0(表单校验+本地通知) / 5.28.0(文件传输助手+我的设备) / 5.27.0(用户中心接口同步) / 5.26.0(文件传输核心架构) / 5.22.0(聊天多媒体+视觉增强) / 4.21.0(聊天会话流) / 5.11.0(通用设置重构) / 5.10.0(关于页面+图标统一) / 3.9.9(画布样式编辑) / 3.9.8(拖拽描边/文本回写/壁纸无限加载) / 3.9.7(画布圆角+导出修复) / 3.9.6(画布圆角/文字按钮卡死) / 3.9.5(Bug回归修复) / 3.9.4(本地化/HTTP明文) / 3.9.3(画布圆角/壁纸卡死) / 3.9.2(画布圆角/文字按钮/壁纸) / 3.9.1(历史卡死/同步丢失) / 3.9.0(编辑器增强) / 3.8.0 / 2.58.0(六大Bug修复) / 2.57.0(开发计划) / 2.56.0(README更新) / 2.55.1(代码质量清理) / 1.55.0(灵感页面重构) / 1.54.0(个人中心+签到Bug) / 1.53.0(分类列表+骨架屏) / 1.52.0(句子卡片不更新) / 1.51.0(句子循环重复) / 1.50.0(频道同步延迟) / 1.49.0(刷新无响应+分类同步) / 1.48.0(句子广场无限循环) / 1.47.0(API类型转换崩溃) / 1.46.0(句子来源页面) / 1.45.0(笔记自动保存) / 1.44.2(笔记Bug修复) / 1.44.1(笔记删除Bug) / 1.44.0(API集成补全) / 1.40.0(用户安全接口) / 1.39.0(卡片震动/分类切换) / 1.31.0(API功能全面接入) / 1.30.0(传统色页面重构) / 1.23.0(偷工减料修复) / 1.22.0(句子广场交互) / 1.21.0(数据管理卡死/Tab抖动) — 更早版本详见 git history

61 KiB Raw Blame History Unescape Escape

Changelog

[6.0.0] - 2026-05-18

🐛 修复鸿蒙端白屏问题 — 错误可见性 + ErrorBoundary + OHOS动画守卫

核心修复

OHOS动画守卫（预防性修复）

诊断Demo v3

[5.19.0] - 2026-05-18

♻️ 重构：设置Provider拆分 — 网络设置与隐私设置独立

新增文件

拆分字段对照

设计说明

[5.18.0] - 2026-05-18

🐛 修复系统状态栏颜色与软件主题不一致

问题根因

修复方案

修复文件清单

🐛 修复 Riverpod Notifier 构造函数中使用 ref/state 导致鸿蒙端崩溃

问题根因

修复方案

修复文件清单

[5.17.8] - 2026-05-17

🐛 鸿蒙端白屏修复 — 数据库Migration未执行 + INSERT OR IGNORE兼容性

白屏根因分析

修复方案

修复文件清单

版本管理流程（修复后）

[5.17.7] - 2026-05-17

🐛 鸿蒙端白屏修复 — SQL双引号标识符 + PRAGMA兼容性

白屏根因分析

修复方案

修复文件清单

SQL适配示例

[5.17.6] - 2026-05-17

🐛 鸿蒙端白屏修复 — Drift数据库适配 + 通知初始化修复

白屏根因分析

修复方案

修复文件清单

架构说明

[5.17.5] - 2026-05-17

🐛 鸿蒙端白屏修复 — 全量平台兼容性适配

白屏根因分析

修复文件清单

核心平台检测机制

[5.17.4] - 2026-05-17

🔧 ArkTS编译错误全量修复 — 45→0个ERROR

修复清单

关键API变更说明

[5.17.3] - 2026-05-17

🔒 受限ACL权限优化 — 5→0个受限权限

gal插件改造

剪贴板桥接

代码修复

[5.17.2] - 2026-05-17

🔌 鸿蒙适配 — 全量审计 + 构建修复

全量依赖审计

构建错误修复

宿主应用权限补全

鸿蒙适配计划文档更新

[5.17.1] - 2026-05-17

🔌 鸿蒙适配 — 第三方包审计修复 + NFC迁移TPC

NFC包迁移: nfc_manager → flutter_nfc_kit (TPC官方适配)

空实现方法修复

module.json5 权限和设备类型修复

HAR引用路径统一

app_links 深度链接集成

[5.17.0] - 2026-05-16

🔌 鸿蒙适配 — flutter_webrtc 完整WebRTC音视频通信

新增本地化鸿蒙适配包

TPC社区库合并

flutter_webrtc ohos原生实现功能

ohos/目录结构

Dart端修改

使用的鸿蒙API

已完成鸿蒙适配的包汇总（共31个）

[5.16.0] - 2026-05-16

🔌 鸿蒙适配 — app_links 深度链接 + pro_image_editor 图片编辑

新增本地化鸿蒙适配包

app_links ohos原生实现功能

使用的鸿蒙API

61 KiB

Raw Blame History