diff --git a/src/assets/images/docs/platform-adaptations/hig-appbar.png b/src/assets/images/docs/platform-adaptations/hig-appbar.png new file mode 100644 index 00000000000..8f0776ca025 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-appbar.png differ diff --git a/src/assets/images/docs/platform-adaptations/hig-checkbox.png b/src/assets/images/docs/platform-adaptations/hig-checkbox.png new file mode 100644 index 00000000000..2b6a66354b4 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-checkbox.png differ diff --git a/src/assets/images/docs/platform-adaptations/hig-progress.png b/src/assets/images/docs/platform-adaptations/hig-progress.png new file mode 100644 index 00000000000..949b3e08328 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-progress.png differ diff --git a/src/assets/images/docs/platform-adaptations/hig-radio.png b/src/assets/images/docs/platform-adaptations/hig-radio.png new file mode 100644 index 00000000000..d90fd058f2f Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-radio.png differ diff --git a/src/assets/images/docs/platform-adaptations/hig-slider.png b/src/assets/images/docs/platform-adaptations/hig-slider.png new file mode 100644 index 00000000000..a710d49da8b Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-slider.png differ diff --git a/src/assets/images/docs/platform-adaptations/hig-switch.png b/src/assets/images/docs/platform-adaptations/hig-switch.png new file mode 100644 index 00000000000..a85e299f485 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/hig-switch.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-checkbox.png b/src/assets/images/docs/platform-adaptations/m3-checkbox.png new file mode 100644 index 00000000000..2fec7626664 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-checkbox.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-progress.png b/src/assets/images/docs/platform-adaptations/m3-progress.png new file mode 100644 index 00000000000..d07221c9136 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-progress.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-radio.png b/src/assets/images/docs/platform-adaptations/m3-radio.png new file mode 100644 index 00000000000..fd1c8219f33 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-radio.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-slider.png b/src/assets/images/docs/platform-adaptations/m3-slider.png new file mode 100644 index 00000000000..319ef58b39b Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-slider.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-switch.png b/src/assets/images/docs/platform-adaptations/m3-switch.png new file mode 100644 index 00000000000..c25df89099f Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-switch.png differ diff --git a/src/assets/images/docs/platform-adaptations/mat-appbar.png b/src/assets/images/docs/platform-adaptations/mat-appbar.png new file mode 100644 index 00000000000..36d2a1e23b3 Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/mat-appbar.png differ diff --git a/src/resources/platform-adaptations.md b/src/resources/platform-adaptations.md index 941766cf42f..57cc09dfe74 100644 --- a/src/resources/platform-adaptations.md +++ b/src/resources/platform-adaptations.md @@ -296,6 +296,11 @@ Therefore a fallback font is used when running on Android if the platform is debug-overridden to iOS or the default Cupertino theme is used. +You might choose to adapt the text styling of Material +widgets to match the default text styling on iOS. +You can see widget-specific examples in the +[UI Component section][]. +
@@ -560,6 +565,99 @@ This section includes preliminary recommendations on how to adapt Material widgets to deliver a natural and compelling experience on iOS. Your feedback is welcomed on [issue #8427][]. +### Widgets with .adaptive() constructors + +Several widgets support `.adaptive()` constructors. +Adaptive constructors substitute the corresponding Cupertino components +when the app is run on an iOS device. + +Widgets in the following table are used primarily for input, +selection, and to display system information. +Because these controls are tightly integrated with the operating system, +users have been trained to recognize and respond to them. +Therefore, we recommend that you follow platform conventions. + + +| Material Widget | Cupertino Widget | Adaptive Constructor | +|---|---|---|---|---| +|Switch in Material 3
`Switch`|Switch in HIG
`CupertinoSwitch`|[`Switch.adaptive()`][]| +|Slider in Material 3
`Slider`|Slider in HIG
`CupertinoSlider`|[`Slider.adaptive()`][]| +|Circular progress indicator in Material 3
`CircularProgressIndicator`|Activity indicator in HIG
`CupertinoActivityIndicator`|[`CircularProgressIndicator.adaptive()`][]| + + + +### Top app bar and navigation bar + +Since Android 12, the default UI for top app +bars follow the design guidelines defined in [Material 3][mat-appbar]. +On iOS, an equivalent component called "Navigation Bars" +is defined in [Apple’s Human Interface Guidelines][hig-appbar] (HIG). + +
+
+
+
+  Top App Bar in Material 3 +
+ Top App Bar in Material 3 +
+
+
+
+
+ Navigation Bar in Human Interface Guidelines +
+ Navigation Bar in Human Interface Guidelines +
+
+
+
+
+ +Certain properties of app bars in Flutter apps should be adapted, +like system icons and page transitions. +These are already automatically adapted when using +the Material `AppBar` and `SliverAppBar` widgets. +You can also further customize the properties of these widgets to better +match iOS platform styles, as shown below. + +```dart +// Map the text theme to iOS styles +TextTheme cupertinoTextTheme = TextTheme( + headlineMedium: CupertinoThemeData() + .textTheme + .navLargeTitleTextStyle + // fixes a small bug with spacing + .copyWith(letterSpacing: -1.5), + titleLarge: CupertinoThemeData().textTheme.navTitleTextStyle) +... + +// Use iOS text theme on iOS devices +ThemeData( + textTheme: Platform.isIOS ? cupertinoTextTheme : null, + ... +) +... + +// Modify AppBar properties +AppBar( + surfaceTintColor: Platform.isIOS ? Colors.transparent : null, + shadowColor: Platform.isIOS ? CupertinoColors.darkBackgroundGray : null, + scrolledUnderElevation: Platform.isIOS ? .1 : null, + toolbarHeight: Platform.isIOS ? 44 : null, + ... + ), + +``` + +But, because app bars are displayed alongside +other content in your page, it's only recommended to adapt the styling +so long as its cohesive with the rest of your application. You can see +additional code samples and a further explanation in [the GitHub discussion on app bar adaptations][appbar-post]. + ### Alert dialog Since Android 12, the default UI of alert dialogs @@ -631,7 +729,8 @@ void _showAdaptiveDialog( ``` Further detail about adapting alert dialogs is available in -[this post][alert-post], where you can leave feedback or ask questions. +[the GitHub discussion on dialog adaptations][alert-post]. +You can leave feedback or ask questions in the discussion. [issue #8410]: {{site.repo.flutter}}/issues/8410#issuecomment-468034023 @@ -654,3 +753,12 @@ Further detail about adapting alert dialogs is available in [m3-dialog]: https://m3.material.io/components/dialogs/overview [hig-alert]: https://developer.apple.com/design/human-interface-guidelines/components/presentation/alerts/ [alert-post]: {{site.repo.uxr}}/discussions/92 +[appbar-post]: {{site.repo.uxr}}/discussions/93 +[mat-appbar]: https://m3.material.io/components/top-app-bar/overview +[hig-appbar]: https://developer.apple.com/design/human-interface-guidelines/components/navigation-and-search/navigation-bars/ + +[`Switch.adaptive()`]: {{site.api}}/flutter/material/Switch/Switch.adaptive.html +[`Slider.adaptive()`]: {{site.api}}/flutter/material/Slider/Slider.adaptive.html +[`CircularProgressIndicator.adaptive()`]: {{site.api}}/flutter/material/CircularProgressIndicator/CircularProgressIndicator.adaptive.html +[UI Component section]: {{site.api}}/resources/platform-adaptations/#ui-components \ No newline at end of file