Skip to main content

Appearance

import {Appearance} from 'react-native';

Appearance 模块公开有关用户外观偏好的信息，例如他们喜欢的配色方案（浅色或深色）。

¥The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

开发者注意事项​

¥Developer notes

Appearance API 的灵感来自于 W3C 的 媒体查询草稿。配色方案首选项以 prefers-color-scheme CSS 媒体功能 为蓝本。

¥The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

示例​

¥Example

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

¥You can use the Appearance module to determine if the user prefers a dark color scheme:

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

尽管配色方案立即可用，但这可能会发生变化（例如，计划在日出或日落时更改配色方案）。任何依赖于用户首选配色方案的渲染逻辑或样式都应尝试在每次渲染时调用此函数，而不是缓存该值。例如，你可以使用 useColorScheme React hook，因为它提供并订阅配色方案更新，或者你可以使用内联样式而不是在 StyleSheet。

¥Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

参考

¥Reference

方法​

¥Methods

getColorScheme()​

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

指示当前用户首选的配色方案。该值可以稍后通过直接用户操作（例如，设备设置中的主题选择或通过 setColorScheme 选择应用级别的用户界面样式）或按计划（例如，遵循日/夜循环的浅色和深色主题）进行更新。

¥Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via setColorScheme) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

支持的配色方案：

¥Supported color schemes:

  • light：用户更喜欢浅色主题。

    ¥light: The user prefers a light color theme.

  • dark：用户更喜欢深色主题。

    ¥dark: The user prefers a dark color theme.

  • 无效的：用户未指定首选颜色主题。

    ¥null: The user has not indicated a preferred color theme.

也可以看看：useColorScheme 钩。

¥See also: useColorScheme hook.

注意：使用 Chrome 进行调试时，getColorScheme() 将始终返回 light。

¥Note: getColorScheme() will always return light when debugging with Chrome.

setColorScheme()​

static setColorScheme('light' | 'dark' | null): void;

强制应用始终采用浅色或深色界面样式。默认值为 null，这使得应用继承系统的界面样式。如果你分配不同的值，新样式将应用于应用以及应用中的所有原生元素（警报、选择器等）。

¥Force the application to always adopt a light or dark interface style. The default value is null which causes the application to inherit the system's interface style. If you assign a different value, the new style applies to the application and all native elements within the application (Alerts, Pickers etc).

支持的配色方案：

¥Supported color schemes:

  • light：应用轻量级用户界面样式。

    ¥light: Apply light user interface style.

  • dark：应用深色用户界面样式。

    ¥dark: Apply dark user interface style.

  • 无效的：遵循系统的界面样式。

    ¥null: Follow the system's interface style.

注意：该更改不会影响系统选择的界面样式或其他应用中设置的任何样式。

¥Note: The change will not affect the system's selected interface style or any style set in other applications.

addChangeListener()​

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

添加一个在外观首选项更改时触发的事件处理程序。

¥Add an event handler that is fired when appearance preferences change.