破坏性改动 (Breaking changes) 及迁移指南

正如 破坏性改动策略 中描述的，我们会不定期地发布关于破坏性改动的迁移指南。

你可以加入 Flutter announce 和 Dart announce，以获得关于未来破坏性改动的通知。

当你在升级 Flutter 后遇到 Dart 错误时，可以考虑使用 dart fix 命令自动迁移你的代码。并非所有的破坏性改动都支持这种方式，但很多都是支持的。

为了避免被未来的 Flutter 版本破坏，可以考虑将你的测试提交到我们的 测试注册表。

以下是可用的迁移指南，它们按发行版本分类并按字母顺序排列：

• Deprecate OverlayPortal.targetsRootOverlay
• Deprecate TextField.canRequestFocus
• Stop generating AssetManifest.json
• UISceneDelegate adoption
• CupertinoDynamicColor wide gamut support
• $FLUTTER_ROOT/version replaced by $FLUTTER_ROOT/bin/cache/flutter.version.json
• SnackBar with action no longer auto-dismisses
• Deprecate SemanticsProperties.focusable and SemanticsConfiguration.isFocusable

• Component theme normalization updates
• Deprecate DropdownButtonFormField value parameter in favor of initialValue
• Deprecate app bar color
• Redesigned the Radio widget
• Removed semantics elevation and thickness
• The Form widget no longer supports being a sliver
• Flutter now sets default abiFilters in Android builds
• Merged threads on macOS and Windows
• The Visibility widget is no longer focusable by default when maintainState is enabled

• Deprecate SystemContextMenuController.show
• Deprecate ExpansionTileController in favor of ExpansibleController
• Deprecate RouteTransitionRecord.markForRemove in favor of RouteTransitionRecord.markForComplete
• Deprecate ThemeData.indicatorColor in favor of TabBarThemeData.indicatorColor
• Material Theme System Updates
• .flutter-plugins-dependencies replaces .flutter-plugins
• Localized messages are generated into source, not a synthetic package
• Changing the default goldenFileComparator for integration_tests
• Deprecate InputDecoration.maintainHintHeight in favor of InputDecoration.maintainHintSize
• Underdamped spring formula changed

• Removal of v1 Android embedding Java APIs
• Deprecate WebGoldenComparator
• Deprecate ThemeData.dialogBackgroundColor in favor of DialogThemeData.backgroundColor
• ImageFilter.blur default tile mode automatic selection
• Updated Material 3 Slider
• Updated Material 3 progress indicators

• Color wide gamut support
• Component theme normalization
• Deep links flag change
• Material 3 Tokens Update in Flutter
• Remove invalid parameters for InputDecoration.collapsed
• Set default for SystemUiMode to Edge-to-Edge

• Navigator's page APIs breaking change
• Generic types in PopScope
• Deprecate ButtonBar in favor of OverflowBar
• New APIs for Android plugins that render to a Surface

• Deprecated API removed after v3.19
• Rename MaterialState to WidgetState
• Introduce new ColorScheme roles
• Dropping support for Android KitKat
• Nullable PageView.controller
• Rename MemoryAllocations to FlutterMemoryAllocations

• Deprecated API removed after v3.16
• Migrate RawKeyEvent/RawKeyboard system to KeyEvent/HardwareKeyboard system
• Deprecate imperative apply of Flutter's Gradle plugins
• Default multitouch scrolling
• Accessibility traversal order of tooltip changed

• Migrating to Material 3
• Migrate ShortcutActivator and ShortcutManager to KeyEvent system
• The ThemeData.useMaterial3 property is now set to true by default
• Deprecated API removed after v3.13
• Customize tabs alignment using the new TabBar.tabAlignment property
• Deprecate textScaleFactor in favor of TextScaler
• Android 14 nonlinear font scaling enabled
• Deprecate describeEnum and update EnumProperty to be type strict
• Deprecated just-in-time navigation pop APIs for Android Predictive Back
• Deprecated Paint.enableDithering
• Updated default text styles for menus
• Windows: External windows should notify Flutter engine of lifecycle changes
• Windows build path changed to add the target architecture

• Added missing dispose() for some disposable objects in Flutter
• Deprecated API removed after v3.10
• Added AppLifecycleState.hidden enum value
• Moved ReorderableListView's localized strings from material to widgets localizations
• Removed ignoringSemantics properties
• Deprecated RouteInformation.location and its related APIs
• Updated EditableText scroll into view behavior
• Migrate a Windows project to ensure the window is shown
• Updated Checkbox.fillColor behavior

• Dart 3 changes in Flutter v3.10 and later
• Deprecated API removed after v3.7
• Insert content text input client
• Deprecated the window singleton
• Resolve the Android Java Gradle error
• Require one data variant for ClipboardData constructor
• "Zone mismatch" message

• Deprecated API removed after v3.3
• Replaced parameters for customizing context menus with a generic widget builder
• iOS FlutterViewController splashScreenView made nullable
• Migrate of to non-nullable return values, and add maybeOf
• Removed RouteSettings.copyWith
• ThemeData's toggleableActiveColor property has been deprecated
• Migrate a Windows project to support dark title bars

• Adding ImageProvider.loadBuffer
• Default PrimaryScrollController on Desktop
• Trackpad gestures can trigger GestureRecognizer
• Migrate a Windows project to set version information

• Deprecated API removed after v2.10
• Migrate useDeleteButtonTooltip to deleteButtonTooltipMessage of Chips
• Page transitions replaced by ZoomPageTransitionsBuilder

• Deprecated API removed after v2.5
• Raw images on Web uses correct origin and colors
• Required Kotlin version
• Scribble Text Input Client

• Default drag scrolling devices
• Deprecated API removed after v2.2
• Change the enterText method to move the caret to the end of the input text
• GestureRecognizer cleanup
• Introducing package:flutter_lints
• Replace AnimationSheetBuilder.display with collate
• ThemeData's accent properties have been deprecated
• Transition of platform channel test interfaces to flutter_test package
• Using HTML slots to render platform views in the web
• Migrate a Windows project to the idiomatic run loop

The following breaking change was reverted in release 2.2:

Network Policy on iOS and Android

Introduced in version: 2.0.0
Reverted in version: 2.2.0

• Default Scrollbars on Desktop

• Added BuildContext parameter to TextEditingController.buildTextSpan
• Android ActivityControlSurface attachToActivity signature change
• Android FlutterMain.setIsRunningInRobolectricTest testing API removed
• Clip behavior
• Deprecated API removed after v1.22
• Dry layout support for RenderBox
• Eliminating nullOk Parameters
• Material Chip button semantics
• SnackBars managed by the ScaffoldMessenger
• TextSelectionTheme migration
• Transition of platform channel test interfaces to flutter_test package
• Use maxLengthEnforcement instead of maxLengthEnforced

• Android v1 embedding app and plugin creation deprecation
• Cupertino icons 1.0.0
• The new Form, FormField auto-validation API

• Actions API revision
• Adding TextInputClient.currentAutofillScope property
• New Buttons and Button Themes
• Dialogs' Default BorderRadius
• More Strict Assertions in the Navigator and the Hero Controller Scope
• The Route Transition record and Transition delegate updates
• The RenderEditable needs to be laid out before hit testing
• Reversing the dependency between the scheduler and services layer
• Semantics Order of the Overlay Entries in Modal Routes
• showAutocorrectionPromptRect method added to TextInputClient
• TestWidgetsFlutterBinding.clock
• TextField requires MaterialLocalizations

• Adding 'linux' and 'windows' to TargetPlatform enum
• Annotations return local position relative to object
• Container color optimization
• CupertinoTabBar requires Localizations parent
• Generic type of ParentDataWidget changed to ParentData
• ImageCache and ImageProvider changes
• ImageCache large images
• MouseTracker moved to rendering
• MouseTracker no longer attaches annotations
• Nullable CupertinoTheme.brightness
• Rebuild optimization for OverlayEntries and Routes
• Scrollable AlertDialog
• TestTextInput state reset
• TextInputClient currentTextEditingValue
• The forgetChild() method must call super
• The Route and Navigator refactoring
• FloatingActionButton and ThemeData's accent properties