DEV/material-components_material-components-android

mirror of https://github.com/material-components/material-components-android.git synced 2026-01-09 07:11:07 +08:00

pubiqq 81d1b772b9 [Theme] Add NoActionBar dynamic color themes

Resolves https://github.com/material-components/material-components-android/pull/3636

GIT_ORIGIN_REV_ID=ab4463028a14e4d4fbd3a613c4c402b8de39f552
PiperOrigin-RevId: 578900644

2023-11-06 13:58:24 +00:00

16 KiB

Raw Blame History

Getting started with Material Components for Android

1. Migration guidance

Take a look at our guide and codelab to help you migrate your codebase using Material Components for Android to the new Material 3 system.

Additionally, if you are still using the legacy Design Support Library, take a look at our legacy guide to help you migrate your codebase to Material Components for Android.

2. Maven library dependency

Material Components for Android is available through Google's Maven Repository. To use it:

Open the build.gradle file for your application.

Make sure that the repositories section includes Google's Maven Repository google(). For example:

  allprojects {
    repositories {
      google()
      mavenCentral()
    }
  }

Add the library to the dependencies section:

  dependencies {
    // ...
    implementation 'com.google.android.material:material:<version>'
    // ...
  }

Visit Google's Maven Repository or MVN Repository to find the latest version of the library.

Note: In order to use the new Material3 themes and component styles, you should depend on version 1.5.0 or later.

New Namespace and AndroidX

If your app currently depends on the original Design Support Library, you can make use of the Refactor to AndroidX… option provided by Android Studio. Doing so will update your app's dependencies and code to use the newly packaged androidx and com.google.android.material libraries.

If you don't want to switch over to the new androidx and com.google.android.material packages yet, you can use Material Components via the com.android.support:design:28.0.0 dependency.

Note: You should not use the com.android.support and com.google.android.material dependencies in your app at the same time.

3. Android 12 compilation

In order to use the latest versions of Material Components for Android and the AndroidX Jetpack libraries, you will have to install the latest version of Android Studio and update your app's compileSdkVersion to 32.

As part of migrating to Android 12, you'll need to add android:exported to any activities, services, or broadcast receivers in your manifest that use intent filters (see the documentation). Consider reading through the Android 12 app migration guide and behavior changes for more tips and information.

4. Java 8 compilation

The latest Material and AndroidX Jetpack libraries now require your app to be compiled with Java 8. See the Java 8 language features and APIs documentation for more information on Java 8 support and how to enable it for your app.

5. Gradle, AGP, and Android Studio

When using MDC-Android version 1.7.0-alpha02 and above, you will need to make sure your project is built with the following minimum requirements, in order to support the latest build features such as XML macro:

6. `AppCompatActivity`

Use AppCompatActivity to ensure that all the components work correctly. If you are unable to extend from AppCompatActivity, update your activities to use AppCompatDelegate. This will enable the AppCompat or Material versions of components to be inflated (depending on your theme), among other important things.

7. `Material3` theme inheritance

We recommend you perform an app-wide migration by changing your app theme to inherit from a Material3 theme. Be sure to test thoroughly afterwards, since this may change the appearance and behavior of existing layout components.

Check out the new Material Theme Builder which can be used to generate your Material3 app theme, with all of the Material Color System roles filled out based on your brand colors.

Web
Figma

Note: If you can't change your theme, you can continue to inherit from an AppCompat or MaterialComponents theme and add some new theme attributes to your theme. See the AppCompat or MaterialComponents themes section for more details.

`Material3` themes

Here are the Material3 themes you can use to get the latest component styles and theme-level attributes, as well as their MaterialComponents equivalents when applicable.

`Material3`	`MaterialComponents`
`Theme.Material3.Light`	`Theme.MaterialComponents.Light`
`Theme.Material3.Light.NoActionBar`	`Theme.MaterialComponents.Light.NoActionBar`
`Theme.Material3.Dark`	`Theme.MaterialComponents`
`Theme.Material3.Dark.NoActionBar`	`Theme.MaterialComponents.NoActionBar`
`Theme.Material3.DayNight`	`Theme.MaterialComponents.DayNight`
`Theme.Material3.DayNight.NoActionBar`	`Theme.MaterialComponents.DayNight.NoActionBar`
`Theme.Material3.DynamicColors.Light`	N/A
`Theme.Material3.DynamicColors.Light.NoActionBar`	N/A
`Theme.Material3.DynamicColors.Dark`	N/A
`Theme.Material3.DynamicColors.Dark.NoActionBar`	N/A
`Theme.Material3.DynamicColors.DayNight`	N/A
`Theme.Material3.DynamicColors.DayNight.NoActionBar`	N/A
N/A	`Theme.MaterialComponents.Light.DarkActionBar`
N/A	`Theme.MaterialComponents.DayNight.DarkActionBar`

Update your app theme to inherit from one of these themes:

<style name="Theme.MyApp" parent="Theme.Material3.DayNight.NoActionBar">
    <!-- ... -->
</style>

For more information on how to set up theme-level attributes for your app, take a look at our Theming guide, as well as our Dark Theme guide for why it's important to inherit from the DayNight theme.

Material3 themes enable a custom view inflater, which replaces default components with their Material counterparts. Currently, this replaces the following XML components:

<Button → MaterialButton
<CheckBox → MaterialCheckBox
<RadioButton → MaterialRadioButton
<TextView → MaterialTextView
<AutoCompleteTextView → MaterialAutoCompleteTextView

`AppCompat` or `MaterialComponents` Themes

You can incrementally test new Material components without changing your app theme. This allows you to keep your existing layouts looking and behaving the same, while introducing new components to your layout one at a time.

However, you must add the following new theme attributes to your existing app theme, or you will encounter ThemeEnforcement errors:

<style name="Theme.MyApp" parent="Theme.AppCompat OR Theme.MaterialComponents">

  <!-- Original AppCompat attributes. -->
  <item name="colorPrimary">@color/my_app_primary</item>
  <item name="colorPrimaryDark">@color/my_app_primary_dark</item>
  <item name="colorSecondary">@color/my_app_secondary</item>
  <item name="android:colorBackground">@color/my_app_background</item>
  <item name="colorError">@color/my_app_error</item>

  <!-- MaterialComponents attributes (needed if parent="Theme.AppCompat"). -->
  <item name="colorPrimaryVariant">@color/my_app_primary_variant</item>
  <item name="colorSecondaryVariant">@color/my_app_secondary_variant</item>
  <item name="colorSurface">@color/my_app_surface</item>
  <item name="colorOnPrimary">@color/my_app_on_primary</item>
  <item name="colorOnSecondary">@color/my_app_on_secondary</item>
  <item name="colorOnBackground">@color/my_app_on_background</item>
  <item name="colorOnError">@color/my_app_on_error</item>
  <item name="colorOnSurface">@color/my_app_on_surface</item>
  <item name="scrimBackground">@color/mtrl_scrim</item>
  <item name="textAppearanceHeadline1">@style/TextAppearance.MaterialComponents.Headline1</item>
  <item name="textAppearanceHeadline2">@style/TextAppearance.MaterialComponents.Headline2</item>
  <item name="textAppearanceHeadline3">@style/TextAppearance.MaterialComponents.Headline3</item>
  <item name="textAppearanceHeadline4">@style/TextAppearance.MaterialComponents.Headline4</item>
  <item name="textAppearanceHeadline5">@style/TextAppearance.MaterialComponents.Headline5</item>
  <item name="textAppearanceHeadline6">@style/TextAppearance.MaterialComponents.Headline6</item>
  <item name="textAppearanceSubtitle1">@style/TextAppearance.MaterialComponents.Subtitle1</item>
  <item name="textAppearanceSubtitle2">@style/TextAppearance.MaterialComponents.Subtitle2</item>
  <item name="textAppearanceBody1">@style/TextAppearance.MaterialComponents.Body1</item>
  <item name="textAppearanceBody2">@style/TextAppearance.MaterialComponents.Body2</item>
  <item name="textAppearanceCaption">@style/TextAppearance.MaterialComponents.Caption</item>
  <item name="textAppearanceButton">@style/TextAppearance.MaterialComponents.Button</item>
  <item name="textAppearanceOverline">@style/TextAppearance.MaterialComponents.Overline</item>

  <!-- Material3 attributes (needed if parent="Theme.MaterialComponents"). -->
  <item name="colorPrimaryInverse">@color/my_app_primary_inverse</item>
  <item name="colorPrimaryContainer">@color/my_app_primary_container</item>
  <item name="colorOnPrimaryContainer">@color/my_app_on_primary_container</item>
  <item name="colorSecondaryContainer">@color/my_app_secondary_container</item>
  <item name="colorOnSecondaryContainer">@color/my_app_on_secondary_container</item>
  <item name="colorTertiary">@color/my_app_tertiary</item>
  <item name="colorOnTertiary">@color/my_app_on_tertiary</item>
  <item name="colorTertiaryContainer">@color/my_app_tertiary_container</item>
  <item name="colorOnTertiaryContainer">@color/my_app_on_tertiary_container</item>
  <item name="colorSurfaceVariant">@color/my_app_surface_variant</item>
  <item name="colorOnSurfaceVariant">@color/my_app_on_surface_variant</item>
  <item name="colorSurfaceInverse">@color/my_app_inverse_surface</item>
  <item name="colorOnSurfaceInverse">@color/my_app_inverse_on_surface</item>
  <item name="colorOutline">@color/my_app_outline</item>
  <item name="colorErrorContainer">@color/my_app_error_container</item>
  <item name="colorOnErrorContainer">@color/my_app_on_error_container</item>
  <item name="textAppearanceDisplayLarge">@style/TextAppearance.Material3.DisplayLarge</item>
  <item name="textAppearanceDisplayMedium">@style/TextAppearance.Material3.DisplayMedium</item>
  <item name="textAppearanceDisplaySmall">@style/TextAppearance.Material3.DisplaySmall</item>
  <item name="textAppearanceHeadlineLarge">@style/TextAppearance.Material3.HeadlineLarge</item>
  <item name="textAppearanceHeadlineMedium">@style/TextAppearance.Material3.HeadlineMedium</item>
  <item name="textAppearanceHeadlineSmall">@style/TextAppearance.Material3.HeadlineSmall</item>
  <item name="textAppearanceTitleLarge">@style/TextAppearance.Material3.TitleLarge</item>
  <item name="textAppearanceTitleMedium">@style/TextAppearance.Material3.TitleMedium</item>
  <item name="textAppearanceTitleSmall">@style/TextAppearance.Material3.TitleSmall</item>
  <item name="textAppearanceBodyLarge">@style/TextAppearance.Material3.BodyLarge</item>
  <item name="textAppearanceBodyMedium">@style/TextAppearance.Material3.BodyMedium</item>
  <item name="textAppearanceBodySmall">@style/TextAppearance.Material3.BodySmall</item>
  <item name="textAppearanceLabelLarge">@style/TextAppearance.Material3.LabelLarge</item>
  <item name="textAppearanceLabelMedium">@style/TextAppearance.Material3.LabelMedium</item>
  <item name="textAppearanceLabelSmall">@style/TextAppearance.Material3.LabelSmall</item>
  <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.Material3.SmallComponent</item>
  <item name="shapeAppearanceMediumComponent">@style/ShapeAppearance.Material3.MediumComponent</item>
  <item name="shapeAppearanceLargeComponent">@style/ShapeAppearance.Material3.LargeComponent</item>
</style>

8. Add Material components

Take a look at our documentation for the full list of available Material components. Each component's page has specific instructions on how to implement it in your app.

Let's use text fields as an example.

Implementing a text field via XML

The default outlined text field XML is defined as:

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/textfield_label">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>
</com.google.android.material.textfield.TextInputLayout>

Note: If you are not using a theme that inherits from a Material3 theme, you will have to specify the text field style as well, via style="@style/Widget.Material3.TextInputLayout.OutlinedBox"

Other text field styles are also provided. For example, if you want a filled text field in your layout, you can apply the Material3 filled style to the text field in XML:

<com.google.android.material.textfield.TextInputLayout
    style="@style/Widget.Material3.TextInputLayout.FilledBox"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/textfield_label">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>
</com.google.android.material.textfield.TextInputLayout>

Contributors

Material Components for Android welcomes contributions from the community. Check out our contributing guidelines as well as an overview of the directory structure before getting started.

16 KiB Raw Blame History Unescape Escape