重大变更与迁移指南
这是一份关于 Flutter 重大变更的通知和迁移指南合集。
正如重大变更政策中所述,我们有时会发布指南,以帮助您在重大变更后迁移代码。
要接收有关未来重大变更的通知,请加入 Flutter announce 和 Dart announce 小组。
如果在升级 Flutter 后遇到 Dart 错误,请考虑使用 dart fix 命令来自动迁移您的代码。虽然并非所有重大变更都支持此方式,但许多变更都可以通过它自动处理。
为避免受到未来 Flutter 版本的影响,请考虑将您的测试提交到框架的 测试注册表 中。
各版本重大变更
#以下是可用的指南。它们按发布版本分类,并按字母顺序排列。
尚未发布至稳定版
#
在 Flutter 3.44 中发布
#- 更改 RawMenuAnchor 关闭顺序
-
弃用
onReorder回调 -
弃用
TextInputConnection.setStyle -
弃用
cacheExtent和cacheExtentStyle -
IconData类标记为final - ListTile 在被彩色组件包裹时在调试模式下报告错误
- 将 Flutter Android 项目迁移到内置 Kotlin
- 页面过渡构建器重组
在 Flutter 3.41 中发布
#- Linux 上的线程合并
-
FontWeight同时控制可变字体的 weight 属性 -
弃用
containsSemantics,改用isSemantics -
在
ListView和SliverList分离构造函数中弃用findChildIndexCallback,改用findItemIndexCallback - Material 3 代币更新
在 Flutter 3.38 中发布
#-
CupertinoDynamicColor广色域支持 -
弃用
OverlayPortal.targetsRootOverlay -
弃用
SemanticsProperties.focusable和SemanticsConfiguration.isFocusable - 带有操作的 SnackBar 不再自动消失
-
Android 上的默认页面过渡现在是
PredictiveBackPageTransitionBuilder - 采用 UISceneDelegate
在 Flutter 3.35 中发布
#- 组件主题标准化更新
-
弃用
DropdownButtonFormField的value参数,改用initialValue - 弃用应用栏(App Bar)颜色
- 重新设计
Radio组件 - 移除语义层级(elevation)和厚度(thickness)
-
Form组件不再支持作为 Sliver 使用 -
Flutter 现在在 Android 构建中设置默认的
abiFilters - macOS 和 Windows 上的线程合并
-
当启用
maintainState时,Visibility组件默认不再可聚焦 -
$FLUTTER_ROOT/version被$FLUTTER_ROOT/bin/cache/flutter.version.json取代
在 Flutter 3.32 中发布
#-
弃用
SystemContextMenuController.show -
弃用
ExpansionTileController,改用ExpansibleController -
弃用
RouteTransitionRecord.markForRemove,改用RouteTransitionRecord.markForComplete -
弃用
ThemeData.indicatorColor,改用TabBarThemeData.indicatorColor - Material 主题系统更新
-
.flutter-plugins-dependencies取代.flutter-plugins - 本地化消息生成到源代码中,而非合成包中
-
更改
integration_test的默认goldenFileComparator -
弃用
InputDecoration.maintainHintHeight,改用InputDecoration.maintainHintSize - 欠阻尼弹簧公式变更
在 Flutter 3.29 中发布
#- 移除 v1 Android 嵌入 Java API
-
弃用
WebGoldenComparator -
弃用
ThemeData.dialogBackgroundColor,改用DialogThemeData.backgroundColor -
ImageFilter.blur默认 tile mode 自动选择 -
更新 Material 3
Slider - 更新 Material 3 进度指示器
在 Flutter 3.27 中发布
#Color广色域支持- 组件主题标准化
- 深度链接标志变更
- Flutter 中 Material 3 代币更新
-
移除
InputDecoration.collapsed的无效参数 - 将 SystemUiMode 的默认值设置为 Edge-to-Edge
在 Flutter 3.24 中发布
#- Navigator 的页面 API 重大变更
PopScope中的泛型类型-
弃用
ButtonBar,改用OverflowBar -
为渲染到
Surface的 Android 插件提供的新 API
在 Flutter 3.22 中发布
#- v3.19 后移除的已弃用 API
-
将
MaterialState重命名为WidgetState -
引入新的
ColorScheme角色 - 停止支持 Android KitKat
-
可为空的
PageView.controller -
将
MemoryAllocations重命名为FlutterMemoryAllocations
在 Flutter 3.19 中发布
#- v3.16 后移除的已弃用 API
- 将 RawKeyEvent/RawKeyboard 系统迁移至 KeyEvent/HardwareKeyboard 系统
- 弃用 Flutter Gradle 插件的命令式应用方式
- 默认多点触控滚动
- Tooltip 的辅助功能遍历顺序已更改
-
停止生成
AssetManifest.json
在 Flutter 3.16 中发布
#- 迁移至 Material 3
- 将 ShortcutActivator 和 ShortcutManager 迁移至 KeyEvent 系统
-
ThemeData.useMaterial3属性现在默认设置为 true - v3.13 后移除的已弃用 API
-
使用新的
TabBar.tabAlignment属性自定义标签页对齐方式 -
弃用
textScaleFactor,改用TextScaler - 启用 Android 14 非线性字体缩放
-
弃用
describeEnum并将EnumProperty更新为类型严格 - 弃用 Android 预测性返回的即时导航 pop API
-
弃用
Paint.enableDithering - 更新菜单的默认文本样式
- Windows:外部窗口应通知 Flutter 引擎生命周期变更
- Windows 构建路径更改,以添加目标架构
在 Flutter 3.13 中发布
#-
为 Flutter 中的某些可释放对象添加了缺失的
dispose() - v3.10 后移除的已弃用 API
- 添加了 AppLifecycleState.hidden 枚举值
- 将 ReorderableListView 的本地化字符串从 material 迁移到 widgets 本地化
-
移除了
ignoringSemantics属性 -
弃用了
RouteInformation.location及其相关 API - 更新了 EditableText 滚动到视图的行为
- 迁移 Windows 项目以确保窗口显示
-
更新了
Checkbox.fillColor的行为
在 Flutter 3.10 中发布
#- Flutter v3.10 及更高版本中的 Dart 3 变更
- v3.7 后移除的已弃用 API
- 插入内容文本输入客户端
- 弃用窗口单例(window singleton)
- 解决 Android Java Gradle 错误
-
要求
ClipboardData构造函数提供一个数据变体 - “Zone mismatch”消息
在 Flutter 3.7 中发布
#- v3.3 后移除的已弃用 API
- 用通用组件构建器替换了自定义上下文菜单的参数
- iOS FlutterViewController splashScreenView 设为可为空
-
将
of迁移至不可为空的返回值,并添加maybeOf - 移除了 RouteSettings.copyWith
- ThemeData 的 toggleableActiveColor 属性已被弃用
- 迁移 Windows 项目以支持深色标题栏
在 Flutter 3.3 中发布
#- 添加 ImageProvider.loadBuffer
- 桌面端的默认 PrimaryScrollController
- 触控板手势可以触发 GestureRecognizer
- 迁移 Windows 项目以设置版本信息
在 Flutter 3 中发布
#- v2.10 后移除的已弃用 API
- 将 Chips 的 useDeleteButtonTooltip 迁移至 deleteButtonTooltipMessage
- 页面过渡由 ZoomPageTransitionsBuilder 替换
在 Flutter 2.10 中发布
#
在 Flutter 2.5 中发布
#- 默认拖动滚动设备
- v2.2 后移除的已弃用 API
- 将 enterText 方法更改为将插入符号移动到输入文本的末尾
- GestureRecognizer 清理
- 引入 package:flutter_lints
- 用 collate 替换 AnimationSheetBuilder.display
- ThemeData 的 accent 属性已被弃用
- 将平台通道测试接口转换为 flutter_test 包
- 在 Web 上使用 HTML 插槽渲染平台视图
- 将 Windows 项目迁移至符合惯例的运行循环
回退 2.2 中的变更
#以下重大变更在 2.2 版本中被回退
-
iOS 和 Android 上的网络策略
-
引入版本:2.0.0
回退版本:2.2.0
在 Flutter 2.2 中发布
#在 Flutter 2 中发布
#- 为 TextEditingController.buildTextSpan 添加了 BuildContext 参数
- Android ActivityControlSurface attachToActivity 签名变更
- 移除了 Android FlutterMain.setIsRunningInRobolectricTest 测试 API
- 裁剪(Clip)行为
- v1.22 后移除的已弃用 API
- RenderBox 的 Dry layout 支持
- 消除 nullOk 参数
- Material Chip 按钮语义
- 由 ScaffoldMessenger 管理的 SnackBars
- TextSelectionTheme 迁移
- 将平台通道测试接口转换为 flutter_test 包
- 使用 maxLengthEnforcement 代替 maxLengthEnforced
在 Flutter 1.22 中发布
#
在 Flutter 1.20 中发布
#- Actions API 修订
- 添加 TextInputClient.currentAutofillScope 属性
- 新按钮和按钮主题
- 对话框的默认圆角(BorderRadius)
- Navigator 和 Hero Controller 作用域中更严格的断言
- 路由过渡记录和过渡代理更新
- RenderEditable 需要在点击测试前进行布局
- 反转调度程序和服务层之间的依赖关系
- 模态路由中 Overlay 条目的语义顺序
- 向 TextInputClient 添加了 showAutocorrectionPromptRect 方法
- TestWidgetsFlutterBinding.clock
- TextField 需要 MaterialLocalizations
在 Flutter 1.17 中发布
#- 在 TargetPlatform 枚举中添加 'linux' 和 'windows'
- 注解返回相对于对象的局部位置
- Container 颜色优化
- CupertinoTabBar 需要本地化父级
- ParentDataWidget 的泛型类型更改为 ParentData
- ImageCache 和 ImageProvider 变更
- ImageCache 大图
- MouseTracker 移至渲染层
- MouseTracker 不再附加注解
- 可为空的 CupertinoTheme.brightness
- OverlayEntries 和 Routes 的重建优化
- 可滚动的 AlertDialog
- TestTextInput 状态重置
- TextInputClient currentTextEditingValue
- forgetChild() 方法必须调用 super
- Route 和 Navigator 重构
- FloatingActionButton 和 ThemeData 的 accent 属性