This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

Expo SystemUI

一个允许与系统 UI 元素交互的库。

Android

iOS

tvOS

Web

GitHub

npm

更新日志

expo-system-ui 使你能够与位于 React 树之外的 UI 元素进行交互。具体来说，它可以设置根视图的背景颜色，以及在 Android 上全局锁定用户界面样式。

安装

Terminal

- npx expo install expo-system-ui

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

在 app 配置中进行配置

如果你的项目中使用了配置插件（Continuous Native Generation (CNG)），你可以使用 expo-system-ui 内置的配置插件来进行配置。该插件允许你从 app config 中配置 Android 上的 userInterfaceStyle 和 iOS 上的 backgroundColor 属性。这些属性无法在运行时设置，且需要构建新的应用二进制文件后才会生效。如果你的应用没有使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "backgroundColor": "#ffffff",
    "userInterfaceStyle": "light",
    "ios": {
      "backgroundColor": "#ffffff",
    }
    "android": {
      "userInterfaceStyle": "light"
    },
    "plugins": ["expo-system-ui"],
  }
}

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation（CNG），或者你正在手动使用原生 android 和 ios 项目，那么你需要向你的原生项目添加以下配置：

Android

要在 Android 上应用 userInterfaceStyle，你需要在 android/app/src/main/res/values/strings.xml 中添加 expo_system_ui_user_interface_style 配置：

<resources>
  <!-- ... -->
  <string name="expo_system_ui_user_interface_style" translatable="false">light</string> <!-- 或 dark -->
</resources>

iOS

要在 iOS 上应用 backgroundColor，你需要在 ios/your-app/Info.plist 中添加 UIUserInterfaceStyle 配置：

<plist>
  <dict>
    <!-- ... -->
    <key>UIUserInterfaceStyle</key>
    <string>Light</string> <!-- 或 Dark -->
  </dict>
</plist>

API

import * as SystemUI from 'expo-system-ui';

Methods

`SystemUI.getBackgroundColorAsync()`

Android

iOS

tvOS

Web

Gets the root view background color.

Returns:

Promise<ColorValue | null>

Current root view background color in hex format. Returns null if the background color is not set.

Example

const color = await SystemUI.getBackgroundColorAsync();

`SystemUI.setBackgroundColorAsync(color)`

Android

iOS

tvOS

Web

Parameter	Type	Description
color	`ColorValue \| null`	Any valid CSS 3 (SVG) color.

Changes the root view background color. Call this function in the root file outside of your component.

Returns:

Promise<void>

Example

SystemUI.setBackgroundColorAsync("black");