react-native-safe-area-context

一个提供灵活 API 用于访问设备安全区域边距信息的库。

Android

iOS

tvOS

Web

Included in Expo Go

GitHub

npm

Bundled version:

~5.6.2

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

安装

Terminal

- npx expo install react-native-safe-area-context

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

组件

`SafeAreaView`

SafeAreaView 是一个普通的 View 组件，会将安全区域边缘作为内边距应用。

如果你在视图上设置了自己的内边距，它会与安全区域的内边距相加。

如果你的目标平台是 web，你必须按照 Context 部分所述设置 SafeAreaProvider。

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

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

SafeAreaView 属性

`edges`

可选 • 类型: Edge[] • 默认值: ["top", "right", "bottom", "left"]

设置要应用安全区域 insets 的边缘。

`emulateUnlessSupported`

可选 • 类型: boolean • 默认值: true

在 iOS 10+ 上，使用状态栏高度和 Home 指示器尺寸来模拟安全区域。

Hooks

`useSafeAreaInsets()`

该 Hook 可让你直接访问安全区域 insets。这是一个更高级的用例，并且在设备旋转时可能比 SafeAreaView 性能更差。

示例

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

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

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

返回值

EdgeInsets

类型

`Edge`

可能的边缘值的字符串联合类型。

可接受的值为：'top'、'right'、'bottom'、'left'。

`EdgeInsets`

表示该 Hook 的结果。

EdgeInsets 属性

名称	类型	描述
`bottom`	`number`	底部 inset 的值。
`left`	`number`	左侧 inset 的值。
`right`	`number`	右侧 inset 的值。
`top`	`number`	顶部 inset 的值。

指南

Context

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

你可能还需要在其他位置添加它，包括使用 react-native-screen 时每个模态和路由的根部。

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

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

然后，你可以使用 useSafeAreaInsets() Hook，也可以使用 consumer API 来访问 inset 数据：

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 根据用户设备注入相应的值，或者直接传入零。否则，由于 inset 测量是异步的，它会破坏页面内容的渲染。

从 CSS 迁移

之前

在仅 web 的应用中，你会使用 CSS 环境变量来获取屏幕安全区域 insets 的尺寸。

styles.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() 可以提供对此信息的访问。

App.js

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