Elements 函式庫

一個包含 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

元件

標頭

可用來當作標題的元件。這是所有導覽程式預設使用的元件。

用法

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

調整標題的方式。可能的選項

• 左
• 中

在 iOS 上預設為中，在 Android 上預設為左。

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 相同的 props。

用法

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

HeaderTitle

此元件用於在標頭中顯示標題文字。它是 headerTitle 的預設值。它接受與 Text 相同的 props。

標題的色彩預設為 主題文字色彩。您可以使用 tintColor prop 來覆寫它。

用法

<HeaderTitle>Hello</HeaderTitle>

HeaderBackButton

此元件用於在標頭中顯示返回按鈕。它是 堆疊導航器 中 headerLeft 的預設值。它接受下列 props

• disabled - 控制按鈕是否為停用狀態的布林值。
• onPress - 按下按鈕時要呼叫的回呼函數。
• pressColor - 材質漣漪的色彩 (僅 Android >= 5.0)。
• backImage - 回傳 React Element 以在標頭的返回按鈕中顯示自訂圖片的函數。
• 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

此元件會顯示一個遺失圖示符號。它可以用作圖示的替代方案，以表示有一個遺失的圖示。它接受下列 props

• color - 圖示色彩。
• size - 圖示大小。
• style - 圖示的額外樣式。

PlatformPressable

一個組件，可以在 Pressable 基礎上提供抽象，用於處理平台差異。除了 Pressable 的屬性之外，它還接受下列額外屬性

• pressColor - 按下時 Android 上材料漣漪的顏色
• pressOpacity - 如果平台不支援材料漣漪，則在按下時的透明度

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

掛勾，用於返回父畫面中最近可見標頭的高度。

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

// ...

const headerHeight = useHeaderHeight();

getDefaultHeaderHeight

輔助程式，用於返回預設標頭高度。需要下列參數

• layout - 畫面的配置，即包含 height 和 width 屬性的物件。
• statusBarHeight - 狀態列高度

getHeaderTitle

協助程式在標題中傳回要使用的文字。它採取下列參數

• 選項 - 螢幕的選項物件。
• 後備 - 如果在選項中找不到標題要使用的後備標題字串。