This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

react-native-safe-area-context 提供了灵活的 API，用于访问设备安全区域的内边距信息。这使你可以围绕刘海、状态栏、主屏幕指示器以及其他设备和操作系统界面元素妥善放置内容。它还提供了 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 }} />;
}

类型

指南

上下文

要使用安全区域上下文，需要在应用的根组件中添加 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,
      }}
    />
  );
}