跳到主要內容
版本：6.x

Native 堆疊導航器

Native 堆疊導航器提供途徑讓應用程式在各個畫面間轉換，每個新的畫面都會擺放在堆疊的最上層。

此導航器使用原生 API「iOS 上的 UINAvigationController」及「Android 上的 Fragment」，因此使用 createNativeStackNavigator 建立的導航功能，其行為與使用這些 API 原生打造的應用程式完全相同，且具有相同的效能特性。它也提供支援的基本網路，使用的是 react-native-web。

需要注意的一點是，儘管 @react-navigation/native-stack 提供原生效能及公開原生功能（如 iOS 上的大標題等），它在某些需要客製化的需求上，可能不如 @react-navigation/stack 靈活。因此如果需要廣泛的客製化功能，應該考慮使用 @react-navigation/stack，這是一個可客製化且基於 JavaScript 的實作。

安裝​

要使用此導航器，請確保已具備 @react-navigation/native 及其相依模組（請遵循本指南），接著安裝 @react-navigation/native-stack

npm install @react-navigation/native-stack

API 定義​

💡 如果在使用 createNativeStackNavigator 時遇到任何 Bug，請在 react-native-screens 而不是 react-navigation 存放庫中提出問題！

要使用此導航器，請從 @react-navigation/native-stack 匯入它

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen name="Notifications" component={Notifications} />
      <Stack.Screen name="Profile" component={Profile} />
      <Stack.Screen name="Settings" component={Settings} />
    </Stack.Navigator>
  );
}

Props​

Stack.Navigator 元件接受下列 prop

id​

導覽的選用獨特 ID。這可以用於 navigation.getParent 來參照子導覽中的此導覽。

initialRouteName​

導覽首頁載入時要呈現的路線名稱。

screenOptions​

在導覽器中的畫面預設選項。

Options​

下列 選項 可用於設定導覽中的畫面

title​

可作為 headerTitle 的備註用字串。

headerBackButtonMenuEnabled​

布林值，表示在 iOS >= 14 後按返回按鈕時是否顯示選單。預設為 true。

需要 react-native-screens 版本 >= 3.3.0。

僅支援 iOS。

headerBackVisible​

頁首中是否可看見返回按鈕。在已指定 headerLeft 的情況下，可使用它來顯示返回按鈕。

這不影響堆疊中第一個畫面。

headerBackTitle​

iOS 上返回按鈕使用的標題字串。預設為前一個場景的標題，或如果沒有足夠的空間，就為「返回」。使用 headerBackTitleVisible: false 來隱藏它。

僅支援 iOS。

headerBackTitleVisible​

返回按鈕標題是否可見。

僅支援 iOS。

headerBackTitleStyle​

頁首返回標題的樣式物件。支援的屬性

  • fontFamily
  • fontSize

僅支援 iOS。

headerBackImageSource​

圖片顯示在頁首中，作為返回按鈕的圖示。預設為平台的返回圖示

  • iOS 上的 V 形標誌
  • Android 上的箭頭

headerLargeStyle​

當顯示大型標題時標題的外觀。如果 headerLargeTitle 為 true 且任何可捲動內容的邊緣達標題的對應邊緣時，則會顯示大型標題。

支援的屬性

  • backgroundColor

僅支援 iOS。

headerLargeTitle​

啟用標題的大型標題，於捲動時會縮成一般標題。

若要在捲動時縮小標題，螢幕的內容應包含在可捲動的檢視中，例如 ScrollView 或 FlatList。如果可捲動區域未填滿螢幕，大型標題在捲動時不會縮小。您還需要在 ScrollView、FlatList 中指定 contentInsetAdjustmentBehavior="automatic"。

僅支援 iOS。

headerLargeTitleShadowVisible​

當顯示大型標題時，標題的陰影是否可見。

headerLargeTitleStyle​

標題中的大型標題樣式物件。支援的屬性

  • fontFamily
  • fontSize
  • fontWeight
  • color

僅支援 iOS。

headerShown​

是否顯示標題。預設會顯示標題。將此設定為 false 會隱藏標題。

headerStyle​

標題樣式物件。支援的屬性

  • backgroundColor

headerShadowVisible​

是否隱藏標題上的高度陰影（Android）或底部邊框（iOS）。

headerTransparent​

布林值，指示導覽列是否為半透明。

預設為 false。將此設定為 true 會讓標題變成絕對定位，使標題浮在螢幕上方並與底下的內容重疊，並將背景顏色變更為 transparent，除非在 headerStyle 中有指定。

如果您想呈現半透明標題或模糊背景，這會很有用。

請注意，如果您不希望內容顯示在標題下方，您需要手動在內容中新增頂端邊距。React Navigation 無法自動完成此動作。

如要取得標題的高度，可以使用 HeaderHeightContext 搭配 React Context API 或 useHeaderHeight。

headerBlurEffect​

半透明標題的模糊效果。headerTransparent 選項必須設定為 true，模糊效果才會生效。

支援的值

  • extraLight
  • light
  • dark
  • regular
  • prominent
  • systemUltraThinMaterial
  • systemThinMaterial
  • systemMaterial
  • systemThickMaterial
  • systemChromeMaterial
  • systemUltraThinMaterialLight
  • systemThinMaterialLight
  • systemMaterialLight
  • systemThickMaterialLight
  • systemChromeMaterialLight
  • systemUltraThinMaterialDark
  • systemThinMaterialDark
  • systemMaterialDark
  • systemThickMaterialDark
  • systemChromeMaterialDark

僅支援 iOS。

headerBackground​

作為標題背景顯示的 React 元素回傳函式。可用於使用圖像或漸層等背景。

headerTintColor​

標題色調。變更返回按鈕和標題的顏色。

headerLeft​

於標題左側顯示的 React Element 回傳函式。會取代返回按鈕。請參閱 headerBackVisible，讓返回按鈕在左側元素旁邊顯示。

headerRight​

於標題右側顯示的 React Element 回傳函式。

headerTitle​

標題使用的字串或回傳 React Element 的函式。預設為 title 或畫面的名稱。

傳遞函式時，函式會在選項物件中接收 tintColor 和 children 作為引數。標題字串傳遞時會使用 children。

請注意，傳遞函式顯示自訂元素時，標題的動畫效果將無法運作。

headerTitleAlign​

對齊標題的方式。可能的值

  • left
  • center

在 iOS 以外的平台上，預設為 left。

不支援 iOS。iOS 上總是 center，而且無法變更。

headerTitleStyle​

標題的樣式物件。支援的屬性

  • fontFamily
  • fontSize
  • fontWeight
  • color

headerSearchBarOptions​

在 iOS 上呈現原生搜尋列的選項。搜尋列很少是靜態的，所以通常是透過傳遞物件到元件主體中的 headerSearchBarOptions 導覽選項來控制它。您還需要在您的 ScrollView、FlatList 等中指定 contentInsetAdjustmentBehavior="automatic"。如果您沒有 ScrollView，請指定 headerTransparent: false。

僅支援 iOS 和 Android。

範例

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      // search bar options
    },
  });
}, [navigation]);

已下描述支援的屬性。

autoCapitalize​

控制是否自動將使用者輸入的文字自動大寫。可能的數值

  • none
  • words
  • sentences
  • characters

預設為 sentences。

autoFocus​

顯示搜尋列時是否自動對焦。預設為 false。

僅支援 Android。

barTintColor​

搜尋欄位背景顏色。預設欄位淡色為半透明的。

僅支援 iOS。

tintColor​

游標插入符號和取消按鈕文字的顏色。

僅支援 iOS。

cancelButtonText​

用來取代預設 取消 按鈕文字的文字。

僅支援 iOS。

disableBackButtonOverride​

返回按鈕是否關閉搜尋列的文字輸入。預設為 false。

僅支援 Android。

hideNavigationBar​

布林值，表示在搜尋時是否隱藏導覽列。預設為 true。

僅支援 iOS。

hideWhenScrolling​

布林值，表示捲動時是否隱藏搜尋列。預設為 true。

僅支援 iOS。

inputType​

輸入類型。預設為 "text"。

支援的值

  • "text"
  • "phone"
  • "number"
  • "email"

僅支援 Android。

obscureBackground​

布林值，表示是否以半透明覆蓋隱藏底層內容。預設為 true。

placeholder​

當搜尋欄位為空白時顯示的文字。

textColor​

搜尋欄位中文字的顏色。

hintTextColor​

搜尋欄位中提示文字的顏色。

僅支援 Android。

headerIconColor​

顯示於標題中的搜尋和關閉圖示的顏色

僅支援 Android。

shouldShowHintSearchIcon​

在搜尋欄位取得焦點時顯示搜尋提示的圖示。預設為 true。

僅支援 Android。

onBlur​

在搜尋欄位失去焦點時呼叫的回呼函式。

onCancelButtonPress​

在按下取消按鈕時呼叫的回呼函式。

onChangeText​

在文字變更時呼叫的回呼函式。會接收搜尋欄位的目前文字值。

範例

const [search, setSearch] = React.useState('');

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      onChangeText: (event) => setSearch(event.nativeEvent.text),
    },
  });
}, [navigation]);

自訂標題，取代預設標題使用。

這會接受一個函式，傳回一個 React 元件做為標題顯示。這個函式會接收一個物件，包含以下屬性，作為引數

  • navigation - 目前畫面導覽的物件。
  • route - 目前畫面路線的物件。
  • options - 目前畫面選項
  • back - 返回按鈕選項，包含一個物件，其 title 屬性用於將返回按鈕標籤。

範例

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

// ..

header: ({ navigation, route, options, back }) => {
  const title = getHeaderTitle(options, route.name);

  return (
    <MyHeader
      title={title}
      leftButton={
        back ? <MyBackButton onPress={navigation.goBack} /> : undefined
      }
      style={options.headerStyle}
    />
  );
};

若要為導覽器中所有畫面設定自訂標題，可以在導覽器的 screenOptions 屬性中指定這個選項。

請注意，如果你指定了自訂標題，本機功能（如大標題、搜尋欄位等）將無法使用。

statusBarAnimation​

設定狀態欄動畫（與 StatusBar 元件類似）。預設為 iOS 的 fade 和 Android 的 none。

支援的值

  • "fade"
  • "none"
  • "slide"

在 Android 上，設定 fade 或 slide 將設定狀態列顏色的轉場動畫。在 iOS 上，此選項套用至狀態列的外觀動畫。

需要在 Info.plist 檔案中設定 基於檢視控制器的狀態列外觀 -> 是 (YES)（或移除此設定檔）。

僅支援 Android 和 iOS。

statusBarHidden​

此畫面上的狀態列是否應隱藏。

需要在 Info.plist 檔案中設定 基於檢視控制器的狀態列外觀 -> 是 (YES)（或移除此設定檔）。

僅支援 Android 和 iOS。

statusBarStyle​

設定狀態列顏色（類似於 StatusBar 元件）。預設為 auto。

支援的值

  • "auto"
  • "inverted"（僅限 iOS）
  • "dark"
  • "light"

需要在 Info.plist 檔案中設定 基於檢視控制器的狀態列外觀 -> 是 (YES)（或移除此設定檔）。

僅支援 Android 和 iOS。

statusBarColor​

設定狀態列顏色（類似於 StatusBar 元件）。預設為狀態列初始顏色。

僅支援 Android。

statusBarTranslucent​

設定狀態列的半透明度（類似於 StatusBar 元件）。預設為 false。

僅支援 Android。

contentStyle​

場景內容的樣式物件。

customAnimationOnGesture​

否手勢應使用提供給 animation 屬性的動畫來關閉。預設為 false。

不會影響以模態顯示的畫面的行為。

僅支援 iOS。

fullScreenGestureEnabled​

是否應於全螢幕上使用此手勢來關閉。使用此選項以手勢關閉將產生與 simple_push 相同的轉場動畫。此行為可透過設定 customAnimationOnGesture 屬性來變更。由於平台限制，無法使用 iOS 的預設動畫。預設為 false。

不會影響以模態顯示的畫面的行為。

僅支援 iOS。

gestureEnabled​

否您可以使用手勢關閉此畫面。預設為 true。僅限 iOS 支援。

animationTypeForReplace​

當此畫面取代另一畫面時所使用的動畫類型。預設為 pop。

支援的值

  • push：新畫面將執行推動畫。p>
  • pop：新畫面將執行反推動畫。

動畫​

推動或彈出時螢幕應執行的動畫效果。

支援的值

  • 預設：使用平台預設動畫
  • 淡入淡出：淡入或淡出螢幕
  • 從底部淡入：從底部淡入新螢幕
  • 翻轉：翻轉螢幕，需要 呈現：modal（僅限 iOS）
  • 簡單推入：預設動畫，但沒有陰影和原生標題轉場（僅限 iOS，Android 上使用預設動畫）
  • 從底部滑入：從底部滑入新螢幕
  • 從右側滑入：從右側滑入新螢幕（僅限 Android，iOS 上使用預設動畫）
  • 從左側滑入：從左側滑入新螢幕（僅限 Android，iOS 上使用預設動畫）
  • 無：不執行螢幕動畫

僅支援 Android 和 iOS。

呈現​

螢幕的呈現方式。

支援的值

  • 卡片：新螢幕將推入堆疊，這表示預設動畫將在 iOS 上從側邊滑入，Android 上的動畫則會根據作業系統版本和主題而有所不同。
  • modal：新螢幕將以 modal 方式呈現，這也允許在螢幕中呈現巢狀堆疊。
  • 透明 modal：新螢幕將以 modal 方式呈現，但此外，前一個螢幕將保留，以便在螢幕有半透明背景時仍可看到下方的內容。
  • isContainedModal：在 iOS 上將使用「UIModalPresentationCurrentContext」modal 樣式，而後備機制為「modal」（Android）。
  • isContainedTransparentModal：在 iOS 上將使用「UIModalPresentationOverCurrentContext」modal 樣式，而後備機制為「transparentModal」（Android）。
  • 全螢幕 modal：在 iOS 上將使用「UIModalPresentationFullScreen」modal 樣式，而後備機制為「modal」（Android）。使用此呈現樣式的螢幕無法透過手勢關閉。
  • 表單紙張：在 iOS 上將使用「UIModalPresentationFormSheet」modal 樣式，而後備機制為「modal」（Android）。

僅支援 Android 和 iOS。

方向​

螢幕要使用的顯示方向。

支援的值

  • 預設 - 解析為「全部」，但在 iOS 上沒有「從上往下直向」。在 Android 上，這讓系統決定最佳方向。
  • 全部：允許所有方向。
  • 直向：允許直向方向。
  • 從上往下直向：允許右側直向方向。
  • 從上往下直向：允許倒置直向方向。
  • 橫向：允許橫向方向。
  • 橫向向左：允許向左橫向方向。
  • 橫向向右：允許向右橫向方向。

僅支援 Android 和 iOS。

自動隱藏home指示器​

指示首頁指標是否較傾向隱藏的布林值。預設為 false。

僅支援 iOS。

手勢方向​

設定輕掃以關閉螢幕時應採用的方向。

支援的值

  • 垂直 – 垂直關閉螢幕
  • 水平 – 水平關閉螢幕 (預設值)

使用 垂直 選項時，將預設設定選項 fullScreenGestureEnabled: true、customAnimationOnGesture: true 和 animation: 'slide_from_bottom'。

僅支援 iOS。

動畫持續時間​

變更 iOS 上 slide_from_bottom、fade_from_bottom、fade 和 simple_push 轉場的持續時間 (毫秒)。預設為 350。

預設 和 翻轉 轉場的持續時間不可自訂。

僅支援 iOS。

設定導覽列顏色。預設為初始狀態列顏色。

僅支援 Android。

指示導覽列是否應隱藏的布林值。預設為 false。

僅支援 Android。

失焦時凍結​

指示是否防止非活動螢幕重新渲染的布林值。預設為 false。當應用程式最上方執行 react-native-screens 套件的 enableFreeze() 時，預設值會變為 true。

需要版本 >=3.16.0 的 react-native-screens。

僅支援 iOS 和 Android。

事件​

導覽欄可以在特定動作時傳送事件。支援的事件如下

轉場開始​

目前螢幕的轉場動畫開始時觸發此事件。

事件資料

  • e.data.closing - 指示螢幕是開啟或關閉的布林值。

範例

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionStart', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

轉場結束​

目前螢幕的轉場動畫結束時觸發此事件。

事件資料

  • e.data.closing - 指示螢幕是開啟或關閉的布林值。

範例

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionEnd', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

輔助程式​

原生的堆疊導覽欄加入下列方法至導覽 prop

取代​

在堆疊中使用新螢幕取代目前的螢幕。此方法接受下列引數

  • name - string - 要推入堆疊的路由名稱。
  • params - 物件 - 要傳遞至目標路由的畫面參數。
navigation.replace('Profile', { owner: 'Michaś' });

push​

推送新的畫面到堆疊頂端並導覽至該畫面。該方法接受下列參數

  • name - string - 要推入堆疊的路由名稱。
  • params - 物件 - 要傳遞至目標路由的畫面參數。
navigation.push('Profile', { owner: 'Michaś' });

pop​

從堆疊中彈出目前的畫面並導覽回到前一個畫面。它可以接收一個選用參數 (count)，讓您可以指定要彈出多少個畫面。

navigation.pop();

popToTop​

彈出堆疊中所有畫面，只保留第一個畫面並導覽至該畫面。

navigation.popToTop();

範例​

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator
      initialRouteName="Home"
      screenOptions={{
        headerTintColor: 'white',
        headerStyle: { backgroundColor: 'tomato' },
      }}
    >
      <Stack.Screen
        name="Home"
        component={Home}
        options={{
          title: 'Awesome app',
        }}
      />
      <Stack.Screen
        name="Profile"
        component={Profile}
        options={{
          title: 'My profile',
        }}
      />
      <Stack.Screen
        name="Settings"
        component={Settings}
        options={{
          gestureEnabled: false,
        }}
      />
    </Stack.Navigator>
  );
}