安全区域

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

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

创建安全区域可确保应用屏幕的内容被正确定位。这意味着它不会被刘海、状态栏、主屏幕指示器以及设备物理硬件或操作系统控制的其他界面元素遮挡。当内容被遮挡时，它会被这些界面元素覆盖。

下面是一个应用屏幕内容在 Android 上被状态栏遮挡的示例。在 iOS 上，相同的内容会被圆角、刘海和状态栏遮挡。

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

react-native-safe-area-context 为处理 Android 和 iOS 设备的安全区域边距提供了一个灵活的 API。它还提供了一个 SafeAreaView 组件，你可以用它来替代 <View>，从而在屏幕组件中自动适配安全区域。

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

安装

如果你使用了默认模板创建项目，则可以跳过安装 react-native-safe-area-context。该库作为 Expo Router 库的 peer dependency 已经安装。否则，请运行以下命令进行安装：

用法

你可以直接使用 SafeAreaView 来包裹屏幕组件的内容。它本质上是一个普通的 <View>，会将安全区域边距作为额外的 padding 或 margin 应用进去。

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

export default function HomeScreen() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Text>内容位于安全区域内。</Text>
    </SafeAreaView>
  );
}

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

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

另一种方式：useSafeAreaInsets 钩子

除了 SafeAreaView 之外，你还可以在屏幕组件中使用 useSafeAreaInsets 钩子。它可以直接访问安全区域边距，让你使用该钩子的 inset 为 <View> 的每个边应用 padding。

下面的示例使用了 useSafeAreaInsets 钩子。它通过 insets.top 为 <View> 应用顶部 padding。

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>内容位于安全区域内。</Text>
    </View>
  );
}

该钩子会以以下对象提供边距：

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

其他信息

最小示例

下面是一个最小可运行示例，它使用 useSafeAreaInsets 钩子为视图应用顶部 padding。

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 }}>内容位于安全区域内。</Text>
    </View>
  );
}

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

与 React Navigation 一起使用

默认情况下，React Navigation 支持安全区域，并将 react-native-safe-area-context 作为 peer dependency 使用。有关更多信息，请参阅 React Navigation 文档。

与 web 一起使用

如果你的目标平台是 web，请按照用法部分所述设置 SafeAreaProvider。如果你正在进行服务端渲染（SSR），请参阅该库文档中的 Web SSR 部分。