react-native-safe-area-context

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

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 }} />;
}

类型

指南

Context

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

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

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

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

然后，你可以使用 useSafeAreaInsets() hook，也可以使用 consumer 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,
      }}
    />
  );
}