Blog

Navigation in React Native mit TypeScript strukturieren

24. September 2022 8 Min. Lesezeit

React Navigation v6 mit TypeScript meistern. Lerne typsichere Navigation, die Übergabe von Parametern und fortgeschrittene Navigations-Patterns in React-Native-Apps.

Navigation in React Native mit TypeScript strukturieren
React NativeTypeScriptNavigationReact Navigation

Die Typisierung voll ausnutzen: React Navigation

Navigation ist heute ein grundlegendes Feature jeder mobilen Anwendung. In der Welt von React Native haben wir dafür React Navigation in der Tasche.

Dieser Artikel zeigt, wie man eine typische React Navigation mit TypeScript umsetzen kann, und vergleicht dabei verschiedene Strategien für den Einsatz von TypeScript.

Noch wichtiger: Er zeigt auch, wie wir das Beste aus den Features von TypeScript herausholen, um eine besser skalierbare Architektur für die Navigation zu bauen.

Hinweis: Die Beispiele in diesem Artikel basieren auf der Version @react-navigation@6.x.

Hinweis: Die Methoden und Strategien in diesem Artikel sind keine unverzichtbaren Regeln, denen du strikt folgen musst. Sie sind einfach meine Vorlieben, und ich fand sie nützlich genug, um sie mit den Lesern dieses Artikels zu teilen. React Navigation hat bereits einen großartigen, gut dokumentierten Abschnitt zur Nutzung von TypeScript. Du kannst also schon eine tolle TypeScript-Struktur für react-navigation bauen, indem du einfach dieser Dokumentation folgst.

Einen Stack Navigator erstellen

Schauen wir uns an, wie man mit dem Paket React Navigation einen Stack Navigator erstellt.

Hier ist das Beispiel aus React Navigation:

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

const Stack = createStackNavigator();

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

function AppStack() {
  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>
  );
}

Wie man sieht, ist hier nichts TypeScript-spezifisch. Fügen wir diesem Snippet also ein bisschen TypeScript hinzu.

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  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>
  );
}

Oben haben wir den Typ ParamList für createStackNavigator hinzugefügt. Aber Moment, woher wissen wir, dass createStackNavigator einen generischen Typ annimmt? Es gibt ein paar Wege, das herauszufinden. Es ist immer eine gute Praxis, zuerst die Dokumentation zu lesen. In diesem Beispiel wirst du schon bemerken, dass es in der Dokumentation einen eigenen Abschnitt dazu gibt.

Angenommen, diese spezielle Typisierung von createStackNavigator wäre nicht auf der Website dokumentiert, dann könnte man einfach zur Typdefinition der Funktion springen, um herauszufinden, ob die Funktion diese Typisierung hat. Das kann anfangs einschüchternd sein, weil jede Menge Typen, Interfaces und Generics herumfliegen, aber je mehr du dir angewöhnst, zur Typdefinition zu springen, desto weniger überwältigend wird es.

Update!

Wenn du dich mit zusätzlicher Komplexität in TypeScript herumschlagen und das brillante TS-Utility des React-Teams (React.ComponentProps) ignorieren willst, kannst du bis zum Ende dieses Artikels weiterlesen.

Aber ich fürchte, dieser Abschnitt könnte schon das Ende sein!

Mit React.ComponentProps können wir die Typisierung für jeden Stack Screen und seine Konfiguration abrufen. Und das Ergebnis ist einfach großartig.

Hier ist das vollständige Beispiel:

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

const Stack = createStackNavigator<AppStackParamList>();

const routes: Array<React.ComponentProps<typeof Stack.Screen>> = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

function AppStack() {
  return (
    <Stack.Navigator>
      {routes.map((routeConfig) => (
        <Stack.Screen key={routeConfig.name} {...routeConfig} />
      ))}
    </Stack.Navigator>
  );
}

Und ja, IntelliSense funktioniert weiterhin, und du wirst weiterhin gewarnt, wenn du einen nicht dazugehörigen* (also z. B. einen Screen, der nicht in deiner Stack-Typdeklaration steht)* Screen in deinen Stack packst, etwa so:

Ungültiger ScreenUngültiger Screen

Auch IntelliSense ist da:

Außerdem ist es sauberer, besser konfigurierbar und dynamischer:

const getAuthStackRoutes = (
  // other parameters...
  theme: ThemeType
): Array<React.ComponentProps<typeof Stack.Screen>> => {
  // more business logic...

  return [
    {
      name: "Home",
      component: Home,
      options: {
        headerStyle: {
          backgroundColor: theme.colors.primary,
          // other theme stylings...
        },
      },
    },
  ];
};

Zusammengefasst können wir mit diesem Ansatz komplexe Navigationsstrukturen leicht verwalten (zumindest im Vergleich mit den anderen Ansätzen in diesem Artikel). Denn du bekommst nicht nur saubereres JSX, sondern kannst deine Routen auch dynamischer und modularer konfigurieren.

TypeScript noch einen Schritt weiter nutzen

Es beschränkt sich tatsächlich nicht darauf, nur den generischen Typ von createStackNavigator zu deklarieren. Wie sieht es mit dem Typ der Child-Elemente aus, die Stack.Navigator haben wird? Obwohl dieses Konzept in der offiziellen Dokumentation bereits ziemlich gut beschrieben ist, schauen wir uns unten an, wie wir damit spielen können, um die Struktur entkoppelter aufzubauen.

import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
  createStackNavigator,
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

// stack param list type
type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

// strictly typed array of app stack routes
const appStackRoutes: Array<AppStackRoutesType> = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  return (
    <Stack.Navigator>
      {/** mapping the app stack routes */}
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Hoppla, hier passiert eine Menge... Teilen wir den Code in einzelne Abschnitte auf.

import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
  createStackNavigator,
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

Ganz oben im Snippet importieren wir die nötigen Module. Dazu gehören Typen, Funktionen und andere nötige Dinge. Nicht spannend, aber nötig :)

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

Oben importieren wir die Komponente View aus react-native, damit sich das Beispiel einfacher zeigen lässt.

// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

Jetzt kommt der interessante Teil. RouteConfig, importiert aus @react-navigation/core, nimmt genau fünf Typen als generischen Typ. Diese spezielle Typdefinition ist auf der offiziellen Website von react-navigation nicht dokumentiert, aber du kannst sie trotzdem herausfinden, indem du wie oben beschrieben einfach zur Typdefinition springst.

Auch wenn es in einem typischen React-Native-Projekt mit TypeScript überflüssig oder unnötig wirken mag, bringt es einige Vorteile, die im folgenden Abschnitt behandelt werden.

IntelliSense

Da wir jetzt ein streng typisiertes Array mit Stack-Routen (also App-Routen) haben, muss sich jedes Element des Arrays an dessen Typdefinition halten. Das heißt, IntelliSense funktioniert direkt, wenn man dem Array ein neues Element hinzufügt.

Außerdem zwingt uns dieser Typ dazu, AppStackRoutesType* jedes Mal zu aktualisieren, wenn den App-Routen ein neues Element hinzugefügt werden soll. Sonst könnten wir kein neues Element hinzufügen, das in AppStackRoutesType (AppStackParamList) nicht existiert.*

Die Routen mappen

Jetzt kommt der letzte Teil: Wir erstellen den Stack Navigator mit createStackNavigator. Dann ist es nur noch eine Frage des Mappens über das Array, das wir oben mit seinem strikten Typ erstellt haben.

Wir können uns schließlich auf jedes Element unseres Arrays verlassen, es hat korrekt typisierte Elemente, also ist es sicher, die Spread-Syntax zu verwenden.

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  return (
    <Stack.Navigator>
      {/** mapping the app stack routes */}
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

War das wirklich der letzte Teil?

Na ja... Nein!

Wir können die Typisierung im behandelten Beispiel noch verbessern.

// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
  RouteConfig<
    ParamList,
    keyof ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >
>;

type AppStackRoutesType = StackRoutesType<AppStackParamList>;

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

// strictly typed array of app stack routes
const appStackRoutes: AppStackRoutesType = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

Der Unterschied, der dir vielleicht aufgefallen ist: Wir haben jetzt StackRoutesType, das einen generischen Typ annimmt und dem Typ entspricht, den wir schon gesehen haben. Aber was ist hier der Vorteil, fragst du vielleicht. Diese Frage beantwortet man am besten visuell.

// too much duplicated code...

type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

type OtherStackRoutesType = RouteConfig<
  OtherStackParamList,
  keyof OtherStackParamList,
  StackNavigationState<OtherStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

type AnotherStackRoutesType = RouteConfig<
  AnotherStackParamList,
  keyof AnotherStackParamList,
  StackNavigationState<AnotherStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

Würden wir den generischen StackRoutesType nicht verwenden, müssten wir die Typisierung für jeden Stack in der App duplizieren.

Das wäre ein Albtraum, je größer die App wird. (Die Idee hier: Die Anzahl der Stacks in der App und die Komplexität der App sind direkt proportional. Das ist zwar nicht immer zu 100 % zutreffend, passt aber für dieses Beispiel)

// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
  RouteConfig<
    ParamList,
    keyof ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >
>;

// becomes one line typings for each stack
type AppStackRoutesType = StackRoutesType<AppStackParamList>;
type OtherStackRoutesType = StackRoutesType<OtherStackParamList>;
type AnotherStackRoutesType = StackRoutesType<AnotherStackParamList>;

Sieh dir dagegen oben an, wie viel einfacher und sauberer es mit dem generischen Typ wird.

Das aktuelle Bild

Vergleichen wir, wie eine typische Stack-Funktion in zwei verschiedenen Szenarien aussehen würde:

Bild 1: Alle Stack Screens einzeln in JSX rendern.

// ...imports, components

function AppStack() {
  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} />
      {/** n more screens... */}
    </Stack.Navigator>
  );
}

Bild 2: Screens über das Array mit Stack-Routen rendern, das mit strikt typisiertem TypeScript erstellt wurde. 🎉

function AppStack() {
  return (
    <Stack.Navigator>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Noch eine Sache... Was ist mit den Navigator-Props?

Eine Sache bleibt vielleicht noch zu bedenken, nämlich die Props des Stack Navigators. Wenn man sich den StackNavigator unten ansieht, gibt es für einen einzelnen Navigator einen ganzen Haufen Konfiguration. Warum diese Konfiguration nicht vom JSX entkoppeln?

import type {
  DefaultNavigatorOptions,
  ParamListBase,
  StackNavigationState,
} from "@react-navigation/core";
import {
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
// other necessary imports for screens...

// generic typing for stack navigator options
type StackNavigatorOptions<ParamList extends ParamListBase> =
  DefaultNavigatorOptions<
    ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >;

// omit the children as it corresponds to stack screen
const appStackNavigatorProps: Omit<
  StackNavigatorOptions<AppStackParamList>,
  "children"
> = {
  initialRouteName: "Home",
  screenOptions: {
    headerShown: false,
    cardOverlayEnabled: true,
    gestureEnabled: false,
    cardStyle: {
      backgroundColor: "royalblue",
    },
    headerLeftContainerStyle: {
      backgroundColor: "firebrick",
    },
    presentation: "modal",
    headerTitleStyle: {
      fontSize: 24,
      color: "olivedrab",
    },
  },
  // ...rest
};

// screen components and stack routes...

function AppStack() {
  return (
    <Stack.Navigator {...appStackNavigatorProps}>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Ab Zeile 13 sollte uns schon vertraut sein, warum wir einen generischen Typ verwenden. Der einzige Unterschied zur Typisierung der Stack-Routen ist vielleicht der Typ DefaultNavigatorOptions, der aus @react-navigation/core importiert wird. Der Name des Typs erklärt sich schon selbst: Es sind die Optionen für den Navigator.

Ähnlich wie der Typ RouteConfig, den wir oben erwähnt haben, nimmt auch dieser mehrere generische Typen an. Beachte außerdem, dass wir den Key children explizit weglassen (Omit), da wir die Children von Stack.Navigator, die Stack.Screen entsprechen, bereits rendern.

In Zeile 22 erstellen wir ein brandneues Objekt (oder es kann auch eine Funktion sein, solange sie ein Objekt zurückgibt, das den Typ der Navigator-Optionen erfüllt), das die Optionen unseres Navigators repräsentiert.

Dadurch kann dieses Objekt in Zeile 50 sicher mit der Spread-Syntax verwendet werden, solange es den gegebenen Typ erfüllt.

Viel saubereres JSX... meiner Meinung nach...

Das aktuelle Bild: Navigator-Props

Vergleichen wir noch einmal, wie eine typische Stack-Funktion in zwei verschiedenen Szenarien aussehen würde:

Bild 1: Die Konfiguration des Stack Navigators steht im JSX.

function AppStack() {
  return (
    <Stack.Navigator
      initialRouteName="Home"
      screenOptions={{
        headerShown: false,
        cardOverlayEnabled: true,
        gestureEnabled: false,
        cardStyle: {
          backgroundColor: "royalblue",
        },
        headerLeftContainerStyle: {
          backgroundColor: "firebrick",
        },
        presentation: "modal",
        headerTitleStyle: {
          fontSize: 24,
          color: "olivedrab",
        },
      }}
      // rest...
    >
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Bild 2: Die Konfiguration des Stack Navigators ist vom JSX entkoppelt.

// ...

function AppStack() {
  return (
    <Stack.Navigator {...appStackNavigatorProps}>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Fazit

In diesem Artikel haben wir gesehen, wie wir TypeScript tatsächlich nutzen und unsere React-Native-Navigatoren sauberer strukturieren können.

Ich wünsche allen einen bugfreien Tag.

Veröffentlicht auf

Dieser Artikel ist auch erschienen auf: