重大變更與遷移指南

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

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

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

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

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

• 棄用 OverlayPortal.targetsRootOverlay
• 棄用 TextField.canRequestFocus
• 停止產生 AssetManifest.json
• 採用 UISceneDelegate
• CupertinoDynamicColor 廣色域支援
• $FLUTTER_ROOT/version 被 $FLUTTER_ROOT/bin/cache/flutter.version.json 取代
• SnackBar 含 action 不再自動消失
• 棄用 SemanticsProperties.focusable 與 SemanticsConfiguration.isFocusable

⟦L326⟧

• 元件主題正規化更新
• 棄用 DropdownButtonFormField value 參數，改用 initialValue
• 棄用 app bar 顏色
• 重新設計 Radio 元件
• 移除 semantics elevation 與 thickness
• Form 元件不再支援 sliver
• Flutter 現於 Android 建置時設置預設 abiFilters
• macOS 與 Windows 合併執行緒
• 啟用 Visibility 時，maintainState 元件預設不再可聚焦

⟦L327⟧

• 棄用 SystemContextMenuController.show
• 棄用 ExpansionTileController，改用 ExpansibleController
• 棄用 RouteTransitionRecord.markForRemove，改用 RouteTransitionRecord.markForComplete
• 棄用 ThemeData.indicatorColor，改用 TabBarThemeData.indicatorColor
• Material 主題系統更新
• [.flutter-plugins-dependencies 取代 .flutter-plugins][Adding ImageProvider.loadBuffer]
• [在原始碼中產生在地化訊息，而非合成套件][Default PrimaryScrollController on Desktop]
• [變更 goldenFileComparator 的預設 integration_test]
• [棄用 InputDecoration.maintainHintHeight，改用 InputDecoration.maintainHintSize]
• [欠阻尼彈簧公式變更]

⟦L328⟧

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

⟦L329⟧

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

⟦L330⟧

• [Navigator 的 page API 重大變更]⟦L208⟧
• [PopScope 泛型型別]⟦L209⟧
• [棄用 ButtonBar，改用 OverflowBar]⟦L210⟧
• [Android 插件渲染至 Surface 的新 API]⟦L211⟧

⟦L331⟧

• [v3.19 後移除的棄用 API]⟦L212⟧
• [將 MaterialState 重新命名為 WidgetState]⟦L213⟧
• [新增 ColorScheme 角色]⟦L214⟧
• [停止支援 Android KitKat]⟦L215⟧
• [PageView.controller 可為 null]⟦L216⟧
• [將 MemoryAllocations 重新命名為 FlutterMemoryAllocations]⟦L217⟧

⟦L332⟧

• [v3.16 後移除的棄用 API]⟦L218⟧
• [RawKeyEvent/RawKeyboard 系統遷移至 KeyEvent/HardwareKeyboard 系統]⟦L219⟧
• [棄用 Flutter Gradle 插件的命令式 apply]⟦L220⟧
• [預設多點觸控滾動]⟦L221⟧
• [tooltip 的無障礙遍歷順序變更]⟦L222⟧

⟦L333⟧

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

⟦L334⟧

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

⟦L335⟧

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

⟦L336⟧

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

⟦L337⟧

• [新增 ImageProvider.loadBuffer]⟦L259⟧
• [桌面版預設 PrimaryScrollController]⟦L260⟧
• [觸控板手勢可觸