重大變更與遷移指南
這是一份關於 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 屬性