重大變更與遷移指南

如重大變更政策所述， 我們會在必要時發布指南， 協助您將程式碼遷移以因應重大變更。

若想即時獲知未來的重大變更， 請加入 Flutter announce 與 Dart announce 群組。

若您在升級 Flutter 後遇到 Dart 錯誤， 可考慮使用 dart fix 指令 自動遷移您的程式碼。 並非所有重大變更都支援此方式， 但許多變更已可自動處理。

為避免未來 Flutter 版本造成破壞性影響， 建議您將測試提交至框架的 test registry。

下列指南可供參考。 依照版本排序，並以字母順序列出：

• 為 DropdownButton 新增 enabled 屬性並讓 onChanged 成為選填
• 在 Android 17 上忽略大螢幕方向與可調整大小限制
• 更新 iOS 與 Android 上的 semantics 標題與 headingLevel 行為

• 變更 RawMenuAnchor 的關閉順序
• 棄用 onReorder 回呼（callback）
• 棄用 TextInputConnection.setStyle
• 棄用 cacheExtent 與 cacheExtentStyle
• IconData 類別標記為 final
• ListTile 在除錯模式下被有顏色的元件包裹時會回報錯誤
• 將 Flutter Android 專案遷移至內建 Kotlin
• 頁面轉場建構器重組

• Linux 合併執行緒
• FontWeight 也能控制可變字型的 weight 屬性
• 棄用 containsSemantics，改用 isSemantics
• 棄用 ListView 與 SliverList 分離建構子中的 findChildIndexCallback，改用 findItemIndexCallback
• Material 3 token 更新

• CupertinoDynamicColor 廣色域支援
• 棄用 OverlayPortal.targetsRootOverlay
• 棄用 SemanticsProperties.focusable 與 SemanticsConfiguration.isFocusable
• 含 action 的 SnackBar 不再自動消失
• Android 預設頁面轉場現已改為 PredictiveBackPageTransitionBuilder
• 採用 UISceneDelegate

• 元件主題正規化更新
• 棄用 DropdownButtonFormField 的 value 參數，改用 initialValue
• 棄用 app bar 顏色
• 重新設計 Radio 元件 (Widget)
• 移除 semantics elevation 與 thickness
• Form 元件不再支援 sliver
• Flutter 現於 Android 建置時設置預設 abiFilters
• macOS 與 Windows 合併執行緒
• 啟用 maintainState 時，Visibility 元件預設不再可聚焦
• $FLUTTER_ROOT/version 被 $FLUTTER_ROOT/bin/cache/flutter.version.json 取代

• 棄用 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
• 欠阻尼彈簧公式變更

• 移除 v1 Android embedding Java API
• 棄用 WebGoldenComparator
• 棄用 ThemeData.dialogBackgroundColor，改用 DialogThemeData.backgroundColor
• ImageFilter.blur 預設平鋪模式自動選擇
• Material 3 Slider 更新
• Material 3 進度指示器更新

• Color 廣色域支援
• 元件主題正規化
• 深層連結旗標變更
• Flutter 中 Material 3 Tokens 更新
• 移除 InputDecoration.collapsed 的無效參數
• SystemUiMode 預設設為 Edge-to-Edge

• Navigator 的 page API 重大變更
• PopScope 泛型型別
• 棄用 ButtonBar，改用 OverflowBar
• Android 插件渲染至 Surface 的新 API

• v3.19 後移除的棄用 API
• 將 MaterialState 重新命名為 WidgetState
• 新增 ColorScheme 角色
• 停止支援 Android KitKat
• PageView.controller 可為 null
• 將 MemoryAllocations 重新命名為 FlutterMemoryAllocations

• v3.16 後移除的棄用 API
• RawKeyEvent/RawKeyboard 系統遷移至 KeyEvent/HardwareKeyboard 系統
• 棄用 Flutter Gradle 插件的命令式 apply
• 預設多點觸控滾動
• tooltip 的無障礙遍歷順序變更
• 停止產生 AssetManifest.json

• 遷移至 Material 3
• ShortcutActivator 與 ShortcutManager 遷移至 KeyEvent 系統
• ThemeData.useMaterial3 屬性預設為 true
• v3.13 後移除的棄用 API
• 使用新 TabBar.tabAlignment 屬性自訂分頁對齊
• 棄用 textScaleFactor，改用 TextScaler
• 啟用 Android 14 非線性字體縮放
• 棄用 describeEnum 並將 EnumProperty 更新為型別嚴格
• Android Predictive Back 棄用即時導航 pop API
• 棄用 Paint.enableDithering
• 選單預設文字樣式更新
• Windows：外部視窗應通知 Flutter 引擎生命週期變化
• Windows 建置路徑新增目標架構

• 為部分可釋放物件新增缺漏的 dispose()
• v3.10 後移除的棄用 API
• 新增 AppLifecycleState.hidden 列舉值
• 將 ReorderableListView 的在地化字串從 material 移至 widgets localizations
• 移除 ignoringSemantics 屬性
• 棄用 RouteInformation.location 及其相關 API
• EditableText 捲動至可見行為更新
• Windows 專案遷移以確保視窗顯示
• Checkbox.fillColor 行為更新

• Flutter v3.10 及後續版本的 Dart 3 變更
• v3.7 後移除的棄用 API
• 插入內容文字輸入 client
• 棄用 window singleton
• 解決 Android Java Gradle 錯誤
• ClipboardData 建構子需至少一個資料變體
• "Zone mismatch" 訊息

• v3.3 後移除的棄用 API
• 以通用元件建構器取代自訂內容選單參數
• iOS FlutterViewController 的 splashScreenView 改為可為 null
• 將 of 遷移為非 null 回傳值，並新增 maybeOf
• 移除 RouteSettings.copyWith
• ThemeData 的 toggleableActiveColor 屬性已棄用
• Windows 專案遷移以支援深色標題列

• 新增 ImageProvider.loadBuffer
• 桌面版預設 PrimaryScrollController
• 觸控板手勢可觸發 GestureRecognizer
• Windows 專案遷移以設定版本資訊

• v2.10 後移除的棄用 API
• 將 Chips 的 useDeleteButtonTooltip 遷移至 deleteButtonTooltipMessage
• 頁面轉場由 ZoomPageTransitionsBuilder 取代

• v2.5 後移除的棄用 API
• 網頁上的原始圖片使用正確的原點與顏色
• 必要的 Kotlin 版本
• Scribble 文字輸入 client

• 預設拖曳捲動裝置
• v2.2 後移除的棄用 API
• 變更 enterText 方法以將游標移至輸入文字末端
• GestureRecognizer 清理
• 引入 package:flutter_lints
• 以 collate 取代 AnimationSheetBuilder.display
• ThemeData 的 accent 屬性已棄用
• 平台頻道測試介面轉移至 flutter_test 套件
• 使用 HTML slots 在網頁上渲染平台視圖
• Windows 專案遷移至慣用執行迴圈

以下重大變更已在 2.2 版本中還原：

iOS 與 Android 的網路政策

引入版本：2.0.0
還原版本：2.2.0

• 桌面版預設捲動條

• 為 TextEditingController.buildTextSpan 新增 BuildContext 參數
• Android ActivityControlSurface attachToActivity 簽章變更
• 移除 Android FlutterMain.setIsRunningInRobolectricTest 測試 API
• 裁剪行為
• v1.22 後移除的棄用 API
• RenderBox 的乾式版面配置支援
• 消除 nullOk 參數
• Material Chip 按鈕語意
• ScaffoldMessenger 管理的 SnackBar
• TextSelectionTheme 遷移
• 平台頻道測試介面轉移至 flutter_test 套件
• 使用 maxLengthEnforcement 取代 maxLengthEnforced

• Android v1 embedding 應用程式與插件建立已棄用
• Cupertino icons 1.0.0
• 新的 Form、FormField 自動驗證 API

• Actions API 修訂
• 新增 TextInputClient.currentAutofillScope 屬性
• 新按鈕與按鈕主題
• 對話框的預設 BorderRadius
• Navigator 與 Hero Controller Scope 中更嚴格的斷言
• Route Transition 記錄與 Transition delegate 更新
• RenderEditable 需在點擊測試前完成版面配置
• 反轉 scheduler 與 services 層之間的相依性
• Modal Routes 中 Overlay Entries 的語意順序
• 為 TextInputClient 新增 showAutocorrectionPromptRect 方法
• TestWidgetsFlutterBinding.clock
• TextField 需要 MaterialLocalizations

• 在 TargetPlatform 列舉中新增 'linux' 與 'windows'
• Annotations 回傳相對於物件的本地座標
• Container 顏色最佳化
• CupertinoTabBar 需要 Localizations 父級
• ParentDataWidget 的泛型型別改為 ParentData
• ImageCache 與 ImageProvider 變更
• ImageCache 大型圖片
• MouseTracker 移至 rendering
• MouseTracker 不再附加 annotations
• Nullable CupertinoTheme.brightness
• OverlayEntries 與 Routes 的重建最佳化
• 可捲動的 AlertDialog
• TestTextInput 狀態重設
• TextInputClient currentTextEditingValue
• forgetChild() 方法必須呼叫 super
• Route 與 Navigator 重構
• FloatingActionButton 與 ThemeData 的 accent 屬性