Skip to content

Commit 6c75b32

Browse files
QuncCcccccsfshaza2
andauthored
Migration guide for the material theme system updates (#11707)
This PR is to add a breaking change page for the update in the Material Theme system. Related to flutter/flutter#157292 ## Presubmit checklist - [ ] This PR is marked as draft with an explanation if not meant to land until a future stable release. - [x] This PR doesn’t contain automatically generated corrections (Grammarly or similar). - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style) — for example, it doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. --------- Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>
1 parent b3770d6 commit 6c75b32

File tree

2 files changed

+78
-0
lines changed

2 files changed

+78
-0
lines changed

src/content/release/breaking-changes/index.md

+2
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ They're sorted by release and listed in alphabetical order:
4242
* [Deprecate `ThemeData.indicatorColor` in favor of `TabBarThemeData.indicatorColor`][]
4343
* [`ImageFilter.blur` default tile mode automatic selection][]
4444
* [Localized messages are generated into source, not a synthetic package][]
45+
* [Material Theme System Updates][]
4546
* [Stop generating `AssetManifest.json`][]
4647
* [Updated Material 3 `Slider`][]
4748
* [Updated Material 3 progress indicators][]
@@ -54,6 +55,7 @@ They're sorted by release and listed in alphabetical order:
5455
[Deprecate `ThemeData.indicatorColor` in favor of `TabBarThemeData.indicatorColor`]: /release/breaking-changes/deprecate-themedata-indicatorcolor
5556
[`ImageFilter.blur` default tile mode automatic selection]: /release/breaking-changes/image-filter-blur-tilemode
5657
[Localized messages are generated into source, not a synthetic package]: /release/breaking-changes/flutter-generate-i10n-source
58+
[Material Theme System Updates]: /release/breaking-changes/material-theme-system-updates
5759
[Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json
5860
[Updated Material 3 `Slider`]: /release/breaking-changes/updated-material-3-slider
5961
[Updated Material 3 progress indicators]: /release/breaking-changes/updated-material-3-progress-indicators
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Material Theme System Updates
3+
description: >-
4+
`CardTheme`, `DialogTheme`, and `TabBarTheme` have been normalized to follow
5+
Flutter's convention for component themes in the Material library. In
6+
`ThemeData`, the type of these properties have also changed accordingly.
7+
---
8+
9+
## Summary
10+
11+
`CardTheme`, `DialogTheme` and `TabBarTheme` were refactored to
12+
conform to Flutter's conventions for component themes. `CardThemeData`,
13+
`DialogThemeData` and `TabBarThemeData` were added to define overrides for the
14+
defaults of the component visual properties.
15+
16+
During card theme normalization, the type of `ThemeData.cardTheme` is changed
17+
to `Object?` to accept both `CardTheme` and `CardThemeData`, in order to have
18+
a smooth transition for the breaking changes. The same approach was used for
19+
`dialogTheme` and `tabBarTheme`.
20+
21+
To complete the transition and fully conform to the `ThemeData` convention, the
22+
type of `ThemeData.cardTheme` has been changed to `CardThemeData?`; the type of
23+
`ThemeData.dialogTheme` has been changed to `DialogThemeData?`; and the type of
24+
`ThemeData.tabBarTheme` has been changed to `TabBarThemeData?`.
25+
26+
## Migration guide
27+
28+
Previously, the type of `ThemeData.cardTheme` was `Object?` to accpet both
29+
`CardTheme` and `CardThemeData`. Now that the type has been changed to
30+
`CardThemeData?`, a migration is required if `ThemeData.cardTheme` is used.
31+
Similarly, the types of `ThemeData.dialogTheme` and `ThemeData.tabBarTheme`
32+
should be migrated to `DialogThemeData` and `TabBarThemeData`, respectively.
33+
34+
Code before migration:
35+
36+
```dart
37+
final ThemeData theme = ThemeData(
38+
cardTheme: CardTheme(),
39+
dialogTheme: DialogTheme(),
40+
tabBarTheme: TabBarTheme(),
41+
);
42+
```
43+
44+
Code after migration:
45+
46+
```dart
47+
final ThemeData theme = ThemeData(
48+
cardTheme: CardThemeData(),
49+
dialogTheme: DialogThemeData(),
50+
tabBarTheme: TabBarThemeData(),
51+
);
52+
```
53+
54+
## Timeline
55+
56+
Landed in version: TBD
57+
Stable release: TBD
58+
59+
## References
60+
61+
API documentation:
62+
63+
* [`ThemeData`][]
64+
* [`CardTheme`][]
65+
* [`DialogTheme`][]
66+
* [`TabBarTheme`][]
67+
68+
Relevant PRs:
69+
70+
* [Change cardTheme, dialogTheme, and tabBarTheme type to xxxThemeData][]
71+
72+
[Change cardTheme, dialogTheme, and tabBarTheme type to xxxThemeData]: {{site.github}}/flutter/flutter/pull/157292
73+
[`ThemeData`]: {{site.api}}/flutter/material/ThemeData-class.html
74+
[`CardTheme`]: {{site.api}}/flutter/material/CardTheme-class.html
75+
[`DialogTheme`]: {{site.api}}/flutter/material/DialogTheme-class.html
76+
[`TabBarTheme`]: {{site.api}}/flutter/material/TabBarTheme-class.html

0 commit comments

Comments
 (0)