跳到主要内容

外观

React TSX
import {Appearance} from 'react-native';

Appearance 模块公开用户外观偏好的信息，例如用户偏好的系统配色方案（浅色或深色）。

开发者说明​

信息

Appearance API 的设计灵感来源于 W3C 的 Media Queries 草案。配色方案偏好基于 prefers-color-scheme CSS 媒体特性。

示例​

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

React TSX
const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
  // Use dark color scheme
}

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

推荐： 使用 useColorScheme hook。

应用级覆盖​

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

参考

方法​

getColorScheme()​

React TSX
static getColorScheme(): 'light' | 'dark' | null;

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

返回值：

  • 'light'：应用浅色配色方案
  • 'dark'：应用深色配色方案
  • null：如果原生 Appearance 模块不可用，则可能返回此值

另请参阅：useColorScheme（hook）。

setColorScheme()​

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

强制应用始终采用浅色或深色界面样式。此变更会应用于应用及其中的所有原生元素（Alerts、Pickers 等）。

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

支持的值：

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

addChangeListener()​

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

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