DEV/material-components_material-components-android
1
0
Fork 0
mirror of https://github.com/material-components/material-components-android.git synced 2026-01-27 19:14:22 +08:00
Code Issues Packages Projects Releases Wiki Activity
material-components_materia.../docs/components/Dialog.md
pekingme 2114a11378 [Docs] Updated dev doc for tonal surface colors in affected components. 
PiperOrigin-RevId: 556901517
2023-08-14 20:55:38 +00:00

285 lines
14 KiB
Markdown
Raw Blame History

<!--docs:
title: "Dialogs"
layout: detail
section: components
excerpt: "Dialogs are modal windows that require interaction."
iconId: dialog
path: /catalog/dialogs/
-->
# Dialogs
[Dialogs](https://material.io/components/dialogs/) inform users about a task and
can contain critical information, require decisions, or involve multiple tasks.
!["Dialog to confirm settings centered in a screen"](assets/dialogs/dialogs_hero.png)
**Contents**
* [Design & API documentation](#design-api-documentation)
* [Using dialogs](#using-dialogs)
* [Basic dialog](#basic-dialog)
* [Full-screen dialog](#full-screen-dialog)
* [Theming](#theming-dialogs)
## Design & API Documentation
* [Google Material3 Spec](https://material.io/components/date-pickers/overview)
* [API reference](https://developer.android.com/reference/com/google/android/material/dialog/package-summary)
## Using dialogs
Before you can use Material dialogs, you need to add a dependency to the
Material Components for Android library. For more information, go to the
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
page.
```kt
MaterialAlertDialogBuilder(context)
// Add customization options here
.show()
```
### Making dialogs accessible
The contents within a dialog should follow their own accessibility guidelines,
such as an icon on a title having a content description via the
`android:contentDescription` attribute set in the
`MaterialAlertDialog.Material3.Title.Icon` style or descendant.
### Types
There are two types of dialogs: 1\. [Basic dialog](#basic-dialog), 2\.
[Full-screen dialog](#full-screen-dialog)
![Examples of the two types of dialogs.](assets/dialogs/dialogs_types.png)
## Dialogs
A dialog is a type of modal window that appears in front of app content to
provide critical information or ask for a decision. Dialogs disable all app
functionality when they appear, and remain on screen until confirmed, dismissed,
or a required action has been taken.
Dialogs are purposefully interruptive, so they should be used sparingly.
### Dialog examples
API and source code:
* `MaterialAlertDialogBuilder`
* [Class description](https://developer.android.com/reference/com/google/android/material/dialog/MaterialAlertDialogBuilder)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/MaterialAlertDialogBuilder.java)
## Basic dialog
The following example shows a basic dialog.
!["Dialog with title, and text and purple buttons to cancel, decline or accept"](assets/dialogs/dialogs_basic.png)
In code:
```kt
MaterialAlertDialogBuilder(context)
.setTitle(resources.getString(R.string.title))
.setMessage(resources.getString(R.string.supporting_text))
.setNeutralButton(resources.getString(R.string.cancel)) { dialog, which ->
// Respond to neutral button press
}
.setNegativeButton(resources.getString(R.string.decline)) { dialog, which ->
// Respond to negative button press
}
.setPositiveButton(resources.getString(R.string.accept)) { dialog, which ->
// Respond to positive button press
}
.show()
```
## Full-screen dialog
Full-screen dialogs group a series of tasks, such as creating a calendar entry
with the event title, date, location, and time. Because they take up the entire
screen, full-screen dialogs are the only dialogs over which other dialogs can
appear.
There is no specific Material implementation of a full-screen dialog. You can
implement it by using a
[`DialogFragment`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment)
as explained in the
[Android Developer guides](https://developer.android.com/guide/topics/ui/dialogs#FullscreenDialog).
### Anatomy and key properties
A dialog has a container, content (either supporting text or a set of items of a
particular type), a background scrim, and, optionally, title and buttons.
![anatomy](assets/dialogs/dialogs_anatomy.png)
1. Container
2. Icon (optional)
3. Title (optional)
4. Content
5. Buttons (optional)
6. Scrim
#### Container attributes
Element | **Attribute** | **Related methods** | **Default value**
----------------------------------- | -------------------------------------------------------- | ------------------------------------------------------ | -----------------
**Color** | `app:backgroundTint` | N/A | `?attr/colorSurfaceContainerHigh`
**Shape** | `app:shapeAppearance`<br/>`app:shapeAppearanceOverlay` | N/A | `?attr/shapeAppearanceCornerExtraLarge`
**Background inset start and end** | `app:backgroundInsetStart`<br/>`app:backgroundInsetEnd` | `setBackgroundInsetStart`<br/>`setBackgroundInsetEnd` | `24dp`
**Background inset top and bottom** | `app:backgroundInsetTop`<br/>`app:backgroundInsetBottom` | `setBackgroundInsetTop`<br/>`setBackgroundInsetBottom` | `80dp`
#### Title attributes
Element | **Attribute** | **Related methods** | **Default value**
-------------- | ------------------------ | -------------------------------- | -----------------
**Text label** | N/A | `setTitle`<br/>`setCustomTitle` | `null`
**Text color** | `android:textColor` | N/A | `?attr/colorOnSurface`
**Typography** | `android:textAppearance` | N/A | `?attr/textAppearanceHeadlineSmall`
**Icon** | N/A | `setIcon`<br/>`setIconAttribute` | `null`
**Icon tint** | `app:tint` | N/A | `?attr/colorSecondary`
#### Content attributes
**Supporting text**
Element | **Attribute** | **Related methods** | **Default value**
-------------- | ------------------------ | ------------------- | -----------------
**Text** | N/A | `setMessage` | `null`
**Color** | `android:textColor` | N/A | `?attr/colorOnSurfaceVariant`
**Typography** | `android:textAppearance` | N/A | `?attr/textAppearanceBodyMedium`
**List item**
Element | **Attribute** | **Related methods** | **Default value**
--------------------------------------- | ------------------------------ | ---------------------- | -----------------
**List item layout** | `app:listItemLayout` | `setItems` | [`@layout/mtrl_alert_select_dialog_item`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_item.xml)
**List item layout style** | N/A | N/A | `?attr/materialAlertDialogBodyTextStyle`
**List item text color** | `android:textColor` | N/A | `?attr/colorOnSurfaceVariant`
**List item typography** | `android:textAppearance` | N/A | `?attr/textAppearanceBodyMedium`
**Multi choice item layout** | `app:multiChoiceItemLayout` | `setMultiChoiceItems` | [`@layout/mtrl_alert_select_dialog_multichoice`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_multichoice.xml)
**Single choice item layout** | `app:singleChoiceItemLayout` | `setSingleChoiceItems` | [`@layout/mtrl_alert_select_dialog_singlechoice`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_singlechoice.xml)
**Multi/single choice item style** | `android:checkedTextViewStyle` | N/A | `@style/Widget.Material3.CheckedTextView`
**Multi/single choice item text color** | `android:textColor` | N/A | `?attr/colorOnSurfaceVariant`
**Multi/single choice item typography** | `android:textAppearance` | N/A | `?attr/textAppearanceBodyLarge`
**Note:** You can set any custom view to be the content of your dialog via the
`setView` method.
#### Buttons attributes
Element | **Attribute** | **Related methods** | **Default value**
------------------------------------------------ | --------------------------------- | ------------------- | -----------------
**Buttons theme attributes (negative/positive)** | `app:buttonBar*ButtonStyle` | N/A | `@style/Widget.Material3.Button.TextButton.Dialog`
**Buttons theme attributes (neutral)** | `app:buttonBarNeutralButtonStyle` | N/A | `@style/Widget.Material3.Button.TextButton.Dialog.Flush`
**Buttons (neutral/negative/positive)** | N/A | `set*Button` | `null`
**Icons** | N/A | `set*ButtonIcon` | `null`
For specific button attributes, see the
[Buttons documentation](https://github.com/material-components/material-components-android/tree/master/docs/components/Button.md).
#### Scrim attributes
Element | **Attribute** | **Related methods** | **Default value**
-------------- | ----------------------------- | ------------------- | -----------------
**Dim amount** | `android:backgroundDimAmount` | N/A | 32%
#### Theme overlays
Element | **Theme overlay**
-------------------------- | -----------------
**Default theme overlay** | `ThemeOverlay.Material3.MaterialAlertDialog`
**Centered theme overlay** | `ThemeOverlay.Material3.MaterialAlertDialog.Centered`
Default theme overlay attribute: `?attr/materialAlertDialogTheme`
#### Theme attributes
Element | **Theme attribute** | **Default value**
------------------------- | ----------------------------------------- | -----------------
**Default style** | `?attr/alertDialogStyle` | `@style/MaterialAlertDialog.Material3`
**Title text style** | `?attr/materialAlertDialogTitleTextStyle` | `@style/MaterialAlertDialog.Material3.Title.Text`
**Supporting text style** | `?attr/materialAlertDialogBodyTextStyle` | `@style/MaterialAlertDialog.Material3.Body.Text`
See full list of
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/styles.xml),
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/attrs.xml),
and
[theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/themes.xml).
## Theming dialogs
A dialog supports
[Material Theming](https://material.io/components/dialogs/#theming) which can
customize color, typography and shape.
### Dialog theming example
API and source code:
* `MaterialAlertDialogBuilder`
* [Class description](https://developer.android.com/reference/com/google/android/material/dialog/MaterialAlertDialogBuilder)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/MaterialAlertDialogBuilder.java)
The following example shows a dialog with Material Theming.
![Dialog with title and text buttons in brown and selected radio button in pink](assets/dialogs/dialogs_theming.png)
#### Implementing dialog theming
Setting the theme attribute `materialAlertDialogTheme` to your custom
`ThemeOverlay` will affect all dialogs.
In `res/values/themes.xml`:
```xml
<style name="Theme.App" parent="Theme.Material3.*">
...
<item name="materialAlertDialogTheme">@style/ThemeOverlay.App.MaterialAlertDialog</item>
</style>
<style name="ThemeOverlay.App.MaterialAlertDialog" parent="ThemeOverlay.Material3.MaterialAlertDialog">
<item name="colorPrimary">@color/shrine_pink_100</item>
<item name="colorSecondary">@color/shrine_pink_100</item>
<item name="colorSurface">@color/shrine_pink_light</item>
<item name="colorOnSurface">@color/shrine_pink_900</item>
<item name="alertDialogStyle">@style/MaterialAlertDialog.App</item>
<item name="materialAlertDialogTitleTextStyle">@style/MaterialAlertDialog.App.Title.Text</item>
<item name="buttonBarPositiveButtonStyle">@style/Widget.App.Button</item>
<item name="buttonBarNegativeButtonStyle">@style/Widget.App.Button</item>
</style>
```
In `res/values/styles.xml`:
```xml
<style name="MaterialAlertDialog.App" parent="MaterialAlertDialog.Material3">
<item name="shapeAppearance">@style/ShapeAppearance.App.MediumComponent</item>
<item name="shapeAppearanceOverlay">@null</item>
</style>
<style name="MaterialAlertDialog.App.Title.Text" parent="MaterialAlertDialog.Material3.Title.Text">
<item name="android:textColor">@color/shrine_pink_900</item>
</style>
<style name="Widget.App.Button" parent="Widget.Material3.Button.TextButton.Dialog">
<item name="android:textColor">@color/shrine_pink_900</item>
</style>
<style name="ShapeAppearance.App.MediumComponent" parent="ShapeAppearance.Material3.MediumComponent">
<item name="cornerFamily">cut</item>
<item name="cornerSize">8dp</item>
</style>
```
Or if you want to change only one specific dialog, pass the `themeResId` to the
constructor:
```kt
MaterialAlertDialogBuilder(context, R.style.ThemeOverlay_App_MaterialAlertDialog)
...
.show()
```
Reference in New Issue View Git Blame Copy Permalink