安全区域

了解如何在 Expo 项目中添加屏幕组件的安全区域。

创建安全区域可确保你的应用屏幕内容定位正确。这意味着它不会被凹口、状态栏、主页指示器和其他属于设备物理硬件或由操作系统控制的界面元素重叠。当内容重叠时，它会被这些界面元素隐藏。

¥Creating a safe area ensures your app screen's content is positioned correctly. This means it doesn't get overlapped by notches, status bars, home indicators, and other interface elements that are part of the device's physical hardware or are controlled by the operating system. When the content gets overlapped, it gets concealed by these interface elements.

以下是 Android 上应用屏幕内容被状态栏隐藏的示例。在 iOS 上，相同的内容被圆角、凹口和状态栏隐藏。

¥Here's an example of an app screen's content getting concealed by the status bar on Android. On iOS, the same content is concealed by rounded corners, notch, and the status bar.

使用 react-native-safe-area-context 库

¥Use react-native-safe-area-context library

react-native-safe-area-context 提供了一个灵活的 API 来处理 Android 和 iOS 设备的安全区域插入。它还提供了一个 SafeAreaView 组件，你可以使用它代替 <View> 自动考虑屏幕组件中的安全区域。

¥react-native-safe-area-context provides a flexible API for handling Android and iOS device's safe area insets. It also provides a SafeAreaView component that you can use instead of a <View> to account for safe areas automatically in your screen components.

使用该库，上一个示例的结果会发生变化，因为它会在安全区域内显示内容，如下所示：

¥Using the library, the result of the previous example changes as it displays the content inside a safe area, as shown below:

安装

¥Installation

如果你使用 这篇博文 创建了项目，则可以跳过安装 react-native-safe-area-context。此库作为 Expo Router 库的对等依赖安装。否则，请通过运行以下命令进行安装：

¥You can skip installing react-native-safe-area-context if you have created a project using the default template. This library is installed as peer dependency for Expo Router library. Otherwise, install it by running the following command:

用法

¥Usage

你可以直接使用 SafeAreaView 来封装屏幕组件的内容。它是一个常规的 <View>，安全区域插入应用为额外的填充或边距。

¥You can directly use SafeAreaView to wrap the content of your screen's component. It is a regular <View> with the safe area insets applied as extra padding or margin.

import { Text } from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';

export default function HomeScreen() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Text>Content is in safe area.</Text>
    </SafeAreaView>
  );
}

import { SafeAreaProvider } from 'react-native-safe-area-context';

export default function App() {
  return (
    return <SafeAreaProvider>...</SafeAreaProvider>;
  );
}

备选：useSafeAreaInsets 钩

¥Alternate: useSafeAreaInsets hook

除了 SafeAreaView，你还可以在屏幕组件中使用 useSafeAreaInsets 钩子。它提供对安全区域插入的直接访问，允许你使用此钩子中的插入为 <View> 的每个边缘应用填充。

¥Alternate to SafeAreaView, you can use useSafeAreaInsets hook in your screen component. It provides direct access to the safe area insets, allowing you to apply padding for each edge of the <View> using an inset from this hook.

下面的示例使用 useSafeAreaInsets 钩子。它使用 insets.top 将顶部填充应用于 <View>。

¥The example below uses the useSafeAreaInsets hook. It applies top padding to a <View> using insets.top.

import { Text, View } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

export default function HomeScreen() {
  const insets = useSafeAreaInsets();

  return (
    <View style={{ flex: 1, paddingTop: insets.top }}>
      <Text>Content is in safe area.</Text>
    </View>
  );
}

钩子在以下对象中提供插入：

¥The hook provides the insets in the following object:

{
  top: number,
  right: number,
  bottom: number,
  left: number
}

附加信息

¥Additional information

最小的例子

¥Minimal example

下面是一个最小的工作示例，它使用 useSafeAreaInsets 钩子将顶部填充应用于视图。

¥Below is a minimal working example that uses the useSafeAreaInsets hook to apply top padding to a view.

import { Text, View } from 'react-native';
import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';

function HomeScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={{ flex: 1, paddingTop: insets.top }}>
      <Text style={{ fontSize: 28 }}>Content is in safe area.</Text>
    </View>
  );
}

export default function App() {
  return (
    <SafeAreaProvider>
      <HomeScreen />
    </SafeAreaProvider>
  );
}

与 React 导航一起使用

¥Usage with React Navigation

默认情况下，React Navigation 支持安全区域并使用 react-native-safe-area-context 作为对等依赖。有关详细信息，请参阅 React 导航文档。

¥By default, React Navigation supports safe areas and uses react-native-safe-area-context as a peer dependency. For more information, see the React Navigation documentation.

与 Web 一起使用

¥Usage with web

如果你的目标是 Web，请按照 使用 Expo CLI 内置的 Chrome DevTools 中的说明设置 SafeAreaProvider。如果你正在进行服务器端渲染 (SSR)，请参阅库文档中的 Web SSR 部分。

¥If you are targeting the web, set up SafeAreaProvider as described in the usage section. If you are doing server-side rendering (SSR), see the Web SSR section in the library's documentation.