diff --git a/_config.yml b/_config.yml index c67277f93b..9888fbc5ef 100644 --- a/_config.yml +++ b/_config.yml @@ -19,6 +19,7 @@ repo: plugins: https://github.com/flutter/plugins gallery: https://github.com/flutter/gallery engine: https://github.com/flutter/engine + uxr: https://github.com/flutter/uxr dart: api: https://api.dart.dev sdk: diff --git a/src/assets/images/docs/platform-adaptations/cupertino-alert.png b/src/assets/images/docs/platform-adaptations/cupertino-alert.png new file mode 100644 index 0000000000..cffd155fbc Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/cupertino-alert.png differ diff --git a/src/assets/images/docs/platform-adaptations/m3-alert.png b/src/assets/images/docs/platform-adaptations/m3-alert.png new file mode 100644 index 0000000000..a9dd39ed9d Binary files /dev/null and b/src/assets/images/docs/platform-adaptations/m3-alert.png differ diff --git a/src/resources/platform-adaptations.md b/src/resources/platform-adaptations.md index 35c29cfcc9..941766cf42 100644 --- a/src/resources/platform-adaptations.md +++ b/src/resources/platform-adaptations.md @@ -28,6 +28,12 @@ For an example of an app using different information architecture structures on Android and iOS but sharing the same content code, see the [platform_design code samples][]. +{{site.alert.info}} +Preliminary guides addressing case 2 +are being added to the UI components section. +You can request additional guides by commenting on [issue #8427][]. +{{site.alert.end}} + ## Page navigation Flutter provides the navigation patterns seen on Android @@ -548,6 +554,85 @@ double tap and shows the selection toolbar. +## UI components + +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][]. + +### Alert dialog + +Since Android 12, the default UI of alert dialogs +(also known as a "basic dialog") follows the design guidelines +defined in [Material 3][m3-dialog] (M3). +On iOS, an equivalent component called “alert” is defined in Apple’s +[Human Interface Guidelines][hig-alert] (HIG). + +
+
+
+
+ Basic Dialog in Material 3 +
+ Basic Dialog in M3 +
+
+
+
+
+ Alert in Human Interface Guidelines +
+ Alert in HIG +
+
+
+
+
+ +Since alert dialogs are often tightly integrated with the operating system, +their design generally needs to follow the platform conventions. +This is especially important when a dialog is used to request user input +about security, privacy, and destructive operations (e.g., deleting files +permanently). As an exception, a branded alert dialog design can be used on +non-critical user flows to highlight specific information or messages. + +To implement platform-specific alert dialogs, +you can use Flutter’s `AlertDialog` widget on Android +and the `CupertinoAlertDialog` widget on iOS. Below is a code snippet you can +adapt to show a platform-specific alert dialog. + +```dart +void _showAdaptiveDialog( + context, { + required Text title, + required Text content, + required List actions, +}) { + Platform.isIOS || Platform.isMacOS + ? showCupertinoDialog( + context: context, + builder: (BuildContext context) => CupertinoAlertDialog( + title: title, + content: content, + actions: actions, + ), + ) + : showDialog( + context: context, + builder: (BuildContext context) => AlertDialog( + title: title, + content: content, + actions: actions, + ), + ); +} +``` + +Further detail about adapting alert dialogs is available in +[this post][alert-post], where you can leave feedback or ask questions. + [issue #8410]: {{site.repo.flutter}}/issues/8410#issuecomment-468034023 [android.app.AlertDialog]: {{site.android-dev}}/reference/android/app/AlertDialog.html @@ -565,3 +650,7 @@ double tap and shows the selection toolbar. [slides up and fades in]: {{site.api}}/flutter/material/FadeUpwardsPageTransitionsBuilder-class.html [`startActivity()`]: {{site.android-dev}}/reference/android/app/Activity.html#startActivity(android.content.Intent [`WidgetsApp`]: {{site.api}}/flutter/widgets/WidgetsApp-class.html +[issue #8427]: {{site.repo.this}}/issues/8427 +[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