react-native-safe-area-context

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

安装

🌐 Installation

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';

组件

🌐 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 时任何模态或路由的根目录下。

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 并按照 Web SSR 中的描述，将其设置为 provider 的 initialMetrics 属性。如果你的 provider 会重新挂载，或者你正在使用 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,
      }}
    />
  );
}