SafeAreaContext

具有灵活 API 的库，用于访问设备的安全区域插入信息。

该库在 Expo SDK 参考中列出，因为它包含在 Expo 中。你可以将你选择的任何库与 开发构建 一起使用。

react-native-safe-area-context 提供了灵活的 API 用于访问设备安全区域插入信息。这使你可以将内容适当地放置在缺口、状态栏、主页指示器以及其他此类设备和操作系统界面元素周围。它还提供了一个 SafeAreaView 组件，你可以使用它来代替 View，以自动插入视图以考虑安全区域。

¥react-native-safe-area-context provides a flexible API for accessing device safe area inset information. This allows you to position your content appropriately around notches, status bars, home indicators, and other such device and operating system interface elements. It also provides a SafeAreaView component that you can use in place of View to automatically inset your views to account for safe areas.

安装

¥Installation

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

API

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

组件

¥Components

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

类型

¥Types

指南

¥Guides

上下文

¥Context

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

¥To use safe area context, you need to add SafeAreaProvider in your app root component.

你可能还需要将其添加到其他位置，包括使用 react-native-screen 时在任何模式的根部或任何路由。

¥You may need to add it in other places too, including at the root of any modals any routes when using react-native-screen.

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

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

然后，你可以使用 useSafeAreaInsets() 钩子和消费者 API 来访问插入数据：

¥Then, you can use useSafeAreaInsets() hook and also consumer API to access inset data:

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

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

优化

¥Optimization

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

¥If you can, use SafeAreaView. It's implemented natively so when rotating the device, there is no delay from the asynchronous bridge.

为了加速初始渲染，你可以从此包导入 initialWindowMetrics 并设置为提供程序上的 initialMetrics 属性，如 Web SSR 中所述。如果你的提供商重新安装，或者你正在使用 react-native-navigation，则无法执行此操作。

¥To speed up the initial render, you can import initialWindowMetrics from this package and set as the initialMetrics prop on the provider as described in Web SSR. You cannot do this if your provider remounts, or you are using react-native-navigation.

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

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

网络服务端渲染

¥Web SSR

如果你在网络上进行服务器端渲染，则可以使用 initialSafeAreaInsets 根据用户拥有的设备注入值，或者直接传递零。否则，插图测量将破坏页面内容的渲染，因为它是异步的。

¥If you are doing server side rendering on the web, you can use initialSafeAreaInsets to inject values based on the device the user has, or simply pass zero. Otherwise, insets measurement will break rendering your page content since it is async.

从 CSS 迁移

¥Migrating from CSS

之前

¥Before

在纯 Web 应用中，你可以使用 CSS 环境变量来获取屏幕安全区域插图的大小。

¥In a web-only app, you would use CSS environment variables to get the size of the screen's safe area insets.

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

之后

¥After

一般来说，钩子 useSafeAreaInsets() 可以提供对此信息的访问。

¥Universally, the hook useSafeAreaInsets() can provide access to this information.

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