跳到主要内容
版本：Next

外观

tsx
import {Appearance} from 'react-native';

Appearance 模块提供有关用户外观偏好的信息，例如他们偏好的系统配色方案（浅色或深色）。

开发者说明​

信息

Appearance API 的灵感来自 W3C 的 Media Queries 草案。配色方案偏好是参照 prefers-color-scheme CSS 媒体特性 建模的。

示例​

你可以使用 Appearance 模块来判断用户是否偏好深色配色方案：

tsx
const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
  // 使用深色配色方案
}

尽管配色方案会立即可用，但在未通过 setColorScheme() 覆盖时，它可能会发生变化（例如在日出或日落时计划的配色方案变更）。任何依赖用户偏好配色方案的渲染逻辑或样式，都应尝试在每次渲染时调用此函数，而不是缓存该值。

推荐： 使用 useColorScheme Hook。

应用级覆盖​

setColorScheme() 会在应用级别覆盖配色方案——它不会影响系统设置或其他应用程序。传入 'auto' 会移除任何覆盖，恢复系统偏好。

参考

方法​

getColorScheme()​

tsx
static getColorScheme(): 'light' | 'dark' | null;

返回当前激活的配色方案。此值可能在运行时发生变化，既可能是系统级别的变化（例如在日出或日落时计划的配色方案变更），也可能是在应用级别通过 setColorScheme() 覆盖后发生变化。

返回值：

  • 'light'：应用浅色配色方案。
  • 'dark'：应用深色配色方案。
  • null：当原生 Appearance 模块不可用时可能返回。

另见：useColorScheme（Hook）。

setColorScheme()​

tsx
static setColorScheme('light' | 'dark' | 'auto' | 'unspecified'): void;

强制应用始终采用浅色或深色界面风格。此更改会应用于应用及其内部的所有原生元素（Alerts、Pickers 等）。

这是应用级覆盖——它不会影响系统选定的界面风格，也不会影响其他应用中设置的任何风格。

支持的值：

  • 'light'：应用浅色配色方案。
  • 'dark'：应用深色配色方案。
  • 'auto'：遵循系统配色方案（移除任何覆盖）。
  • 'unspecified'（已弃用）：遵循系统配色方案（移除任何覆盖）。

addChangeListener()​

tsx
static addChangeListener(
  listener: (preferences: {colorScheme: 'light' | 'dark' | null}) => void,
): NativeEventSubscription;

添加一个事件处理程序，当外观偏好发生变化时触发。在 iOS 和 Android 上，回调中的 colorScheme 值始终为 'light' 或 'dark'。