Material 颜色

从 JavaScript 读取 Material 3 调色板（包括 Material 3 Dynamic Colors）。

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.1

Expo UI Jetpack Compose 暴露了 Jetpack Compose 使用的 Material 3 配色方案，因此你可以选择一种配色方案来源，并让 <Host> 下的所有组件始终从该方案中获取主题。

配色方案来源取决于你传入的选项：

基于壁纸生成：在 Android 12 及更高版本中，未提供 seedColor 时的默认选项。使用 Material 3 动态颜色（Material You）。
静态 Material 3 基础配色方案：在 Android 11 及更低版本中，未提供 seedColor 时的默认回退方案。
基于颜色种子生成：传入 seedColor 时，使用 Material 3 动态颜色为基于壁纸的颜色生成配色方案时所用的相同算法，生成完整的配色方案。适用于所有 Android API 级别，且不受壁纸影响。

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

使用颜色种子设置 `<Host>` 的主题

Host 直接接受 seedColor 和 colorScheme 属性。这是为 Compose 子树设置主题的推荐方式。此 Host 下的原生 Compose 组件会使用基于种子生成的配色方案进行渲染，任何调用 useMaterialColors() 且不带参数的后代组件，都会从 Host 的上下文中获得相同的配色方案。

BrandedHostExample.tsx

import { Button, Host, Text } from '@expo/ui/jetpack-compose';

export default function BrandedHostExample() {
  return (
    <Host seedColor="#8E24AA" colorScheme="dark" matchContents>
      <Button onClick={() => {}}>
        <Text>Themed from the seed</Text>
      </Button>
    </Host>
  );
}

在 Host 内读取当前配色方案

在 <Host> 内调用不带参数的 useMaterialColors()，即可读取 Host 当前的配色方案。此 Hook 会返回一个引用稳定的 MaterialColors 对象，并且在重新渲染时不会经过原生桥接。

MaterialColorsExample.tsx

import {
  Column,
  Host,
  Surface,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { padding } from '@expo/ui/jetpack-compose/modifiers';

export default function MaterialColorsExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Surface>
        <PaletteInspector />
      </Surface>
    </Host>
  );
}

function PaletteInspector() {
  const colors = useMaterialColors();
  return (
    <Column
      modifiers={[padding(16, 16, 16, 16)]}
      verticalArrangement={{ spacedBy: 8 }}>
      <Text>Primary: {colors.primary}</Text>
      <Text>Surface: {colors.surface}</Text>
    </Column>
  );
}

使用参数计算特定配色方案

向 useMaterialColors() 传入参数，即可按需计算配色方案，即使在 <Host> 外部也可以使用。colorScheme 可设为 'light' 或 'dark'，也可以省略以跟随系统设置。

UseMaterialColorsExample.tsx

import {
  Column,
  Host,
  Surface,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { padding } from '@expo/ui/jetpack-compose/modifiers';

export default function UseMaterialColorsExample() {
  const dark = useMaterialColors({ colorScheme: 'dark' });
  const brand = useMaterialColors({ seedColor: '#8E24AA' });
  const brandedDark = useMaterialColors({
    colorScheme: 'dark',
    seedColor: '#8E24AA',
  });

  return (
    <Host style={{ flex: 1 }}>
      <Surface>
        <Column
          modifiers={[padding(16, 16, 16, 16)]}
          verticalArrangement={{ spacedBy: 8 }}>
          <Text>Dark primary: {dark.primary}</Text>
          <Text>Brand primary: {brand.primary}</Text>
          <Text>Branded dark primary: {brandedDark.primary}</Text>
        </Column>
      </Surface>
    </Host>
  );
}

在 React 组件外读取颜色

GetMaterialColorsExample.tsx

import {
  getMaterialColors,
  isDynamicColorAvailable,
} from '@expo/ui/jetpack-compose';

const palette = getMaterialColors({ seedColor: '#8E24AA' });
console.log(
  'available:',
  isDynamicColorAvailable,
  'primary:',
  palette.primary
);

API

Constants

`MaterialColors.isDynamicColorAvailable`

Android

Type: boolean

Whether the current device supports Material You dynamic colors (Android 12+). When false, getMaterialColors and useMaterialColors return the static Material 3 baseline palette unless a seedColor is provided — seed-based palettes work on every Android API level.

Hooks

`useMaterialColors(options)`

Android

Parameter	Type
options(optional)	`UseMaterialColorsOptions`

Returns the Material 3 color palette. Call with no arguments inside a <Host> to get the palette that <Host> is themed with. Pass scheme and/or seedColor to get a specific palette.

Returns:

MaterialColors

Methods

`MaterialColors.getMaterialColors(options)`

Android

Parameter	Type
options(optional)	`MaterialColorsOptions`

Get the Material 3 color palette.

Returns:

MaterialColors

Types

`MaterialColors`

Android

Material 3 color palette exposed to TypeScript/JavaScript as #RRGGBBAA strings.

On Android 12+ devices these values are derived from the app user's wallpaper (Material You). On older devices they fall back to the static Material 3 baseline palette. Use isDynamicColorAvailable to distinguish the two at runtime.

Property	Type	Description
background	`RgbaHex`	The background color that appears behind scrollable content.
error	`RgbaHex`	The error color is used to indicate errors in components, such as invalid text in a text field.
errorContainer	`RgbaHex`	The preferred tonal color of error containers.
inverseOnSurface	`RgbaHex`	A color that contrasts well with `inverseSurface`. Useful for content that sits on top of containers that are `inverseSurface`.
inversePrimary	`RgbaHex`	Color to be used as a "primary" color in places where the inverse color scheme is needed, such as the button on a SnackBar.
inverseSurface	`RgbaHex`	A color that contrasts sharply with `surface`. Useful for surfaces that sit on top of other surfaces with surface color.
onBackground	`RgbaHex`	Color used for text and icons displayed on top of the background color.
onError	`RgbaHex`	Color used for text and icons displayed on top of the error color.
onErrorContainer	`RgbaHex`	The color (and state variants) that should be used for content on top of `errorContainer`.
onPrimary	`RgbaHex`	Color used for text and icons displayed on top of the primary color.
onPrimaryContainer	`RgbaHex`	The color (and state variants) that should be used for content on top of `primaryContainer`.
onPrimaryFixed	`RgbaHex`	Color used for text and icons displayed on top of `primaryFixed` or `primaryFixedDim`. Maintains the same tone in light and dark themes.
onPrimaryFixedVariant	`RgbaHex`	An `onPrimaryFixed` variant which provides less emphasis. Useful when a strong contrast is not required.
onSecondary	`RgbaHex`	Color used for text and icons displayed on top of the secondary color.
onSecondaryContainer	`RgbaHex`	The color (and state variants) that should be used for content on top of `secondaryContainer`.
onSecondaryFixed	`RgbaHex`	Color used for text and icons displayed on top of `secondaryFixed` or `secondaryFixedDim`. Maintains the same tone in light and dark themes.
onSecondaryFixedVariant	`RgbaHex`	An `onSecondaryFixed` variant which provides less emphasis. Useful when a strong contrast is not required.
onSurface	`RgbaHex`	Color used for text and icons displayed on top of the surface color.
onSurfaceVariant	`RgbaHex`	The color (and state variants) that can be used for content on top of `surface`.
onTertiary	`RgbaHex`	Color used for text and icons displayed on top of the tertiary color.
onTertiaryContainer	`RgbaHex`	The color (and state variants) that should be used for content on top of `tertiaryContainer`.
onTertiaryFixed	`RgbaHex`	Color used for text and icons displayed on top of `tertiaryFixed` or `tertiaryFixedDim`. Maintains the same tone in light and dark themes.
onTertiaryFixedVariant	`RgbaHex`	An `onTertiaryFixed` variant which provides less emphasis. Useful when a strong contrast is not required.
outline	`RgbaHex`	Subtle color used for boundaries. Outline color role adds contrast for accessibility purposes.
outlineVariant	`RgbaHex`	Utility color used for boundaries for decorative elements when strong contrast is not required.
primary	`RgbaHex`	The primary color is the color displayed most frequently across your app's screens and components.
primaryContainer	`RgbaHex`	The preferred tonal color of containers.
primaryFixed	`RgbaHex`	A primary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.
primaryFixedDim	`RgbaHex`	A primary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.
scrim	`RgbaHex`	Color of a scrim that obscures content.
secondary	`RgbaHex`	The secondary color provides more ways to accent and distinguish your product. Secondary colors are best for: Floating action buttons Selection controls, like checkboxes and radio buttons Highlighting selected text Links and headlines
secondaryContainer	`RgbaHex`	A tonal color to be used in containers.
secondaryFixed	`RgbaHex`	A secondary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.
secondaryFixedDim	`RgbaHex`	A secondary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.
surface	`RgbaHex`	The surface color that affect surfaces of components, such as cards, sheets, and menus.
surfaceBright	`RgbaHex`	A surface variant that is always brighter than `surface`, whether in light or dark mode.
surfaceContainer	`RgbaHex`	A surface variant that affects containers of components, such as cards, sheets, and menus.
surfaceContainerHigh	`RgbaHex`	A surface variant for containers with higher emphasis than `surfaceContainer`. Use this role for content which requires more emphasis than `surfaceContainer`.
surfaceContainerHighest	`RgbaHex`	A surface variant for containers with higher emphasis than `surfaceContainerHigh`. Use this role for content which requires more emphasis than `surfaceContainerHigh`.
surfaceContainerLow	`RgbaHex`	A surface variant for containers with lower emphasis than `surfaceContainer`. Use this role for content which requires less emphasis than `surfaceContainer`.
surfaceContainerLowest	`RgbaHex`	A surface variant for containers with lower emphasis than `surfaceContainerLow`. Use this role for content which requires less emphasis than `surfaceContainerLow`.
surfaceDim	`RgbaHex`	A surface variant that is always dimmer than `surface`, whether in light or dark mode.
surfaceTint	`RgbaHex`	This color will be used by components that apply tonal elevation and is applied on top of `surface`. The higher the elevation the more this color is used.
surfaceVariant	`RgbaHex`	Another option for a color with similar uses of `surface`.
tertiary	`RgbaHex`	The tertiary color that can be used to balance primary and secondary colors, or bring heightened attention to an element such as an input field.
tertiaryContainer	`RgbaHex`	A tonal color to be used in containers.
tertiaryFixed	`RgbaHex`	A tertiary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.
tertiaryFixedDim	`RgbaHex`	A tertiary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.

`MaterialColorsOptions`

Android

Options common to getMaterialColors and useMaterialColors.

Property	Type	Description
scheme(optional)	`'light' \| 'dark'`	Force a specific appearance. When omitted, the palette follows the current system dark/light mode.
seedColor(optional)	`ColorValue`	Seed color used to generate the full Material 3 palette via the `SchemeTonalSpot` variant (the same one Material You uses). When set, the palette is derived from this color on every Android device, including those below Android 12 where wallpaper-based dynamic colors are not available. When omitted, the palette comes from the device wallpaper (Android 12+) or the static Material 3 baseline.

`RgbaHex`

Android

8-digit RGBA hex color string, always in #RRGGBBAA form (uppercase). Compatible with React Native's ColorValue.

String union of string values.

`UseMaterialColorsOptions`

Android

Options for useMaterialColors.

Type: Omit<MaterialColorsOptions, 'scheme'> extended by:

Property	Type	Description
colorScheme(optional)	`ColorSchemeName`	`'light'` or `'dark'` force a specific palette. `'unspecified'`, `null`, or omitted follows the system appearance.

Material 颜色

安装

用法

使用颜色种子设置 <Host> 的主题

在 Host 内读取当前配色方案

使用参数计算特定配色方案

在 React 组件外读取颜色

API

Constants

MaterialColors.isDynamicColorAvailable

Hooks

useMaterialColors(options)

Methods

MaterialColors.getMaterialColors(options)

Types

MaterialColors

MaterialColorsOptions

RgbaHex

UseMaterialColorsOptions

使用颜色种子设置 `<Host>` 的主题

`MaterialColors.isDynamicColorAvailable`

`useMaterialColors(options)`

`MaterialColors.getMaterialColors(options)`

`MaterialColors`

`MaterialColorsOptions`

`RgbaHex`

`UseMaterialColorsOptions`