元素库

一个包含 React Navigation 中使用的 UI 元素和辅助工具的组件库。如果您正在构建自己的导航器，或者想要在您的应用程序中重用默认功能，它会很有用。

安装

要使用此包，请确保您已安装 @react-navigation/native 及其依赖项（请遵循本指南），然后安装 @react-navigation/elements

npm

npm install @react-navigation/elements

Yarn

yarn add @react-navigation/elements

pnpm

pnpm add @react-navigation/elements

组件

Header

一个可以用作标题的组件。默认情况下，所有导航器都会使用它。

用法

import { Header } from '@react-navigation/elements';

function MyHeader() {
  return <Header title="My app" />;
}

要在导航器中使用标题，您可以在屏幕选项中使用 header 选项

import { Header, getHeaderTitle } from '@react-navigation/elements';

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator
      screenOptions={{
        header: ({ options, route }) => (
          <Header {...options} title={getHeaderTitle(options, route.name)} />
        ),
      }}
    >
      <Stack.Screen name="Home" component={HomeScreen} />
    </Stack.Navigator>
  );
}

注意

这不会复制堆栈和原生堆栈导航器中标题的行为，因为堆栈导航器还包括动画，而原生堆栈导航器标题由原生平台提供。

它接受以下道具

headerTitle

用于标题的字符串或返回 React 元素的函数。默认值为场景的 title。当指定函数时，它会接收一个包含 allowFontScaling、tintColor、style 和 children 属性的对象。children 属性包含标题字符串。

headerTitleAlign

如何对齐标题。可能的值

• left
• center

在 iOS 上默认为 center，在 Android 上默认为 left。

headerTitleAllowFontScaling

标题字体是否应缩放以尊重文本大小辅助功能设置。默认为 false。

headerLeft

返回 React 元素的函数，该元素显示在标题左侧。您可以使用它来实现自定义左侧按钮，例如

<Stack.Screen
  name="Home"
  component={HomeScreen}
  options={{
    headerLeft: (props) => (
      <MyButton
        {...props}
        onPress={() => {
          // Do something
        }}
      />
    ),
  }}
/>

headerRight

返回 React 元素的函数，该元素显示在标题右侧。

headerShadowVisible

是否隐藏标题上的阴影（Android）或底部边框（iOS）。

这是以下样式的简写

{
  elevation: 0,
  shadowOpacity: 0,
  borderBottomWidth: 0,
}

如果上述样式在 headerStyle 中与 headerShadowVisible: false 一起指定，则 headerShadowVisible: false 将优先。

headerStyle

标题的样式对象。例如，您可以在此处指定自定义背景颜色。

headerTitleStyle

标题组件的样式对象

headerLeftContainerStyle

自定义 headerLeft 组件容器的样式，例如添加填充。

headerRightContainerStyle

自定义headerRight组件容器的样式，例如添加填充。

headerTitleContainerStyle

自定义headerTitle组件容器的样式，例如添加填充。

默认情况下，headerTitleContainerStyle使用绝对定位样式，并偏移left和right。如果使用自定义的headerLeft，这可能会导致headerLeft和headerTitle之间出现空白或重叠。可以通过调整headerTitleContainerStyle中的left和right样式以及headerTitleStyle中的marginHorizontal来解决。

headerBackgroundContainerStyle

headerBackground元素容器的样式对象。

headerTintColor

标题的着色颜色。

headerPressColor

材质波纹的颜色（仅限 Android >= 5.0）

headerPressOpacity

标题中按钮的按下不透明度（Android < 5.0 和 iOS）

headerTransparent

默认为false。如果为true，标题将不会有背景，除非你使用headerBackground显式提供背景。标题也会浮动在屏幕上，以便与下面的内容重叠。

这在你想渲染半透明标题或模糊背景时很有用。

请注意，如果你不希望你的内容出现在标题下方，你需要手动为你的内容添加顶部边距。React Navigation 不会自动执行此操作。

要获取标题的高度，可以使用HeaderHeightContext与React 的 Context API或useHeaderHeight。

headerBackground

返回一个 React 元素的函数，该元素将作为标题的背景渲染。这对于使用图像或渐变等背景很有用。

例如，您可以将它与 headerTransparent 一起使用，以渲染模糊视图以创建半透明标题。

import { BlurView } from 'expo-blur';

// ...

<Stack.Screen
  name="Home"
  component={HomeScreen}
  options={{
    headerTransparent: true,
    headerBackground: () => (
      <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
    ),
  }}
/>;

headerStatusBarHeight

在标题顶部添加的额外填充，以考虑半透明状态栏。默认情况下，它使用设备安全区域内边距的顶部值。传递 0 或自定义值以禁用默认行为，并自定义高度。

HeaderBackground

一个包含标题背景中使用的样式的组件，例如背景颜色和阴影。它是 headerBackground 的默认值。它接受与 View 相同的道具。

用法

<HeaderBackground style={{ backgroundColor: 'tomato' }} />

HeaderTitle

用于在标题中显示标题文本的组件。它是 headerTitle 的默认值。它接受与 Text 相同的道具。

标题的颜色默认为 主题文本颜色。您可以通过传递 tintColor 道具来覆盖它。

用法

<HeaderTitle>Hello</HeaderTitle>

HeaderBackButton

用于显示后退按钮标题的组件。它是 堆栈导航器 中 headerLeft 的默认值。它接受以下道具

• disabled - 布尔值，控制按钮是否禁用。
• onPress - 按下按钮时要调用的回调。
• pressColor - 材料涟漪的颜色（仅限 Android >= 5.0）。
• backImage - 返回 React 元素的函数，以在标题的后退按钮中显示自定义图像。
• tintColor - 标题的色调颜色。
• label - 按钮的标签文本。通常是上一个屏幕的标题。默认情况下，这仅在 iOS 上显示。
• truncatedLabel - 当没有足够的空间显示完整标签时要显示的标签文本。
• labelVisible - 标签文本是否可见。在 iOS 上默认为 true，在 Android 上默认为 false。
• labelStyle - 标签的样式对象。
• allowFontScaling - 标签字体是否应缩放以尊重文本大小辅助功能设置。
• onLabelLayout - 当标签的大小发生变化时触发的回调。
• screenLayout - 屏幕布局。
• titleLayout - 标题元素在头部中的布局。
• canGoBack - 布尔值，指示是否可以返回堆栈。
• accessibilityLabel - 用于屏幕阅读器的按钮的辅助功能标签。
• testID - 在测试中定位此按钮的 ID。
• style - 按钮的样式对象。

用法

<HeaderBackButton label="Hello" onPress={() => console.log('back pressed')} />

MissingIcon

一个渲染缺失图标符号的组件。它可以用作图标的回退，以显示缺少图标。

• color - 图标的颜色。
• size - 图标的大小。
• style - 图标的附加样式。

PlatformPressable

一个组件，它在 Pressable 之上提供抽象，以处理平台差异。除了 Pressable 的属性外，它还接受以下附加属性

• pressColor - Android 上按下时的材质波纹颜色
• pressOpacity - 如果平台不支持材质波纹，则按下时的不透明度

ResourceSavingView

一个组件，通过利用 removeClippedSubviews 来帮助提高非活动屏幕的性能。它接受一个 visible 属性来指示是否应该剪切屏幕。

用法

<ResourceSavingView visible={0}>{/* Content */}</ResourceSavingView>

实用程序

SafeAreaProviderCompat

一个对来自 `react-native-safe-area-context 的 SafeAreaProvider 组件的包装器，其中包含初始值。

用法

<SafeAreaProviderCompat>{/* Your components */}</SafeAreaProviderCompat>

HeaderBackContext

React 上下文，可用于获取父屏幕的返回标题。

import { HeaderBackContext } from '@react-navigation/elements';

// ...

<HeaderBackContext.Consumer>
  {(headerBack) => {
    if (headerBack) {
      const backTitle = headerBack.title;

      /* render something */
    }

    /* render something */
  }}
</HeaderBackContext.Consumer>;

HeaderShownContext

React 上下文，可用于检查父屏幕中是否显示标题。

import { HeaderShownContext } from '@react-navigation/elements';

// ...

<HeaderShownContext.Consumer>
  {(headerShown) => {
    /* render something */
  }}
</HeaderShownContext.Consumer>;

HeaderHeightContext

一个 React 上下文，用于获取父级屏幕中最近可见标题的高度。

import { HeaderHeightContext } from '@react-navigation/elements';

// ...

<HeaderHeightContext.Consumer>
  {(headerHeight) => {
    /* render something */
  }}
</HeaderHeightContext.Consumer>;

useHeaderHeight

返回父级屏幕中最近可见标题高度的 Hook。

import { useHeaderHeight } from '@react-navigation/elements';

// ...

const headerHeight = useHeaderHeight();

getDefaultHeaderHeight

返回默认标题高度的辅助函数。它接受以下参数

• layout - 屏幕布局，即包含 height 和 width 属性的对象。
• statusBarHeight - 状态栏高度

getHeaderTitle

返回标题文本的辅助函数，用于在标题中使用。它接受以下参数

• options - 屏幕的选项对象。
• fallback - 如果在选项中未找到标题，则使用回退标题字符串。