Translation from foreign documents plus your own understanding of the original text

We recently announced Material Design Components (MDC) 1.1.0, a library update that brings Material Theming, new Components, dark themes, and other exciting features to your Android applications.

MDC replaces the design support library. This guide will show you how to migrate the code base so that you can use the new properties, styles, and widgets.

A concise topic example

This guide uses a streamlined application to demonstrate the migration process. It uses the AppCompat theme, widgets from the design support library (including buttons with custom backgrounds), and various other elements that need to be migrated. We’ll start with an application theme that uses the traditional AppCompat template:

<style name="Theme.App" parent="Theme.AppCompat.*">
    <item name="colorPrimary">@color/navy_700</item>
    <item name="colorPrimaryDark">@color/navy_900</item>
    <item name="colorAccent">@color/green_300</item>
</style>
Copy the code

Apps that use AppCompat and the Design Support Library

fromSupport LibraryMigration toJetPack

Before you can use MDC, you need to migrate from the support library to Android Jetpack. Jetpack uses the new Androidx.* namespace and splits the previous support library package into a semantically versioned library that is maintained separately to provide a partially functional new library. MDC is built using the AndroidX libraries and therefore must be migrated.

To migrate to AndroidX, it is recommended that you follow the official developer documentation. Refactoring > Migrating to AndroidX tools in Android Studio restructures your Design Support Library dependencies into MDC.

Updates to the MDC

Build. Gradle dependency

Com. Android. Support: design: 28.0.0 modified into com. Google. Android. Material: material: 1.0.0

Change the topic

You need to subclass the app theme to the Material Components theme

<style name = "Theme.App" parent = "Theme.MaterialComponents.">

There is a one-to-one mapping between the style and AppCompat in the MDC theme, and in most cases it is simply a matter of replacing AppCompat with MaterialComponents

AppCompat theme MDC-Android theme
Theme.AppCompat Theme.MaterialComponents
Theme.AppCompat.NoActionBar Theme.MaterialComponents.NoActionBar
Theme.AppCompat.Dialog.* Theme.MaterialComponents.Dialog.*
Theme.AppCompat.DialogWhenLarge Theme.MaterialComponents.DialogWhenLarge
Theme.AppCompat.Light Theme.MaterialComponents.Light
Theme.AppCompat.Light.DarkActionBar Theme.MaterialComponents.Light.DarkActionBar
Theme.AppCompat.Light.NoActionBar Theme.MaterialComponents.Light.NoActionBar
Theme.AppCompat.Light.Dialog.* Theme.MaterialComponents.Light.Dialog.*
Theme.AppCompat.Light.DialogWhenLarge Theme.MaterialComponents.Light.DialogWhenLarge
Theme.AppCompat.DayNight Theme.MaterialComponents.DayNight
Theme.AppCompat.DayNight.DarkActionBar Theme.MaterialComponents.DayNight.DarkActionBar
Theme.AppCompat.DayNight.NoActionBar Theme.MaterialComponents.DayNight.NoActionBar
Theme.AppCompat.DayNight.Dialog.* Theme.MaterialComponents.DayNight.Dialog.*
Theme.AppCompat.DayNight.DialogWhenLarge Theme.MaterialComponents.DayNight.DialogWhenLarge
AppCompat theme overlay MDC-Android theme overlay
ThemeOverlay.AppCompat ThemeOverlay.MaterialComponents
ThemeOverlay.AppCompat.Light ThemeOverlay.MaterialComponents.Light
ThemeOverlay.AppCompat.Dark ThemeOverlay.MaterialComponents.Dark
ThemeOverlay.AppCompat.*.ActionBar ThemeOverlay.MaterialComponents.*.ActionBar.*
ThemeOverlay.AppCompat.Dialog.* ThemeOverlay.MaterialComponents.Dialog.*
N/A ThemeOverlay.MaterialComponents.*.BottomSheetDialog
N/A ThemeOverlay.MaterialComponents.MaterialAlertDialog.*
N/A ThemeOverlay.MaterialComponents.MaterialCalendar.*
N/A ThemeOverlay.MaterialComponents.Toolbar.*

Example updates

Button to change

From the Design library to the MDC, style into a Theme. The MaterialComponents. * there are some changes. Take buttons, for example. Buttons lose their custom background. The Button now has a green accent color and the spacing between the fonts is greater.

So why does this happen? Let’s look at the layout first

<Button
    android:id="@+id/containedButton"// This is a custom color backgroundandroid:background="@drawable/bg_button_gradient"
    android:textColor="@android:color/white"
    . />
<Button
    android:id="@+id/textButton"
    style="? Attr/borderlessButtonStyle"
    . />
Copy the code

This happens because when the layout is populated, the normal controls in our layout are automatically replaced with MDC controls.

Like AppCompat, MDC replaces some of the original controls with MDC equivalent controls at the time of populating. This allows you to release new features and bug fixes without having to replace all declarations with new types. This is done through MaterialComponentsViewInflater, it belongs to AppCompatViewInflater subclass.

Mapping:

Framework widget AppCompat widget (replaced by AppCompatViewInflater) MDC-Android widget (replaced by MaterialComponentsViewInflater)
Button AppCompatButton MaterialButton
CheckBox AppCompatCheckBox MaterialCheckBox
RadioButton AppCompatRadioButton MaterialRadioButton
TextView AppCompatTextView MaterialTextView
AutoCompleteTextView AppCompatAutoCompleteTextView MaterialAutoCompleteTextView

Note: Only the Button control is replaced in MDC 1.0.0.

In our example, if it is a Theme.AppCompat.*, then the Button will be replaced by AppCompatButton. Now the Theme modified into the Theme. MaterialComponents. *, would have replaced the Button into MaterialButton, there will be the default style

Unlike the AppCompatButton, the MaterialButton does not support a custom background. Support is available with version 1.2.0- Alpha06. With Shape, you can be flexible. More on this in the following sections.

Update MDC 1.1.0

There are many new changes from 1.0.0 to 1.1.0:

  • The completeMaterial Theming
  • Dark Themesupport
  • Android 10 gesture navigation support
  • New components: Extended FAB, Date Picker, Badges, Toggle Buttons
  • Accessibility improvements, bug fixes, etc

Implementation 'com. Google. Android. Material: material: 1.1.0'

Some unexpected changes and common problems

MDC 1.1.0 changed some of the default widget styles to better conform to the “Material Design” guidelines. However, after upgrading, you may notice some unexpected changes to the color and other properties of some controls.

In the example above, the button changes and the text and icon color changes. The FAB is now turquoise, and the text fields look completely different. Don’t worry. Our current theme may be missing some important MDC attributes, and there are some important AppCompat or original attributes (Android: XXX) that are no longer needed. Let’s look at some common migration scenarios to understand these issues

Text field changed

In MDC, the default style of literal fields has changed. The improved version was researched by users.

We recommend that you use this version to improve availability and configurability. But we realize that this may not be a good fit for your brand and design system.

To restore old text fields, you can add styles to the layout

<com.google.android.material.textfield.TextInputLayout
    .
+    style="@style/Widget.Design.TextInputLayout">.</com.google.android.material.textfield.TextInputLayout>
Copy the code

Or you can set default styles for all text in the theme

<style name="Theme.App" parent="Theme.MaterialComponents.*">. +<item name="TextInputStyle">@style/Widget.App.TextInputLayout</item>
</style>

+<style name="Widget. App. TextInputLayout" parent="Widget. Design. TextInputLayout">
+    <! -- Custom attrs -->
+</style>
Copy the code

Prefers THE MDC style and controls

As mentioned above, the style of the previous support libraries has become part of MDC. In most cases, we can all through the Widget. The MaterialComponents. * replace the Widget in the Design. * style. New properties are also enabled, and although you can leave them out, we recommend the new MDC style!

It is recommended to replace AppCompat or MaterialButton (if any) with an MDC component. These components use the updated material design guide by default. And support for enabling Material Theming and other features.

Here are a few things to consider

  • Use the MDC control if it exists for the control written in the layout
  • Any style, default style, and default style properties should be changed to the MDC version
  • Any controls used either programmatically or by the parent class of the custom class should be the MDC version.

Complete control and style mapping table

MDC-Android widget (moved from Design Support Library) Design Support Library default style MDC-Android default style Default style attr
AppBarLayout Widget.Design.AppBarLayout Widget.MaterialComponents.AppBarLayout.* appBarLayoutStyle
BottomNavigationView Widget.Design.BottomNavigationView Widget.MaterialComponents.BottomNavigationView bottomNavigationStyle
BottomSheetBehavior Widget.Design.BottomSheet.Modal Widget.MaterialComponents.BottomSheet.* bottomSheetStyle
BottomSheetDialog BottomSheetDialogFragment Theme.Design.Light.BottomSheetDialog Theme.MaterialComponents.*.BottomSheetDialog ThemeOverlay.MaterialComponents.*.BottomSheetDialog bottomSheetDialogTheme
CollapsingToolbarLayout Widget.Design.CollapsingToolbar N/A N/A
FloatingActionButton Widget.Design.FloatingActionButton Widget.MaterialComponents.FloatingActionButton floatingActionButtonStyle
NavigationView Widget.Design.NavigationView Widget.MaterialComponents.NavigationView navigationViewStyle
Snackbar Widget.Design.Snackbar Widget.MaterialComponents.Snackbar snackbarStyle
TabLayout TabItem Widget.Design.TabLayout Widget.MaterialComponents.TabLayout tabStyle
TextInputLayout TextInputEditText Widget.Design.TextInputLayout Widget.MaterialComponents.TextInputLayout.* textInputStyle
AppCompat widget AppCompat default style AppCompat default style attr MDC-Android widget MDC-Android default style MDC-Android default style attr
AlertDialog.Builder AlertDialog.AppCompat ThemeOverlay.AppCompat.Dialog.Alert alertDialogStyle alertDialogTheme MaterialAlertDialogBuilder MaterialAlertDialog.MaterialComponents ThemeOverlay.MaterialComponents.MaterialAlertDialog alertDialogStyle materialAlertDialogTheme
AppCompatAutoCompleteTextView Widget.AppCompat.AutoCompleteTextView autoCompleteTextViewStyle MaterialAutoCompleteTextView Widget.MaterialComponents.AutoCompleteTextView.* ThemeOverlay.MaterialComponents.AutoCompleteTextView.* autoCompleteTextViewStyle
AppCompatButton Widget.AppCompat.Button buttonStyle MaterialButton Widget.MaterialComponents.Button materialButtonStyle
AppCompatCheckBox Widget.AppCompat.CompoundButton.CheckBox checkboxStyle MaterialCheckbox Widget.MaterialComponents.CompoundButton.CheckBox checkboxStyle
AppCompatImageView N/A N/A ShapeableImageView Widget.MaterialComponents.ShapeableImageView N/A
AppCompatRadioButton Widget.AppCompat.CompoundButton.RadioButton radioButtonStyle MaterialRadioButton Widget.MaterialComponents.CompoundButton.RadioButton radioButtonStyle
AppCompatTextView Widget.AppCompat.TextView N/A MaterialTextView Widget.MaterialComponents.TextView N/A
CardView CardView cardViewStyle MaterialCardView Widget.MaterialComponents.CardView materialCardViewStyle
PopupMenu Widget.AppCompat.PopupMenu.* popupMenuStyle N/A Widget.MaterialComponents.PopupMenu.* popupMenuStyle
SwitchCompat Widget.AppCompat.CompoundButton.Switch switchStyle SwitchMaterial Widget.MaterialComponents.CompoundButton.Switch switchStyle
Toolbar Widget.AppCompat.Toolbar toolbarStyle MaterialToolbar Widget.MaterialComponents.Toolbar toolbarStyle

IO /develop/and…

Sample update

Replace the MDC component with an MDC component

<! -- Copyright 2020 Google LLC. spdx-license-identifier: apache-2.0 -->
-<androidx.cardview.widget.CardView
+<com.google.android.material.card.MaterialCardView
    android:id="@+id/card"
    .>. -</androidx.cardview.widget.CardView>
+</com.google.android.material.card.MaterialCardView>

-<androidx.appcompat.widget.SwitchCompat
+<com.google.android.material.switch.SwitchMaterial
    android:id="@+id/switch"
    . />
Copy the code

color

The color palette for MDC is drawn directly from the Material Design Color System.

Since the history is shared between MDC-Android, AppCompat, and the framework, the set of color properties includes the following:

  • Appropriately named existing attributes in the framework (for exampleandroid:colorBackground)
  • Existing properly-named attributes in AppCompat (for examplecolorPrimaryandcolorError)
  • New attributes are introduced by MDC, such ascolorSurface.colorOnPrimaryEtc.)

The MDC widget uses these properties to color its background, text, ICONS, and so on. To understand which widgets use which colors, you need to examine the default widget styles in the source code.

Some colors still exist in AppCompat and the framework, but they are no longer suitable for this new system. The Theme. MaterialComponents. Try your best to backward compatibility they * themes, such as the widget, these old property.

<item name="colorAccent">? attr/colorSecondary</item>

However, you should consider not recommending these properties. Use more appropriate MDC properties or phase them out.

See the color attribute mapping table below:

Note that the color attribute in AppCompat should not be used

AppCompat/frame color properties Mdc-android color properties
colorPrimary colorPrimary
colorPrimaryDark colorPrimaryVariant （android:statusBarColorExplicitly specified)
Do not apply colorOnPrimary
colorAccent colorSecondary
Do not apply colorSecondaryVariant
Do not apply colorOnSecondary
Do not apply colorSurface
Do not apply colorOnSurface
android:colorBackground android:colorBackground
Do not apply colorOnBackground
colorError colorError
Do not apply colorOnError
android:textColorPrimary.android:textColorSecondaryAnd so on. N/A (You are advised to set the MDC attribute to on or use the default value)
colorControlNormal.colorControlHighlight.colorControlActivated N/A (use the default MDC preference for “on” or ATTRS) *** Note: *These are still used for coloringMaterialCheckBox.MaterialRadioButton.SwitchMaterialandMaterialToolbaricon.

example

<style name="Theme.App" parent="Theme.MaterialComponents.*">.<item name="colorPrimary">@color/navy_700</item>
-    <item name="colorPrimaryDark">@color/navy_900</item>
+    <item name="colorPrimaryVariant">@color/navy_900</item>
-    <item name="colorAccent">@color/green_300</item>
+    <item name="colorSecondary">@color/green_300</item>
+    <item name="ColorSecondaryVariant">@color/green_500</item>
+    <item name="android:statusBarColor">@color/navy_900</item>
</style>
Copy the code

@color We should also use the new “on” color property for the included button text color

<! -- Copyright 2020 Google LLC. spdx-license-identifier: apache-2.0 -->
<Button
-    android:textColor="@android:color/white"
+    android:textColor="? attr/colorOnPrimary"
    . />
Copy the code

The font type

New TextAppearance style/property

The MDC font palette is extracted directly from the Material Design type system. The expression means adhering to Material Design style

Introduced a new set of TextAppearance. MaterialComponents. Corresponding TextAppearance * * style and theme properties, they replaced the existing AppCompat/frame style.

The MDC widget uses these properties to set text styles. To know which widgets use which type of palette, you need to examine the default widget styles in the source code.

See the full list of type styles and attribute mappings below: 13 types

AppCompat text style Mdc-android text style MDC-Android text properties
TextAppearance.AppCompat.Display4 TextAppearance.MaterialComponents.Headline1 textAppearanceHeadline1
TextAppearance.AppCompat.Display3 TextAppearance.MaterialComponents.Headline2 textAppearanceHeadline2
TextAppearance.AppCompat.Display2 TextAppearance.MaterialComponents.Headline3 textAppearanceHeadline3
TextAppearance.AppCompat.Display1 TextAppearance.MaterialComponents.Headline4 textAppearanceHeadline4
TextAppearance.AppCompat.Headline TextAppearance.MaterialComponents.Headline5 textAppearanceHeadline5
TextAppearance.AppCompat.Title TextAppearance.AppCompat.Large TextAppearance.MaterialComponents.Headline6 textAppearanceHeadline6
TextAppearance.AppCompat.Subhead TextAppearance.AppCompat.Menu TextAppearance.MaterialComponents.Subtitle1 textAppearanceSubtitle1
TextAppearance.AppCompat.Small TextAppearance.MaterialComponents.Subtitle2 textAppearanceSubtitle2
TextAppearance.AppCompat.Body1 TextAppearance.MaterialComponents.Body1 textAppearanceBody1
TextAppearance.AppCompat.Body2 TextAppearance.MaterialComponents.Body2 textAppearanceBody2
TextAppearance.AppCompat.Button TextAppearance.MaterialComponents.Button textAppearanceButton
TextAppearance.AppCompat.Caption TextAppearance.MaterialComponents.Caption textAppearanceCaption
Do not apply TextAppearance.MaterialComponents.Overline textAppearanceOverline

example

<com.google.android.material.card.MaterialCardView
    .>.<TextView
        android:id="@ + id/the headerText"
-        android:textAppearance="@style/TextAppearance.AppCompat.Title"
+        android:textAppearance="? attr/textAppearanceHeadline6"
        . />
    <TextView
        android:id="@ + id/subheadText"
        android:textColor="? android:attr/textColorSecondary"
-        android:textAppearance="@style/TextAppearance.AppCompat.Body2"
+        android:textAppearance="? attr/textAppearanceBody2"
        . />
    <TextView
        android:id="@ + id/supportingText"
        android:textColor="? android:attr/textColorSecondary"
-        android:textAppearance="@style/TextAppearance.AppCompat.Body2"
+        android:textAppearance="? attr/textAppearanceBody2"
        . />
</com.google.android.material.card.MaterialCardView>
Copy the code

The custom

We also have the option to override the type ratio in the application theme to use a custom font family, XML or download the font through Android Studio:

<! -- Copyright 2020 Google LLC. spdx-license-identifier: apache-2.0 -->
<style name="Theme.App" parent="Theme.MaterialComponents.*">. +<item name="textAppearanceHeadline6">@style/TextAppearance.App.Headline6</item>
+    <item name="textAppearanceBody2">@style/TextAppearance.App.Body2</item>
</style>

+<style name="TextAppearance.App.Headline6"
+    parent="TextAppearance.MaterialComponents.Headline6">
+    <item name="fontFamily">@font/roboto_mono_medium</item>
+</style>
+<style name="TextAppearance.App.Body2"
+    parent="TextAppearance.MaterialComponents.Body2">
+    <item name="fontFamily">@font/roboto_mono_regular</item>
+</style>
Copy the code

Above we have only overridden one of the 13 types. If you want to change the font, it is recommended that you also change the remaining 12 to keep the font consistent in the APP.

Shape

ShapeAppearance styles/attributes

Shape (Material Design Shape System) is used to handle the edges of THE MDC control, divided into small, medium, and large

These appropriate style properties come from ShapeAppearance.* styles. CornerFamily (two values: rounded cut). I’m going to say cornerSize

The MDC widget uses these properties to set its background style. To understand which widgets fit into which shape categories, you need to examine the default widget styles in the source code.

Controls the background

The class that implements this function is MaterialShapeDrawable. By default, all MDC controls use this drawable object as the background, and we can also consider using it as the background for our custom View. It can handle shape themes, shadows, black themes, and so on.

So. We do not recommend using Android: Background as the background for MDC controls. Because it overrides the MaterialShapeDrawable. The default style for most MDC controls is

@null

In order to avoid this kind of situation, should use shapeApperance/shapeAppearanceOverlay and backgroundTint attribute to adjust the background shape and color.

The following situations require separate attention:

  • MaterialButton 在 1.2.0 - alpha06Omitted before versionandroid:backgroundIf you do need to use this property, consider using itAppCompatButtonIn your layout.
  • MaterialShapeDrawableIt is not supportedgradients. If you really need it, use itandroid:background

example

In our example we can remove some of the properties handled by Shape Theming.

<com.google.android.material.bottomnavigation.BottomNavigationView
-    android:background="@android:color/white"
    . />

<com.google.android.material.card.MaterialCardView
-    app:cardCornerRadius="2dp"
    .>.</com.google.android.material.card.MaterialCardView>
Copy the code

usecorner family 和 sizeFrom definition shape

We can choose to express our own brand by overlaying shape styles in the application theme.

<style name="Theme.App" parent="Theme.MaterialComponents.*">. +<item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
+    <item name="shapeAppearanceMediumComponent">@style/ShapeAppearance.App.MediumComponent</item>
+    <item name="shapeAppearanceLargeComponent">@style/ShapeAppearance.App.LargeComponent</item>
</style>

+<style name="ShapeAppearance.App.SmallComponent"
+   parent="ShapeAppearance.MaterialComponents.SmallComponent">
+    <item name="cornerFamily">rounded</item>
+    <item name="cornerSize">8dp</item>
+</style>
+<style name="ShapeAppearance.App.MediumComponent"
+    parent="ShapeAppearance.MaterialComponents.MediumComponent">
+    <item name="cornerFamily">rounded</item>
+    <item name="cornerSize">12dp</item>
+</style>
+<style name="ShapeAppearance.App.LargeComponent"
+    parent="ShapeAppearance.MaterialComponents.LargeComponent">
+    <item name="cornerFamily">rounded</item>
+    <item name="cornerSize">16dp</item>
+</style>
Copy the code

Example using Shape Theming

Restore Button’s custom gradient background

-<Button
+<androidx.appcompat.widget.AppCompatButton
    android:background="@drawable/bg_button_gradient"
+    android:textAppearance="? attr/textAppearanceButton"
    . />
Copy the code

If you are using MDC 1.2.0-alpha-06 or later, you can directly use the Android: Background of MaterialButton. Note that you want to clear backgroundTint, because in the default style, backgroundTint is colorPrimary

<! -- Copyright 2020 Google LLC. spdx-license-identifier: apache-2.0 -->
<Button
    android:background="@drawable/bg_button_gradient"
+    app:backgroundTint="@null"
    . />
Copy the code