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

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

react-native-safe-area-context 提供了一个灵活的 API，用于访问设备安全区域插图信息。这使你能够在刘海、状态栏、Home 指示器以及其他类似的设备和操作系统界面元素周围，适当地放置内容。它还提供了一个 SafeAreaView 组件，你可以用它替代 View，从而自动为你的视图添加内边距以适配安全区域。

安装

If you are installing this in an existing React Native app, make sure to install expo in your project. Then, follow the installation instructions provided in the library's README or documentation.

API

import {
  SafeAreaView,
  SafeAreaProvider,
  SafeAreaInsetsContext,
  useSafeAreaInsets,
} from 'react-native-safe-area-context';

组件

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

function SomeComponent() {
  return (
    <SafeAreaView>
      <View />
    </SafeAreaView>
  );
}

Hooks

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

function HookComponent() {
  const insets = useSafeAreaInsets();

  return <View style={{ paddingTop: insets.top }} />;
}

类型

指南

Context

要使用安全区域上下文，你需要在应用根组件中添加 SafeAreaProvider。

你可能也需要在其他地方添加它，包括在使用 react-native-screen 时任何模态框或路由的根部。

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

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

然后，你可以使用 useSafeAreaInsets() Hook，也可以使用消费者 API 来访问插图数据：

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

function Component() {
  return (
    <SafeAreaInsetsContext.Consumer>
      {insets => <View style={{ paddingTop: insets.top }} />}
    </SafeAreaInsetsContext.Consumer>
  );
}

优化

如果可以，使用 SafeAreaView。它是原生实现的，因此在旋转设备时，不会因为异步桥而产生延迟。

为了加快初始渲染，你可以从此包中导入 initialWindowMetrics，并像 Web SSR 中所述那样，将其设置为 provider 的 initialMetrics 属性。如果你的 provider 会重新挂载，或者你正在使用 react-native-navigation，则不能这样做。

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

function App() {
  return <SafeAreaProvider initialMetrics={initialWindowMetrics}>...</SafeAreaProvider>;
}

Web SSR

如果你在 web 上进行服务端渲染，你可以使用 initialSafeAreaInsets 基于用户所使用的设备注入值，或者直接传入零。否则，插图测量会是异步的，从而破坏页面内容的渲染。

从 CSS 迁移

之前

在仅限 web 的应用中，你会使用 CSS 环境变量来获取屏幕安全区域插图的大小。

div {
  padding-top: env(safe-area-inset-top);
  padding-left: env(safe-area-inset-left);
  padding-bottom: env(safe-area-inset-bottom);
  padding-right: env(safe-area-inset-right);
}

之后

通用地说，Hook useSafeAreaInsets() 可以提供对这些信息的访问。

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

function App() {
  const insets = useSafeAreaInsets();
  return (
    <View
      style={{
        paddingTop: insets.top,
        paddingLeft: insets.left,
        paddingBottom: insets.bottom,
        paddingRight: insets.right,
      }}
    />
  );
}