Expo 系统界面

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

Android

iOS

tvOS

Web

Bundled version:

~6.0.9

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

安装

🌐 Installation

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.

应用配置中的配置

🌐 Configuration in app config

在使用连续本地生成 (CNG) 时启用 expo-system-ui 配置插件。该插件允许你从应用配置配置 Android 上的 userInterfaceStyle 和 iOS 上的 backgroundColor 属性。这些属性无法在运行时设置，需要构建新的应用二进制文件才能生效。如果你的应用不使用 CNG，则需要手动配置该库。

🌐 Enable the expo-system-ui config plugin when you use Continuous Native Generation (CNG). The plugin allows you to configure userInterfaceStyle on Android and backgroundColor on iOS properties from app config. These properties cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

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?

如果你没有使用连续本地生成（CNG），或者你是手动使用原生 android 和 ios 项目，那么你需要将以下配置添加到你的原生项目中：

🌐 If you're not using Continuous Native Generation (CNG) or you're using native android and ios project manually, then you need to add the following configuration to your native project:

安卓

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

🌐 To apply userInterfaceStyle on Android, you need to add the expo_system_ui_user_interface_style configuration android/app/src/main/res/values/strings.xml:

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

iOS

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

🌐 To apply backgroundColor on iOS, you need to add the UIUserInterfaceStyle configuration in ios/your-app/Info.plist:

<plist>
  <dict>
    <!-- ... -->
    <key>UIUserInterfaceStyle</key>
    <string>Light</string> <!-- or 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	`null \| ColorValue`	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");