• 跨平台
• 移动开发
• 前端
• UI组件
• OpenHarmony
• 图形学

本文以 Flutter3.7_to_3.22_Breaking-changes.en.md 为核心骨架，系统梳理 Flutter 从 3.7 升级到 3.22 过程中引入的 40 项破坏性变更（Breaking Changes）。作为 OpenHarmony 适配版 Flutter SDK 仓库（CPF-Flutter/flutter_flutter，当前基线为 Flutter 3.35.7），本仓库已完整落地了这批变更；本文在继承原文档全部变更清单的基础上，结合仓库源码（packages/flutter/lib/src下各模块）给出可验证的实现证据与适配要点，帮助开发者完成存量项目的平滑迁移。

一、升级背景：为什么 3.7 → 3.22 是一次"需要认真对待"的大版本跨越

原文档明确指出：从 Flutter 3.7 到 3.22，版本更新带来了大量改进——性能优化、新特性、安全性与稳定性增强、开发工具改进，以及生态扩展。与此同时，一批 API 行为发生了破坏性变化，开发者需要逐一评估并完成适配。

这批变更并非全部都需要动手改造。原文档用"是否要求适配（Is Adaptation Required?）"字段对每项变更做了标注：

• Yes（需要适配）：API 删除、行为变更、类型收紧，存量代码编译会失败或运行行为会改变，必须修改；
• No（无需适配）：平台侧行为、构建路径、新能力增强，通常不影响现有 Dart 代码，但需要了解以便排查问题。

40 项变更分布在 3.10.0、3.13.0、3.16、3.19、3.22 五个里程碑版本中，贯穿了 Dart 3 迁移、Material 3 默认化、键盘输入系统重构、生命周期细化、内存诊断基础设施等多个主线。

二、40 项破坏性变更完整清单

下表完整继承原文档的全部 40 项变更（"Change Guidance"列中的外部文档链接因不可引用外部地址，替换为本文后续章节的适配指引索引）：

三、需要适配的变更：逐项深入解读与源码证据

3.1 Dart 3 迁移（变更 1，Flutter 3.10 起）

Flutter v3.10 起强制跟随 Dart 3 语言版本。Dart 3 引入了 sound null safety 的最终形态、records、patterns、class modifiers等新语法，同时移除了对非 null-safe 代码的运行时支持。存量项目需要：

• 将pubspec.yaml中的environment.sdk提升到>=3.0.0；
• 确认全部依赖已迁移到 null-safe；
• 使用dart fix与dart analyze完成自动化修复与残留问题排查。

仓库内packages/flutter/pubspec.yaml、packages/flutter_tools/pubspec.yaml等全部子项目均已运行在 Dart 3 之上，可作为升级后的语法基线参考。

3.2 多轮"已弃用 API 移除"（变更 2/9/20/30/35）

原文档以五个里程碑为节点（v3.7→3.10、v3.10→3.13、v3.13→3.16、v3.16→3.19、v3.19→3.22），每个版本都会清理上一轮标记弃用的 API。适配要点：

• 升级前先运行flutter analyze与dart fix --apply，优先处理deprecated_member_use告警；
• 在代码中避免直接使用以Deprecated注解标记的成员，关注 IDE 中的删除线提示；
• 升级后若出现"undefined"类编译错误，优先检查是否调用了被本轮移除的旧 API。

仓库中大量源码本身就是"弃用 → 移除 → 迁移"的活样本。例如 material_state.dart 中通过typedef兼容层保留旧名称，而describeEnum（变更 24）在 3.16 被弃用后，仓库内的调试诊断代码已全面改用更类型安全的方式枚举对象状态。

3.3 弃用 window 单例（变更 4，3.10）

早期版本通过全局window单例访问屏幕尺寸、设备像素比等信息。3.10 起该单例被弃用，改为通过WidgetsBinding.instance下的PlatformDispatcher与View体系获取：

// 旧写法（已不可用） // window.physicalSize; // window.devicePixelRatio; // 新写法 final Size size = View.of(context).physicalSize; final double dpr = View.of(context).devicePixelRatio;

多窗口与多显示器场景下，window单例无法表达"当前视图"的概念，因此被按视图（View）划分的 API 取代。仓库packages/flutter/lib/src/widgets/binding.dart中的WidgetsBinding已完全基于View体系工作，可作为迁移后的参考实现。

3.4 弃用 API 移除的配套项：describeEnum 与 EnumProperty 强类型化（变更 24）

describeEnum依赖字符串拼接来描述枚举值，3.16 将其弃用并让EnumProperty强类型化。诊断输出现在直接使用Enum类型的toString()，避免了硬编码名称与实际枚举项不一致的问题。涉及调试与序列化的自定义代码需要同步调整。

3.5 ClipboardData 构造函数收紧（变更 6，3.10）

ClipboardData构造函数改为要求至少提供一个数据变体。仓库源码 clipboard.dart 中可见其签名：

@immutable class ClipboardData { /// Creates data for the system clipboard. const ClipboardData({required String this.text}); /// Plain text variant of this clipboard data. // This is nullable as other clipboard data variants, like images, may be // added in the future. Currently, plain text is the only supported variant // and this is guaranteed to be non-null. final String? text; }

注意text字段类型仍为String?（为未来图片等变体预留），但构造函数参数已用required标注。存量代码中ClipboardData()（空参调用）将直接编译失败，需要改为ClipboardData(text: '...')。

3.6 "Zone mismatch" 报错信息（变更 7，3.10）

当异步操作跨越不同的Zone时（例如在测试环境中使用fakeAsync却在真实异步 Zone 中等待，或自定义runZoned包裹 Flutter 引擎启动），3.10 起会抛出更明确的 "Zone mismatch" 错误。这是运行期错误而非编译期错误，适配要点：

• 确保runApp与所有异步测试在同一 Zone 内完成；
• 使用package:fake_async时，避免在FakeAsync.run之外等待其内部产生的 Future；
• 自定义 Zone 包裹引擎初始化时，保持WidgetsFlutterBinding.ensureInitialized()与runApp位于同一 Zone。

3.7 为可释放对象补充 dispose()（变更 8，3.13）

3.13 为一批原本缺少释放方法的可销毁对象（如TextPainter、ImageStreamCompleter相关资源、ScrollController持有的监听器等）补上了dispose()，并强化了资源生命周期管理。适配要点：

• 在State.dispose()中释放由initState创建的 controller、stream subscription、text painter 等；
• 关注"must be disposed"类分析告警（flutter analyze中的leak_related规则）；
• 未调用dispose的对象在 debug 模式会输出内存泄漏诊断信息。

仓库配套测试（如packages/flutter/test下的资源生命周期测试）验证了未释放对象在 debug 断言下的行为，可作为自测参照。

3.8 新增 AppLifecycleState.hidden（变更 10，3.13）

应用生命周期枚举新增hidden状态，位于inactive与paused之间：当应用不再可见（例如被完全遮挡）但尚未暂停时进入hidden。仓库 binding.dart 的handleAppLifecycleStateChanged中完整枚举了各状态分支：

void handleAppLifecycleStateChanged(AppLifecycleState state) { switch (state) { case AppLifecycleState.resumed: case AppLifecycleState.inactive: case AppLifecycleState.hidden: case AppLifecycleState.paused: case AppLifecycleState.detached: ... } }

适配要点：实现WidgetsBindingObserver.didChangeAppLifecycleState时，对AppLifecycleState.hidden需要显式处理（或在switch中将其纳入与paused相同的分支），否则会出现非穷尽 switch 的编译告警。

3.9 ReorderableListView 本地化字符串迁移（变更 11，3.13）

ReorderableListView的语义标签（如"上移/下移/移到开头/移到末尾"）本地化字符串从 material 的本地化表迁移到了 widgets 层的WidgetsLocalizations。仓库 reorderable_list.dart 中的实现已确认使用：

final WidgetsLocalizations localizations = WidgetsLocalizations.of(context);

适配要点：若你之前通过MaterialLocalizations覆盖了这些字符串，需要改到 widgets 层；使用自定义WidgetsLocalizationsDelegate时需同步补充这些新键值，以保证无障碍语义标签的正确显示。

3.10 语义与无障碍相关：ignoringSemantics 与 Tooltip 遍历顺序（变更 12/34）

• 变更 12（3.13）：IgnorePointer及相关类（IgnorePointer、AbsorbPointer）的ignoringSemantics语义被重新梳理，明确了"忽略指针"与"忽略语义"两种能力的解耦关系。迁移时注意：当ignoringSemantics为 true 时，子树的无障碍信息将被隐藏；需按新语义重新核对自定义组件的可访问性。
• 变更 34（3.19）：Tooltip在无障碍树中的遍历顺序发生变化，tooltip 文本的语义节点位置被调整，以避免在焦点遍历时"插队"。依赖 tooltip 进行屏幕阅读器导航的应用需重新验证朗读顺序。

3.11 RouteInformation.location 迁移（变更 13，3.13）

RouteInformation.location的类型由String演进为基于Uri的规范化处理。仓库 router.dart 中RouteInformation的locationgetter 已经基于 URI 语义工作：

String get location { ... }

适配要点：自定义RouteInformationParser在解析 location 时应按 URI 规则处理（百分号编码、query 参数等），避免手写字符串拼接导致的路由还原不一致。仓库packages/flutter/lib/src/widgets/router.dart的实现与packages/flutter/test/widgets/router_test.dart是标准参考。

3.12 EditableText 滚动到可见区域行为更新（变更 14，3.13）

EditableText在输入时光标滚入可见区域的策略被更新：当文本方向、光标位置或视口边界条件变化时，滚动行为更贴近原生输入框体验。适配要点：依赖旧版"光标永远居中/永远贴边"行为的自定义输入控件，需要基于新的ScrollPosition行为重新校准；涉及TextField、TextFormField的存量 UI 建议做一次回归测试。

3.13 Checkbox.fillColor 行为更新（变更 16，3.13）

Checkbox.fillColor的解析逻辑更新：WidgetStateProperty.resolve现在按一组明确的WidgetState集合解析填充色（选中、悬停、按下、禁用等）。仓库 checkbox.dart 文档中给出了标准用法：

Checkbox( fillColor: MaterialStateProperty.resolveWith<Color>((Set<WidgetState> states) { // 根据 states 集合返回不同颜色 ... }), )

适配要点：之前依赖fillColor单一颜色或MaterialStateColor旧解析顺序的代码，需核对各状态下返回值的优先级（如selected优先于hovered）。

3.14 Material 3 默认化与主题迁移（变更 17/19/27）

这是本批变更中影响面最大的一组：

• 变更 17（3.16）：官方推荐全面迁移到 Material 3 设计语言，包括新的组件形态、颜色系统与排版规范；
• 变更 19（3.16）：ThemeData.useMaterial3默认值改为true。仓库 theme_data.dart 中可见：

useMaterial3 ??= true;

这意味着未显式设置useMaterial3: false的应用，升级后将自动切换为 M3 视觉风格（组件圆角、颜色映射、字重体系均会变化）。

• 变更 27（3.16）：菜单（MenuAnchor、PopupMenu）的默认文本样式更新，改由统一的菜单样式体系（MenuStyle.textStyle、MenuThemeData）控制，见 menu_anchor.dart。

适配路径：若希望保持旧版 M2 外观，需显式设置ThemeData(useMaterial3: false)；若接受 M3，则重点回归检查颜色、圆角、Typography（textTheme映射变化，见 M3 typography 迁移说明）与菜单样式。仓库内packages/flutter/lib/src/material/下各组件已完整实现 M3/M2 双模式切换，可直接对照源码排查差异。

3.15 键盘输入系统重构：KeyEvent/HardwareKeyboard（变更 18/31）

• 变更 18（3.16）：ShortcutActivator与ShortcutManager迁移到新的KeyEvent系统；
• 变更 31（3.19）：RawKeyEvent/RawKeyboard全面迁移到KeyEvent/HardwareKeyboard。

旧系统基于原始键码（raw key data），新系统基于逻辑按键（LogicalKeyboardKey）与物理按键（PhysicalKeyboardKey）的KeyEvent模型。仓库packages/flutter/lib/src/services/hardware_keyboard.dart中的HardwareKeyboard、KeyEventManager即为新系统的核心实现。

适配要点：

// 旧写法（已移除） // RawKeyboard.instance.addListener(...); // 新写法 HardwareKeyboard.instance.addHandler((KeyEvent event) { if (event is KeyDownEvent && event.logicalKey == LogicalKeyboardKey.keyA) { // 处理按键 return true; // 已消费 } return false; });

涉及Shortcuts、Actions、Focus的代码同样需要切换到新事件流。KeyEvent的character、logicalKey、physicalKey字段与KeyEventResult消费模型是排查自定义快捷键逻辑的关键。

3.16 弃用 textScaleFactor，改用 TextScaler（变更 22，3.16）

TextStyle.textScaleFactor与MediaQuery.textScaleFactor被弃用，统一由TextScaler取代。仓库 text_scaler.dart 中：

abstract class TextScaler { /// Creates a text scaler that scales the font size by multiplying it with /// the given `textScaleFactor`. const factory TextScaler.linear(double textScaleFactor) = _LinearTextScaler; /// This is equivalent to `TextScaler.linear(1.0)`, the [TextScaler.scale] /// of which returns its input unchanged. static const TextScaler noScaling = _LinearTextScaler(1.0); ... }

适配要点：

// 旧写法（已弃用） // Text('hello', textScaleFactor: 1.5); // MediaQuery.of(context).textScaleFactor; // 新写法 Text('hello', textScaler: TextScaler.linear(1.5)); MediaQuery.of(context).textScaler;

TextScaler为后续非线性字体缩放（如 Android 14 的 nonlinear scaling，见变更 23）预留了扩展点——_LinearTextScaler之外未来可接入非线性实现。仓库中TextPainter、RenderParagraph、EditableText等全部文本链路已基于TextScaler工作。

3.17 默认多指滚动（变更 33，3.19）

3.19 起多指触摸滚动（multitouch scrolling）默认启用：多个手指同时触摸时，Scrollable会聚合所有指针的运动来计算滚动偏移，而不是仅跟踪第一个指针。适配要点：自定义手势识别器或依赖单指拖拽假设的代码，需在GestureDetector层面对多指事件做好冲突处理；官方默认开启后，个别手势冲突场景可能需要显式声明supportedDevices或调整gestureSettings。仓库packages/flutter/lib/src/gestures/下的多点触摸聚合逻辑是排查相关行为的基础。

3.18 MaterialState 重命名为 WidgetState（变更 36，3.22）

这是 3.22 中影响最广的重命名类变更：MaterialState、MaterialStateProperty、MaterialStateColor、MaterialStateMouseCursor、MaterialStateBorderSide、MaterialStateOutlinedBorder、MaterialStateTextStyle、MaterialStatesController全部重命名为对应的WidgetState系列，从"Material 专属"升级为"widgets 层通用"的状态机制。

仓库 widget_state.dart 是新的核心定义文件，WidgetState枚举包含 8 种交互状态：

enum WidgetState implements WidgetStatesConstraint { hovered, // 鼠标悬停 focused, // 键盘/焦点导航 pressed, // 按下 dragged, // 拖拽中 selected, // 已选中（chip、checkbox、tab 等） scrolledUnder,// AppBar 等被滚动内容遮挡 disabled, // 禁用 error; // 错误/非法状态 }

同时提供了类型安全的组合约束与解析机制：

// 状态约束组合：与 / 或 / 非 final WidgetStatesConstraint constraint = WidgetState.focused | WidgetState.hovered; final WidgetStatesConstraint selectedError = WidgetState.selected & WidgetState.error; // 基于 Map 的状态解析（支持 WidgetState.any 兜底） final WidgetStateProperty<Color> color = WidgetStateProperty<Color>.fromMap( <WidgetStatesConstraint, Color>{ selectedError & WidgetState.hovered: Colors.redAccent, selectedError: Colors.red, WidgetState.any: Colors.black, }, ); // 基于回调的解析 WidgetStateColor.resolveWith((Set<WidgetState> states) { if (states.contains(WidgetState.pressed)) { return const Color(0xdeadbeef); } return const Color(0xcafefeed); });

仓库 material_state.dart 保留了完整的兼容层：

typedef MaterialState = WidgetState; typedef MaterialStateColor = WidgetStateColor; typedef MaterialStateProperty<T> = WidgetStateProperty<T>; typedef MaterialStatePropertyAll<T> = WidgetStatePropertyAll<T>; typedef MaterialStatesController = WidgetStatesController;

适配要点：typedef兼容层意味着旧代码在 3.22 仍可编译，但应尽快机械替换（dart fix支持该重命名的自动修复），因为后续版本会移除MaterialState系列名称。Checkbox、Chip、TabBar、InputDecoration等组件的主题字段签名均已更新为WidgetState*类型。

3.19 引入新的 ColorScheme 角色（变更 37，3.22）

M3 颜色系统新增一批ColorScheme角色，仓库 color_scheme.dart 中可见surfaceContainerHighest、outlineVariant、inverseSurface等新字段，并且旧字段（如background、onBackground、surfaceVariant等）带有Deprecated注解与迁移提示（如 "Use surfaceContainerHighest instead."）。

适配要点：以Theme.of(context).colorScheme.xxx读取颜色的代码，需核对所使用的角色是否已被新角色替代；例如colorScheme.surfaceVariant应迁移到colorScheme.surfaceContainerHighest，colorScheme.background/onBackground应迁移到surface/onSurface。新角色的引入是为了细分容器层级（surfaceContainerLowest→surfaceContainerHighest），支撑更细腻的 M3 层级视觉。

3.20 PageView.controller 改为可空（变更 39，3.22）

PageView.controller从必填改为可空。仓库 page_view.dart 中：

/// An object that can be used to control the position to which this page /// view is scrolled. final PageController? controller;

内部实现（page_view.dart#L902）已处理widget.controller == null的情况：不传 controller 时PageView自行创建内部控制器。适配要点：传controller时保持与之前一致（由外部持有并负责 dispose）；不传 controller 时PageView内部管理滚动位置，外部代码不能再直接操作PageControllerAPI。

3.21 MemoryAllocations 重命名为 FlutterMemoryAllocations（变更 40，3.22）

内存分配追踪基础设施重命名。仓库 memory_allocations.dart 中：

const bool _kMemoryAllocations = bool.fromEnvironment('flutter.memory_allocations'); const bool kFlutterMemoryAllocationsEnabled = _kMemoryAllocations || kDebugMode; ... /// 兼容层 typedef MemoryAllocations = FlutterMemoryAllocations;

适配要点：

• 类型名迁移到FlutterMemoryAllocations（旧名保留typedef兼容）；
• 访问实例统一通过FlutterMemoryAllocations.instance；
• 所有使用点需以if (kFlutterMemoryAllocationsEnabled)守卫，仅在启用时才调用dispatchObjectEvent等方法（release 构建默认关闭，可通过--dart-define=flutter.memory_allocations=true开启）；
• 该机制用于监听对象创建与释放事件，是 Flutter 内存泄漏诊断（flutter run下的泄漏报告）的基础设施。

四、无需适配的变更：知晓即可

原文档标注"无需适配"的变更虽然不影响 Dart 代码编译，但理解其背景有助于排查升级后的疑难问题：

• 变更 3（Android 图片键盘）：insertContentTextInputClient相关 API 为 Android 输入法提供图片插入能力，属新增能力；
• 变更 5（Android Java Gradle 迁移）：Android 构建体系向 Kotlin DSL 迁移，涉及原生工程而非 Dart 代码；
• 变更 15/28/29（Windows 相关）：窗口显示时机、外部窗口生命周期通知、构建产物路径加入目标架构（如build/windows/x64/runner/Debug/），影响 Windows 打包与宿主集成代码；
• 变更 21（TabBar.tabAlignment）：新增TabAlignment枚举（startOffset、start、center、fill）用于自定义 Tab 栏水平对齐，属新增配置能力。注意 tabs.dart 中的校验规则：TabAlignment.fill仅对不可滚动 TabBar 有效，否则会抛出FlutterError；
• 变更 23（Android 14 非线性字体缩放）：系统字体缩放策略变化，TextScaler架构即为该能力预留；配合变更 22 的新 API 可获得最佳体验；
• 变更 25（Android Predictive Back）：弃用旧式即时 pop 相关 API，属 Android 平台演进；
• 变更 26（Paint.enableDithering）：Paint的抖动开关弃用，渲染层行为变化；
• 变更 32（Flutter Gradle 插件命令式 apply）：Gradle 插件接入方式演进，影响 Android 工程配置写法；
• 变更 38（放弃 Android KitKat）：最低支持版本提升到 Android 5.0（API 21），影响老设备用户群。

五、迁移优先级建议与自检清单

结合原文档结构与仓库实际情况，建议按以下顺序推进升级：

1. 先做"改名 + 删 API"类机械迁移（优先级最高，编译期失败）：dart fix --apply处理MaterialState→WidgetState（变更 36）、MemoryAllocations→FlutterMemoryAllocations（变更 40）；处理各版本已移除的弃用 API（变更 2/9/20/30/35）；
2. 处理构造函数与类型收紧：ClipboardData必填 text（变更 6）、PageView.controller可空（变更 39）、describeEnum移除（变更 24）；
3. 处理默认行为变化：M3 默认开启（变更 17/19/27）、多指滚动默认开启（变更 33）、Checkbox.fillColor 解析（变更 16）、Tooltip 遍历顺序（变更 34）；
4. 处理新状态与生命周期：AppLifecycleState.hidden的 switch 分支补齐（变更 10）、Zone mismatch 排查（变更 7）、dispose 补齐（变更 8）；
5. 处理输入与路由系统重构：键盘事件迁移到KeyEvent/HardwareKeyboard（变更 18/31）、RouteInformation.locationURI 化（变更 13）、textScaleFactor→TextScaler（变更 22）；
6. 最后做视觉与无障碍回归：M3 视觉差异、ColorScheme新角色（变更 37）、ReorderableListView 本地化（变更 11）、ignoringSemantics（变更 12）。

升级完成后，建议在仓库内packages/flutter/test/与dev/的对应测试用例基础上建立自己的回归用例，重点覆盖：主题色解析、键盘快捷键、输入框滚动、可访问性遍历顺序与内存释放路径。

六、总结

Flutter 3.7 → 3.22 的 40 项破坏性变更，本质上是一次"语言现代化 + 设计系统换代 + 输入/生命周期/诊断基础设施重构"的组合升级。其中约三分之二需要开发者主动适配，且大部分在升级瞬间即可通过编译器暴露（改名、删 API、类型收紧），少部分为运行期行为变化（M3 视觉、多指滚动、Zone 校验、语义顺序）需要回归测试发现。CPF-Flutter/flutter_flutter 仓库作为 Flutter 3.35.7 的 OpenHarmony 适配基线，已将上述全部变更落地于packages/flutter/lib/src各模块，并配套完整的测试覆盖，是开发者对照源码理解每个变更行为与迁移写法的第一手参考。

• 跨平台
• 移动开发
• 前端
• UI组件
• OpenHarmony
• 图形学