mirror of
https://github.com/material-components/material-components-android.git
synced 2026-01-23 16:01:40 +08:00
451f6199cd
Resolves https://github.com/material-components/material-components-android/pull/726 GIT_ORIGIN_REV_ID=54fe70015a2f3bf9ad7b41e9dfd1d5016f9ef04c PiperOrigin-RevId: 277561393
218 lines
7.1 KiB
Markdown
218 lines
7.1 KiB
Markdown
<!--docs:
|
|
title: "Tab Layout"
|
|
layout: detail
|
|
section: components
|
|
excerpt: "A horizontal layout to display tabs."
|
|
iconId: tabs
|
|
path: /catalog/tab-layout/
|
|
-->
|
|
|
|
# Tab Layout
|
|
|
|
`TabLayout` provides a horizontal layout to display tabs. The layout handles
|
|
interactions for a group of tabs including:
|
|
|
|
- scrolling behavior,
|
|
- (swipe) gestures,
|
|
- tab selection,
|
|
- animations,
|
|
- and alignment.
|
|
|
|
The Android Developers site provides
|
|
[detailed documentation](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout)
|
|
on implementing `TabLayout`.
|
|
|
|
## Design & API Documentation
|
|
|
|
- [Material Design guidelines: Tabs](https://material.io/go/design-tabs)
|
|
<!--{: .icon-list-item.icon-list-item--spec }-->
|
|
- [Class definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayout.java)
|
|
<!--{: .icon-list-item.icon-list-item--link }-->
|
|
- [Class overview](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout)
|
|
<!--{: .icon-list-item.icon-list-item--link }--> <!--{: .icon-list }-->
|
|
|
|
## Usage
|
|
|
|
To use a `TabLayout` with a static number of tabs, define each tab as a
|
|
`TabItem` directly in the layout.
|
|
|
|
```xml
|
|
<com.google.android.material.tabs.TabLayout
|
|
android:id="@+id/tabs"
|
|
android:layout_width="match_parent"
|
|
android:layout_height="wrap_content">
|
|
|
|
<com.google.android.material.tabs.TabItem
|
|
android:icon="@drawable/ic_icon_a_24"
|
|
android:text="@string/tab_a_label"/>
|
|
<com.google.android.material.tabs.TabItem
|
|
android:icon="@drawable/ic_icon_b_24"
|
|
android:text="@string/tab_b_label"/>
|
|
<com.google.android.material.tabs.TabItem
|
|
android:icon="@drawable/ic_icon_c_24"
|
|
android:text="@string/tab_c_label"/>
|
|
|
|
</com.google.android.material.tabs.TabLayout>
|
|
```
|
|
|
|
A tab layout should be used above the content associated with the respective
|
|
tabs and lets the user quickly change between content views. These content views
|
|
are often held in a
|
|
[ViewPager](https://developer.android.com/reference/android/support/v4/view/ViewPager.html).
|
|
|
|
Use
|
|
[setupWithViewPager(ViewPager)](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout#setupWithViewPager\(ViewPager\))
|
|
to link a `TabLayout` with a ViewPager. The individual tabs in the `TabLayout`
|
|
will be automatically populated with the page titles from the PagerAdapter.
|
|
|
|
```java
|
|
ViewPager pager;
|
|
TabLayout tabs = (TabLayout) findViewById(R.id.tabs);
|
|
|
|
tabs.setupWithViewPager(pager);
|
|
```
|
|
|
|
Alternatively, you can add a `TabLayout` to a ViewPager in XML:
|
|
|
|
```xml
|
|
<androidx.viewpager.widget.ViewPager
|
|
android:layout_width="match_parent"
|
|
android:layout_height="match_parent">
|
|
|
|
<com.google.android.material.tabs.TabLayout
|
|
android:layout_width="match_parent"
|
|
android:layout_height="wrap_content"
|
|
android:layout_gravity="top" />
|
|
|
|
</androidx.viewpager.widget.ViewPager>
|
|
```
|
|
|
|
### Badges
|
|
|
|
|
|
|
|
`TabLayout` supports displaying icon and number badges.
|
|
|
|
```java
|
|
// Creates and initializes an instance of BadgeDrawable associated with a tab.
|
|
// Subsequent calls to this method will reuse the existing BadgeDrawable.
|
|
// This method does not guarantee that the badge is visible.
|
|
BadgeDrawable badge = tablayout.getTabAt(0).getOrCreateBadge();
|
|
badge.setVisible(true);
|
|
// Optionally show a number.
|
|
badge.setNumber(99);
|
|
```
|
|
|
|
NOTE: Don't forget to remove any BadgeDrawables that are no longer needed.
|
|
|
|
```java
|
|
tablayout.getTabAt(0).removeBadge();
|
|
```
|
|
|
|
Best Practice: If you only need to temporarily hide the badge(e.g. until the
|
|
next notification is received), the recommended/lightweight alternative is to
|
|
change the visibility of the BadgeDrawable instead.
|
|
|
|
Please see [`BadgeDrawable`](BadgeDrawable.md) for details on how to update the
|
|
badge content being displayed.
|
|
|
|
### Material Styles
|
|
|
|
Using `TabLayout` with an updated Material theme (`Theme.MaterialComponents`)
|
|
will provide the correct updated Material styles to your tabs by default. If you
|
|
need to use updated Material tabs and your application theme does not inherit
|
|
from an updated Material theme, you can apply one of the updated Material styles
|
|
directly to your widget in XML.
|
|
|
|
#### Updated Material Style (Default)
|
|
|
|
The updated Material `TabLayout` style consists of updated icon and label tints,
|
|
ripple color, and ripple shape.
|
|
|
|
```xml
|
|
<com.google.android.material.tabs.TabLayout
|
|
style="@style/Widget.MaterialComponents.TabLayout"
|
|
android:layout_width="match_parent"
|
|
android:layout_height="wrap_content"/>
|
|
```
|
|
|
|
#### Colored Material Style
|
|
|
|
The colored Material `TabLayout` style consists of updated background color
|
|
based on `?attr/colorPrimary`.
|
|
|
|
```xml
|
|
<com.google.android.material.tabs.TabLayout
|
|
style="@style/Widget.MaterialComponents.TabLayout.Colored"
|
|
android:layout_width="match_parent"
|
|
android:layout_height="wrap_content"/>
|
|
```
|
|
|
|
#### Legacy Material Style
|
|
|
|
```xml
|
|
<com.google.android.material.tabs.TabLayout
|
|
style="@style/Widget.Design.TabLayout"
|
|
android:layout_width="match_parent"
|
|
android:layout_height="wrap_content"/>
|
|
```
|
|
|
|
### Attributes
|
|
|
|
Feature | Relevant attributes
|
|
---------- | -------------------
|
|
Size | `app:tabMinWidth`<br/>`app:tabMaxWidth`
|
|
Scroll | `app:tabMode`
|
|
Centered | `app:tabGravity`
|
|
Background | `app:tabBackground`
|
|
Icon | `app:tabIconTint`<br/>`app:tabIconTintMode`
|
|
Label | `app:tabInlineLabel`<br/>`app:tabTextAppearance`<br/>`app:tabTextColor`<br/>`app:tabSelectedTextColor`
|
|
Indicator | `app:tabIndicatorColor`<br/>`app:tabIndicatorHeight`<br/>`app:tabIndicator`<br/>`app:tabIndicatorGravity`<br/>`app:tabIndicatorFullWidth`
|
|
Position | `app:tabContentStart`<br/>`app:tabPaddingStart`<br/>`app:tabPaddingTop`<br/>`app:tabPaddingEnd`<br/>`app:tabPaddingBottom`<br/>`app:tabPadding`
|
|
Ripple | `app:tabRippleColor`
|
|
|
|
### Theme Attribute Mapping
|
|
|
|
#### Updated Material Style (Default)
|
|
|
|
```
|
|
style="@style/Widget.MaterialComponents.TabLayout"
|
|
```
|
|
|
|
Component Attribute | Default Theme Attribute Value
|
|
------------------------- | -------------------------------
|
|
`tabTextAppearance` | `textAppearanceButton`
|
|
`android:background` | `colorSurface`
|
|
`tabTextColor` (selected) | `colorPrimary`
|
|
`tabTextColor` | `colorOnSurface` at 60% opacity
|
|
`tabIconTint` (selected) | `colorPrimary`
|
|
`tabIconTint` | `colorOnSurface` at 60% opacity
|
|
`tabRippleColor` | `colorPrimary`
|
|
`tabIndicatorColor` | `colorPrimary`
|
|
|
|
#### Colored Material Style
|
|
|
|
```
|
|
style="@style/Widget.MaterialComponents.TabLayout.Colored"
|
|
```
|
|
|
|
Component Attribute | Default Theme Attribute Value
|
|
------------------------- | -------------------------------
|
|
`tabTextAppearance` | `textAppearanceButton`
|
|
`android:background` | `colorPrimary`
|
|
`tabTextColor` (selected) | `colorOnPrimary`
|
|
`tabTextColor` | `colorOnPrimary` at 60% opacity
|
|
`tabIconTint` (selected) | `colorOnPrimary`
|
|
`tabIconTint` | `colorOnPrimary` at 60% opacity
|
|
`tabRippleColor` | `colorOnPrimary`
|
|
`tabIndicatorColor` | `colorOnPrimary`
|
|
|
|
#### Legacy Material Style
|
|
|
|
```
|
|
style="@style/Widget.Design.TabLayout"
|
|
```
|
|
|
|
The legacy Material style of `TabLayout` does not make use of our new theming
|
|
attributes.
|