Elements Library

一个包含 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" />;
}

在 Snack 上尝试

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

静态

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

const MyStack = createNativeStackNavigator({
  screenOptions: {
    header: ({ options, route, back }) => (
      <Header
        {...options}
        back={back}
        title={getHeaderTitle(options, route.name)}
      />
    ),
  },
  screens: {
    Home: HomeScreen,
  },
});

在 Snack 上尝试

动态

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

const Stack = createNativeStackNavigator();

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

在 Snack 上尝试

注意

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

它接受以下属性

headerTitle

字符串或返回一个 React 元素的函数，供标题使用。默认为场景 title。

当指定一个函数时，它接收一个包含以下属性的对象

• allowFontScaling：是否缩放以尊重文本大小辅助功能设置。
• tintColor：标题的文本颜色。
• style：Text 组件的样式对象。
• children：标题字符串（来自 options 中的 title）。

静态

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerTitle: ({ allowFontScaling, tintColor, style, children }) => (
          <Text
            style={[style, { color: tintColor }]}
            allowFontScaling={allowFontScaling}
          >
            {children}
          </Text>
        ),
      },
    },
  },
});

动态

<Stack.Screen
  name="Home"
  component={HomeScreen}
  options={{
    headerTitle: ({ allowFontScaling, tintColor, style, children }) => (
      <Text
        style={[style, { color: tintColor }]}
        allowFontScaling={allowFontScaling}
      >
        {children}
      </Text>
    ),
  }}
/>

headerTitleAlign

如何对齐标题。可能的值

• left
• center

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

headerTitleAllowFontScaling

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

headerLeft

返回一个 React 元素以显示在标题左侧的函数。

它接收一个包含以下属性的对象

• tintColor：图标和标签的颜色。
• pressColor：材质波纹的颜色（仅限 Android >= 5.0）。
• pressOpacity：按钮按下时的不透明度（Android < 5.0 和 iOS）。
• displayMode：元素如何显示图标和标题。在 iOS 上默认为 default，在 Android 上默认为 minimal。可能的值
  • default：根据可用空间显示以下内容之一：上一个屏幕的标题、通用标题（例如“返回”）或无标题（仅图标）。
  • generic：根据可用空间显示以下内容之一：通用标题（例如“返回”）或无标题（仅图标）。仅限 iOS >= 14，在较旧的 iOS 版本上回退到“default”。
  • minimal：始终仅显示图标，不显示标题。
• href：在 Web 上按下按钮时要打开的 URL。

您可以使用它来实现您的自定义左侧按钮，例如

静态

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerLeft: (props) => (
          <MyButton {...props} onPress={() => {
            // Do something
          }}>
        )
      }
    }
  }
})

动态

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

headerRight

返回一个 React 元素以显示在标题右侧的函数。

它接收一个包含以下属性的对象

• tintColor：图标和标签的颜色。
• pressColor：材质波纹的颜色（仅限 Android >= 5.0）。
• pressOpacity：按钮按下时的不透明度（Android < 5.0 和 iOS）。

静态

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerLeft: (props) => (
          <MyButton {...props} onPress={() => {
            // Do something
          }}>
        )
      }
    }
  }
})

动态

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

headerSearchBarOptions

标题中搜索栏的选项。当指定此项时，标题将包含一个按钮以显示搜索输入。

它可以包含以下属性

• ref：用于命令式操作搜索输入的 Ref。它包含以下方法
  • focus - 聚焦搜索栏
  • blur - 移除搜索栏的焦点
  • setText - 将搜索栏的内容设置为给定值
  • clearText - 移除搜索栏输入字段中存在的任何文本
  • cancelSearch - 取消搜索并关闭搜索栏
• autoCapitalize：自动大写行为。可能的值：none、words、sentences、characters。
• autoFocus：在挂载时自动聚焦搜索输入。
• cancelButtonText：用于代替默认 Cancel 按钮文本的文本（仅限 iOS）。
• inputType：输入的类型。可能的值：text、phone、number、email。
• onBlur：当搜索输入失去焦点时调用的回调。
• onChangeText：当文本更改时调用的回调。
• onClose：当搜索输入关闭时调用的回调。
• onFocus：当搜索输入获得焦点时调用的回调。
• placeholder：当搜索输入为空时显示的文本。

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      placeholder: 'Search',
      onChangeText: (text) => {
        // Do something
      },
    },
  });
}, [navigation]);

headerShadowVisible

是否隐藏标题上的 elevation 阴影 (Android) 或底部边框 (iOS)。

这是以下样式的简写形式

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

如果在 headerStyle 中指定了上述任何样式以及 headerShadowVisible: false，则 headerStyle 中的样式将优先。

headerStyle

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

{
  backgroundColor: 'tomato',
}

请注意，如果您还使用 headerBackground，则 headerStyle 将不起作用。在这种情况下，您应该改为设置从 headerBackground 返回的元素的样式。

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 一起使用以渲染模糊视图以创建半透明标题。

静态

const Stack = createStackNavigator({
  initialRouteName: 'Home',
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerTransparent: true,
        headerBackground: () => (
          <BlurView
            tint="dark"
            intensity={100}
            style={StyleSheet.absoluteFill}
          />
        ),
      },
    },
    Profile: ProfileScreen,
  },
});

在 Snack 上尝试

动态

import { BlurView } from 'expo-blur';

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

在 Snack 上尝试

headerStatusBarHeight

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

HeaderBackground

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

用法

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

HeaderTitle

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

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

用法

<HeaderTitle>Hello</HeaderTitle>

HeaderButton

一个用于在标题中显示按钮的组件。它可用于左侧和右侧按钮。它接受以下属性

• onPress - 按下按钮时要调用的回调。
• href - 用于 Web 上锚标记的 href。
• disabled - 控制按钮是否禁用的布尔值。
• accessibilityLabel - 屏幕阅读器按钮的辅助功能标签。
• testID - 用于在测试中定位此按钮的 ID。
• tintColor - 标题按钮的着色颜色。
• pressColor - 材质波纹的颜色（仅限 Android >= 5.0）。
• pressOpacity - 如果平台不支持材质波纹，则按钮按下时的不透明度。
• style - 按钮的样式对象。
• children - 为按钮渲染的内容。通常是图标。

用法

<HeaderButton
  accessibilityLabel="More options"
  onPress={() => console.log('button pressed')}
>
  <MaterialCommunityIcons
    name="dots-horizontal-circle-outline"
    size={24}
    color={tintColor}
  />
</HeaderButton>

HeaderBackButton

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

• disabled - 控制按钮是否禁用的布尔值。
• onPress - 按下按钮时要调用的回调。
• pressColor - 材质波纹的颜色（仅限 Android >= 5.0）。
• backImage - 返回一个 React 元素的函数，用于在标题的后退按钮中显示自定义图像。
• tintColor - 标题的着色颜色。
• label - 按钮的标签文本。通常是上一个屏幕的标题。默认情况下，这仅在 iOS 上显示。
• truncatedLabel - 当没有足够的空间容纳完整标签时显示的标签文本。
• displayMode：后退按钮如何显示图标和标题。在 iOS 上默认为 default，在 Android 上默认为 minimal。可能的值
  • default：根据可用空间显示以下内容之一：上一个屏幕的标题、通用标题（例如“返回”）或无标题（仅图标）。
  • generic：根据可用空间显示以下内容之一：通用标题（例如“返回”）或无标题（仅图标）。仅限 iOS >= 14，在较旧的 iOS 版本上回退到“default”。
  • minimal：始终仅显示图标，不显示标题。
• 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 - 如果平台不支持材质波纹，则按下时的不透明度

Button

一个渲染按钮的组件。除了 PlatformPressable 的属性外，它还接受以下附加属性

• variant - 按钮的变体。可能的值为
  • tinted（默认）
  • plain
  • filled
• color - 按钮的颜色。默认为主题的主颜色。
• children - 在按钮内部渲染的内容。

此外，该按钮与 React Navigation 集成，并接受与 useLinkProps hook 相同的属性。

它可以通过指定屏幕名称和参数来用于在屏幕之间导航

<Button screen="Profile" params={{ userId: 'jane' }}>
  Go to Profile
</Button>

或作为常规按钮

<Button onPress={() => console.log('button pressed')}>Press me</Button>

Label

Label 组件用于渲染小文本。它在底部标签导航器中用于渲染每个标签的标签。

除了标准的 Text 属性外，它还接受以下属性

• tintColor - 标签的颜色。默认为主题的文本颜色。

用法

<Label>Home</Label>

ResourceSavingView

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

用法

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

实用工具

SafeAreaProviderCompat

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

用法

<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

Helper，返回默认标题高度。它接受以下参数

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

getHeaderTitle

Helper，返回要在标题中使用的标题文本。它接受以下参数

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