diff --git a/src/content/release/breaking-changes/appbar-theme-color.md b/src/content/release/breaking-changes/appbar-theme-color.md new file mode 100644 index 0000000000..3654b2e784 --- /dev/null +++ b/src/content/release/breaking-changes/appbar-theme-color.md @@ -0,0 +1,118 @@ +--- +title: AppBar theme color parameter deprecation +description: >- + The color parameter in AppBarTheme and AppBarThemeData has been + deprecated in favor of backgroundColor for better API consistency. +--- + +## Summary + +The `color` parameter in `AppBarTheme` and `AppBarThemeData` constructors +and their `copyWith` methods hasve been deprecated. Use `backgroundColor` +instead. This change affects how AppBar themes are configured and may +cause deprecation warnings in existing code. + +## Background + +The AppBar theming system had two parameters that controlled the same +property: `color` and `backgroundColor`. This duplication created confusion +and inconsistency in the API. To improve clarity and consistency, the +`color` parameter has been deprecated in favor of `backgroundColor`. + +The deprecation affects the following classes and methods: + +- `AppBarTheme` constructor +- `AppBarTheme.copyWith` method +- `AppBarThemeData` constructor +- `AppBarThemeData.copyWith` method + +When using the deprecated `color` parameter, you'll see warnings like: + +``` +'color' is deprecated and shouldn't be used. Use backgroundColor instead. +This feature was deprecated after v3.33.0-0.2.pre. +``` + +The classes also include assertion checks to prevent using both parameters +simultaneously: + +``` +The color and backgroundColor parameters mean the same thing. Only specify one. +``` + +## Migration guide + +Replace all uses of the `color` parameter with `backgroundColor` in +`AppBarTheme` and `AppBarThemeData` constructors and `copyWith` methods. + +Code before migration: + +```dart +// AppBarTheme constructor +AppBarTheme( + color: Colors.blue, + elevation: 4.0, +) + +// AppBarTheme copyWith +theme.copyWith( + color: Colors.red, + elevation: 2.0, +) + +// AppBarThemeData constructor +AppBarThemeData( + color: Colors.green, + elevation: 4.0, +) + +// AppBarThemeData copyWith +themeData.copyWith( + color: Colors.purple, + elevation: 2.0, +) +``` + +Code after migration: + +```dart +// AppBarTheme constructor +AppBarTheme( + backgroundColor: Colors.blue, + elevation: 4.0, +) + +// AppBarTheme copyWith +theme.copyWith( + backgroundColor: Colors.red, + elevation: 2.0, +) + +// AppBarThemeData constructor +AppBarThemeData( + backgroundColor: Colors.green, + elevation: 4.0, +) + +// AppBarThemeData copyWith +themeData.copyWith( + backgroundColor: Colors.purple, + elevation: 2.0, +) +``` + +## Timeline + +Landed in version: 3.33.0-0.2.pre
+In stable release: Not yet + +## References + +API documentation: + +- [`AppBarTheme`](https://main-api.flutter.dev/flutter/material/AppBarTheme-class.html) +- [`AppBarThemeData`](https://main-api.flutter.dev/flutter/material/AppBarThemeData-class.html) + +Relevant PRs: + +- [AppBar theme color parameter deprecation #170624]({{site.github}}/flutter/flutter/pull/170624) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index a1cd297c20..7d89e35ae2 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -50,6 +50,7 @@ They're sorted by release and listed in alphabetical order: * [Component theme normalization updates][] [Redesigned the Radio Widget]: /release/breaking-changes/radio-api-redesign +[Deprecate app bar color]: /release/breaking-changes/appbar-theme-color [Removed semantics elevation and thickness]: /release/breaking-changes/remove-semantics-elevation-and-thickness [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json