Blog

Formular-Handling in React Native auf dem nächsten Level

28. Juni 2023 10 Min. Lesezeit

Fortgeschrittene Techniken für Formulare in React Native. Lerne mehr über Validierung, Performance-Optimierung und wiederverwendbare Formular-Komponenten.

Formular-Handling in React Native auf dem nächsten Level
React NativeFormulareValidierungPerformanceReact Hook FormZod

Formular-Handling in React Native auf dem nächsten Level

Besseres Formular-Handling in React Native mit Zod und React Hook Form

Formular-Handling ist ein grundlegender Teil jeder Anwendung, die Eingaben von Nutzern braucht, und mit den richtigen Tools und Libraries kann es ein einfacher und reibungsloser Prozess sein. Dieser Artikel zeigt dir, wie du Formulare in einer React-Native-App mit react-hook-form und zod verarbeitest. Durch die Kombination der beiden erreichen wir einen effizienten Mechanismus für Formulare. Bauen wir zur Veranschaulichung ein einfaches Registrierungsformular.

Den vollständigen Quellcode findest du am Ende des Artikels.

Schema-Deklaration mit Zod

Zuerst deklarieren wir unser Schema mit zod. Dieses Schema legt die erwartete Form unserer Formulardaten fest und richtet Validierungen für jedes Feld ein. Zod bietet eine Menge leistungsstarker Validierungsfunktionen, um diese Regeln zu definieren.

Hier ist das vollständige zod-Schema:

Dieser Artikel setzt voraus, dass du die Grundlagen von zod kennst.

import z from "zod";

const phoneNumberRegexp = new RegExp(
  /^[\+]?([0-9][\s]?|[0-9]?)([(][0-9]{3}[)][\s]?|[0-9]{3}[-\s\.]?)[0-9]{3}[-\s\.]?[0-9]{4,6}$/im
);
const FIELD_REQUIRED_STR = "This field is required";
export const GENDER_OPTIONS = ["Male", "Female", "Other"] as const;

export const signUpFormSchema = z.object({
  name: z
    .string({
      invalid_type_error: "Name must be a string",
      required_error: FIELD_REQUIRED_STR,
    })
    .min(3, "Minimum 3 characters")
    .max(20, "Maximum 20 characters")
    .trim(),

  surname: z
    .string({
      invalid_type_error: "Surname must be a string",
      required_error: FIELD_REQUIRED_STR,
    })
    .min(3, "Minimum 3 characters")
    .max(20, "Maximum 20 characters")
    .trim(),

  phoneNumber: z
    .string({
      invalid_type_error: "Phone number must be a number",
      required_error: FIELD_REQUIRED_STR,
    })
    .regex(phoneNumberRegexp, "Invalid phone number"),

  email: z
    .string({
      invalid_type_error: "Email must be a string",
      required_error: FIELD_REQUIRED_STR,
    })
    .email("Email is invalid"),

  gender: z.enum(GENDER_OPTIONS, {
    required_error: FIELD_REQUIRED_STR,
    invalid_type_error: `Invalid gender, must be one of the followings: ${GENDER_OPTIONS.join(
      ", "
    )}`,
  }),

  birthDate: z
    .date({
      invalid_type_error: "Birth date must be a date",
      required_error: FIELD_REQUIRED_STR,
    })
    .min(new Date("1900-01-01"), "Invalid date time, too old")
    .max(new Date("2023-01-01"), "Invalid date time, too young")
    .default(new Date()),
});

export type SignUpFormSchema = z.infer<typeof signUpFormSchema>;

In diesem Schema legen wir mit zod fest, was jedes Feld enthalten soll. Zum Beispiel sollen die Felder name und surname Strings mit 3 bis 20 Zeichen sein, während das Feld phoneNumber eine Zahl sein soll.

Für manche Felder haben wir auch komplexere Regeln. Das Feld email zum Beispiel soll ein String sein und nur gültige E-Mail-Adressen enthalten. Das Feld gender soll eine der vordefinierten Optionen sein ('Male', 'Female' oder 'Other').

Schließlich ist das Feld birthDate vom Typ Datum und soll ein gültiges Datum zwischen 1900-01-01 und 2023-01-01 sein. Wird keines angegeben, nimmt es standardmäßig das aktuelle Datum.

Mit zod lassen sich komplexe Validierungsregeln ganz einfach erstellen. So ist garantiert, dass die Daten aus unserem Formular dem entsprechen, was wir erwarten.

Der nächste Schritt ist, den Typ des Schemas abzuleiten. Zod bietet dafür die Methode infer, die den TypeScript-Typ eines gegebenen zod-Schemas ableitet.

export type SignUpFormSchema = z.infer<typeof signUpFormSchema>;

Dieser abgeleitete Typ wird später in useForm verwendet, damit unsere Formulardaten zu unserem Schema passen.

Formular-Setup mit React Hook Form

Als Nächstes richten wir unser Formular mit dem Hook useForm aus 'react-hook-form' ein. Dieser Hook bekommt unser zod-Schema (über zodResolver) als Argument, um die Formularvalidierung aufzulösen.

const methods = useForm<SignUpFormSchema>({
  resolver: zodResolver(signUpFormSchema),
  defaultValues: {
    birthDate: new Date(),
  },
  mode: "onBlur",
});

Beim resolver übergeben wir unser Schema. Mit der Eigenschaft defaultValues können wir Standardwerte für Formularfelder festlegen. In diesem Fall setzen wir das Standard-birthDate auf das aktuelle Datum. Die Eigenschaft mode bestimmt, wann die Validierung stattfinden soll. Hier passiert sie onBlur, also wenn der Nutzer ein Feld verlässt.

Felder rendern und validieren

Wir nutzen die Komponente Controller aus react-hook-form, um jedes Formularfeld zu verwalten. Sie liefert uns die Props field und fieldState, mit denen wir den Wert, den Fehlerzustand und die Validierung unseres Feldes steuern.

So richten wir zum Beispiel das Feld name ein:

<Controller
  control={methods.control}
  name="name"
  render={({ field: { onChange, onBlur, value }, fieldState: { error } }) => {
    return (
      <TextInput
        label="Name"
        onBlur={onBlur}
        value={value}
        onChangeText={onChange}
        errorMessage={error?.message}
      />
    );
  }}
/>

Das macht jedes Prop:

  • control: Hier übergibst du das Prop control aus dem Hook useForm. Es ist nötig, damit der Controller mit dem State des Formulars interagieren kann.

  • name: Das ist der Key, über den auf den Wert des Inputs im Formular zugegriffen wird. Wenn du Formularwerte abrufst oder setzt, wird dieser Key verwendet. Er muss über alle Formularfelder hinweg eindeutig sein.

  • render: Eine Funktion, die dein Input-Element zurückgibt. Die Funktion stellt die Props field und fieldState bereit.

  • field: Enthält die Props onChange, onBlur und value. Diese sollten direkt mit deiner kontrollierten Komponente verbunden werden. In diesem Fall ist onChange mit onChangeText von TextInput verbunden, das die Eingabe des Nutzers erfasst und im State des Formulars speichert.

  • fieldState: Enthält das Prop error, das Informationen über Validierungsfehler dieses Feldes liefert.

Innerhalb des Props render wird der TextInput angepasst. onBlur und onChangeText werden mit den entsprechenden Methoden aus field verbunden, und das Prop value ist mit dem aktuellen Formularwert dieses Inputs verknüpft. Das Prop errorMessage ist mit der Fehlermeldung verbunden, falls die Validierung fehlschlägt.

Wenn das Feld 'name' also beim Absenden des Formulars oder bei der Echtzeit-Validierung die im Zod-Schema definierten Anforderungen nicht erfüllt, wird die Fehlermeldung in diesem TextInput angezeigt.

Validierung mit React Hook Form gezielt auslösen

Ein besonderer Fall entsteht beim Feld birthDate, das eine Datumsauswahl-Komponente nutzt (in diesem Fall RNDateTimePicker). Hier braucht die Validierung eine Sonderbehandlung, weil sich die Interaktion mit einem Date Picker von typischen Texteingaben unterscheidet.

<Controller
  control={methods.control}
  name="birthDate"
  render={({ field: { onChange, onBlur, value }, fieldState: { error } }) => {
    return (
      <View>
        <Text>Birth date</Text>
        <RNDateTimePicker
          value={value}
          mode="date"
          onChange={(e) => {
            if (e.type === "set" && e.nativeEvent.timestamp) {
              onChange(new Date(e.nativeEvent.timestamp));
              methods.trigger("birthDate");
            }
          }}
        />
        {!!error?.message && <Text>{error.message}</Text>}
      </View>
    );
  }}
/>

Wenn der Nutzer ein Datum auswählt, wird das Event onChange ausgelöst. In diesem Event-Handler prüfen wir zuerst, ob der Event-Typ 'set' ist, was bedeutet, dass der Nutzer ein Datum gesetzt hat. Danach prüfen wir, ob ein Timestamp vorhanden ist, um sicherzugehen, dass ein Datum ausgewählt wurde.

Wenn diese Bedingungen erfüllt sind, wandeln wir den Timestamp mit new Date(e.nativeEvent.timestamp) in ein JavaScript-Date-Objekt um. Dann wird dieser neue Wert an onChange übergeben, das den Wert des Feldes birthDate im Formular aktualisiert.

Anders als typische Texteingaben, die bei Änderungen automatisch eine Validierung auslösen, tun Date Picker das nicht auf dieselbe Weise. Deshalb müssen wir die Validierung nach dem Aktualisieren des Werts manuell auslösen. Das erreichen wir, indem wir methods.trigger('birthDate') aufrufen.

Die Methode trigger von react-hook-form startet die Validierung für ein bestimmtes Feld. Hier löst sie die Validierung für das Feld birthDate aus, sobald das Datum gesetzt ist, sodass unsere Validierungsregeln sofort angewendet werden.

Gibt es Validierungsfehler, werden sie schließlich über {!!error?.message && {error.message}} angezeigt, wobei error?.message die Fehlermeldung enthält, wie sie in unserem zod-Schema definiert ist.

Formular absenden mit React Hook Form

Das Paket react-hook-form bietet effiziente Methoden, um das Absenden von Formularen und die Fehlerbehandlung abzuwickeln.

const onSubmit: SubmitHandler<SignUpFormSchema> = (data) => {
  console.log(JSON.stringify(data));
};

const onError: SubmitErrorHandler<SignUpFormSchema> = (errors, e) => {
  console.log(JSON.stringify(errors));
};

<Button
  onPress={methods.handleSubmit(onSubmit, onError)}
  title="Submit Form"
  color={"#007BFF"}
/>;

Schauen wir uns den Ablauf genauer an:

Der Handler onSubmit bekommt die Formulardaten als Argument. In diesem Szenario loggen wir die Daten nur, aber in echten Anwendungen könnten sie an einen Server geschickt oder je nach Bedarf der Anwendung weiterverarbeitet werden.

Die Funktion onError dagegen wird aufgerufen, wenn es beim Absenden des Formulars Validierungsfehler gibt. Das Objekt errors enthält detaillierte Informationen über alle Felder, deren Validierung fehlgeschlagen ist. In diesem Beispiel loggen wir diese Fehler einfach.

Wenn jedes Feld einen Fehler hat, sieht das Fehlerobjekt so aus:

    {
      "name": {
        "message": "This field is required",
        "type": "invalid_type",
        "ref": {
          "name": "name"
        }
      },
      "surname": {
        "message": "This field is required",
        "type": "invalid_type",
        "ref": {
          "name": "surname"
        }
      },
      "phoneNumber": {
        "message": "This field is required",
        "type": "invalid_type",
        "ref": {
          "name": "phoneNumber"
        }
      },
      "email": {
        "message": "This field is required",
        "type": "invalid_type",
        "ref": {
          "name": "email"
        }
      },
      "gender": {
        "message": "This field is required",
        "type": "invalid_type",
        "ref": {
          "name": "gender"
        }
      },
      "birthDate": {
        "message": "Invalid date time, too young",
        "type": "too_big",
        "ref": {
          "name": "birthDate"
        }
      }
    }

Vorab-Validierung mit Zod

Der folgende Codeblock zeigt einen Ansatz, bei dem Formulardaten vor dem Absenden manuell mit der Methode safeParse von Zod vorab validiert werden. Obwohl sich die Methode handleSubmit von React Hook Form bereits um die Formularvalidierung kümmert, kann eine Vorab-Validierung Entwicklern mehr Kontrolle über den Validierungsprozess geben.

<Button
  title="Submit Form"
  onPress={() => {
    // get current form values
    const currFormValues = methods.getValues();

    // Prevalidate using zod's safeParse
    const result = signUpFormSchema.safeParse(currFormValues);

    // If prevalidation is failed, display the error
    if (!result.success) {
      Alert.alert(JSON.stringify(result.error));
    } else {
      // If prevalidation is successful, notify the user
      Alert.alert("Validation is successful with zod");
    }
  }}
/>

Analysieren wir den Code oben:

  • Das Event onPress des Buttons wird genutzt, um eine Funktion auszuführen, die vor dem Absenden eine Vorab-Validierung durchführt.

  • Die Methode getValues aus methods (bereitgestellt von React Hook Form) wird verwendet, um die aktuellen Formularwerte abzurufen.

  • Diese Werte werden dann an die Methode safeParse von signUpFormSchema übergeben (das zod-Schema, das wir am Anfang erstellt haben). In diesem Schritt findet die Vorab-Validierung mit zod statt. Anders als die Methode parse von zod wirft safeParse keinen Fehler, wenn die Validierung fehlschlägt. Stattdessen gibt sie ein Objekt zurück, das den Boolean success enthält und, falls die Validierung fehlgeschlagen ist, ein Fehlerobjekt.

  • Eine Bedingung prüft, ob result.success false ist (die Validierung ist also fehlgeschlagen). Ist es false, wird ein Alert mit dem Validierungsfehler angezeigt.

  • Ist result.success true (die Validierung war also erfolgreich), wird ein Alert angezeigt, der meldet, dass die Validierung mit zod erfolgreich war.

Auch wenn dieser Ansatz überflüssig wirken mag, weil handleSubmit von React Hook Form die Formularvalidierung bereits mit dem über zod bereitgestellten Schema durchführt, kann er in bestimmten Szenarien trotzdem nützlich sein. Vielleicht willst du bestimmte Aktionen erst nach einer manuellen Validierung ausführen, oder du willst Formulareingaben in Echtzeit validieren, während der Nutzer das Formular ausfüllt. In solchen Fällen kann eine Vorab-Validierung mit der zod-Methode safeParse sehr nützlich sein.

Und so sieht das Fehlerobjekt von zod aus:

    {
      "issues": [
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": [
            "name"
          ],
          "message": "This field is required"
        },
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": [
            "surname"
          ],
          "message": "This field is required"
        },
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": [
            "phoneNumber"
          ],
          "message": "This field is required"
        },
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": [
            "email"
          ],
          "message": "This field is required"
        },
        {
          "expected": "'Male' | 'Female' | 'Other'",
          "received": "undefined",
          "code": "invalid_type",
          "path": [
            "gender"
          ],
          "message": "This field is required"
        },
        {
          "code": "too_big",
          "message": "Invalid date time, too young",
          "inclusive": true,
          "exact": false,
          "maximum": 1672531200000,
          "type": "date",
          "path": [
            "birthDate"
          ]
        }
      ],
      "name": "ZodError"
    }

Das ist tatsächlich ein großes Objekt, und für unseren Fall enthält es vielleicht sogar unnötige Felder. Zum Glück bietet zod eine Methode zum Formatieren von Fehlern.

Wir können einfach result.error.format() verwenden, und den Rest erledigt zod intern.

if (!result.success) {
  // Format errors using result.error.format()
  const formattedError = result.error.format();
  Alert.alert(JSON.stringify(formattedError));
} else {
  Alert.alert("Validation is successful with zod");
}

Das formatierte Fehlerobjekt sieht so aus:

    {
      "name": {
        "_errors": [
          "This field is required"
        ]
      },
      "surname": {
        "_errors": [
          "This field is required"
        ]
      },
      "phoneNumber": {
        "_errors": [
          "This field is required"
        ]
      },
      "email": {
        "_errors": [
          "This field is required"
        ]
      },
      "gender": {
        "_errors": [
          "This field is required"
        ]
      },
      "birthDate": {
        "_errors": [
          "Invalid date time, too young"
        ]
      }
    }

Der aktuelle Code

Hier ist der aktuelle Code (ohne Imports und Styles). Wenn du den vollständigen Quellcode sehen willst, schau ans Ende des Artikels.

// imports...

export const SignupForm: React.FC = () => {
  const [shouldValidateWithZod, setShouldValidateWithZod] =
    React.useState<boolean>(false);

  const [isCalendarOpenForAndroid, setIsCalendarOpenForAndroid] =
    React.useState<boolean>(false);

  const methods = useForm<SignUpFormSchema>({
    resolver: zodResolver(signUpFormSchema),
    defaultValues: {
      birthDate: new Date(),
    },
    mode: "onBlur",
  });

  const onSubmit: SubmitHandler<SignUpFormSchema> = (data) => {
    console.log(JSON.stringify(data));
  };

  const onError: SubmitErrorHandler<SignUpFormSchema> = (errors, e) => {
    console.log(JSON.stringify(errors));
    Alert.alert("Warning", getReadableValidationErrorMessage(errors));
  };

  return (
    <SafeAreaView edges={["top", "bottom"]} style={styles.safeArea}>
      <ScrollView>
        <Text style={styles.title}>Sign Up Form</Text>
        <View style={styles.root}>
          <FormProvider {...methods}>
            <Controller
              control={methods.control}
              name="name"
              render={({
                field: { onChange, onBlur, value },
                fieldState: { error },
              }) => {
                return (
                  <TextInput
                    label="Name"
                    onBlur={onBlur}
                    value={value}
                    onChangeText={onChange}
                    errorMessage={error?.message}
                  />
                );
              }}
            />
            <View style={styles.spacing} />
            <Controller
              control={methods.control}
              name="surname"
              render={({
                field: { onChange, onBlur, value },
                fieldState: { error },
              }) => {
                return (
                  <TextInput
                    label="Surname"
                    onBlur={onBlur}
                    value={value}
                    onChangeText={onChange}
                    errorMessage={error?.message}
                  />
                );
              }}
            />
            <View style={styles.spacing} />

            <Controller
              control={methods.control}
              name="email"
              render={({
                field: { onChange, onBlur, value },
                fieldState: { error },
              }) => {
                return (
                  <TextInput
                    label="Email"
                    onBlur={onBlur}
                    value={value}
                    onChangeText={onChange}
                    errorMessage={error?.message}
                  />
                );
              }}
            />

            <View style={styles.spacing} />

            <Controller
              control={methods.control}
              name="phoneNumber"
              render={({
                field: { onChange, onBlur, value },
                fieldState: { error },
              }) => {
                return (
                  <TextInput
                    label="Phone number"
                    onBlur={onBlur}
                    keyboardType="decimal-pad"
                    value={value}
                    onChangeText={(val) => onChange(val.toString())}
                    errorMessage={error?.message}
                  />
                );
              }}
            />

            <View style={styles.spacing} />

            <Controller
              control={methods.control}
              name="birthDate"
              render={({
                field: { onChange, value },
                fieldState: { error },
              }) => {
                return (
                  <View style={styles.dateWrapper}>
                    <Text style={styles.label}>Birth date</Text>

                    {Platform.OS === "android" && (
                      <Button
                        onPress={() => {
                          setIsCalendarOpenForAndroid(true);
                        }}
                        title={value.toString()}
                      />
                    )}

                    {(isCalendarOpenForAndroid ||
                      Platform.OS !== "android") && (
                      <RNDateTimePicker
                        value={value}
                        style={styles.dateTimePicker}
                        mode={"date"}
                        onChange={(e) => {
                          if (Platform.OS === "android") {
                            setIsCalendarOpenForAndroid(false);
                          }

                          if (e.type === "set" && e.nativeEvent.timestamp) {
                            onChange(new Date(e.nativeEvent.timestamp));
                            methods.trigger("birthDate");
                          }
                        }}
                      />
                    )}

                    {!!error?.message && (
                      <Text style={styles.errorMessageText}>
                        {error.message}
                      </Text>
                    )}
                  </View>
                );
              }}
            />

            <View style={styles.spacing} />

            <Controller
              control={methods.control}
              name="gender"
              render={({
                field: { onChange, onBlur, value, ref },
                fieldState: { error },
              }) => {
                return (
                  <View style={styles.genderWrapper}>
                    <Text style={styles.label}>Gender</Text>
                    <View style={styles.genderOptionsWrapper}>
                      {GENDER_OPTIONS.map((genderOption) => (
                        <Pressable
                          key={genderOption}
                          style={[
                            styles.genderOptionPressable,
                            {
                              backgroundColor:
                                value === genderOption ? "#007BFF" : "#F2F2F2",
                            },
                          ]}
                          onPress={() => onChange(genderOption)}
                        >
                          <Text
                            style={[
                              styles.genderOptionText,
                              {
                                color: value === genderOption ? "#fff" : "#000",
                              },
                            ]}
                          >
                            {genderOption}
                          </Text>
                        </Pressable>
                      ))}
                    </View>
                    {!!error?.message && (
                      <Text style={styles.errorMessageText}>
                        {error.message}
                      </Text>
                    )}
                  </View>
                );
              }}
            />

            <View style={styles.spacing} />

            <Text style={styles.label}>Should validate with zod</Text>

            <Switch
              value={shouldValidateWithZod}
              onChange={(e) => setShouldValidateWithZod(e.nativeEvent.value)}
            />
            <View style={styles.spacing} />

            <Button
              onPress={
                shouldValidateWithZod
                  ? () => {
                      /** we could also prevalidate using zod like below */

                      // get current form values
                      const currFormValues = methods.getValues();
                      // https://zod.dev/?id=safeparse
                      const result = signUpFormSchema.safeParse(currFormValues);

                      if (!result.success) {
                        const formattedError = result.error.format();
                        Alert.alert(JSON.stringify(formattedError));
                      } else {
                        Alert.alert("Validation is successful with zod");
                      }
                    }
                  : methods.handleSubmit(onSubmit, onError)
              }
              title="Submit Form"
              color={"#007BFF"}
            />
          </FormProvider>
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

// styles...

Diese Beispiel-App ist mit expo go geschrieben. Du kannst sie also ganz einfach mit dem QR-Code unten testen! (Falls der QR-Code nicht funktioniert, nutze bitte den Link zum Quellcode am Ende des Artikels.)

Fazit

In diesem Artikel haben wir uns angesehen, wie wir die Kombination aus React Hook Form, Zod und TypeScript effektiv nutzen können, um eine robuste Formularvalidierung in unserer React-Native-Anwendung zu bauen. Wir haben gesehen, wie uns die Flexibilität und Stärke dieser Libraries sauberen, typsicheren Code ermöglichen, der auch komplexe Validierungsanforderungen abdeckt.

Das Zusammenspiel von React Hook Form und Zod lässt uns die Vorteile beider nutzen. React Hook Form vereinfacht das Formular-Handling, optimiert Re-Renders und bringt Features wie State-Management für Formulare und Fehlerbehandlung mit. Zod wiederum bietet eine zusätzliche Sicherheitsebene: Wir können festlegen, welche Art von Daten für jedes Formularfeld erlaubt ist, und diese Regeln durchsetzen.

Auch wenn die hier gezeigten Techniken im Kontext eines einfachen Registrierungsformulars verwendet werden, lassen sie sich auf jede formularbasierte Nutzereingabe in deinen React-Native-Anwendungen übertragen. Mit diesen Strategien stellst du sicher, dass deine Formulare nutzerfreundlich, robust und wartbar sind, was zu besseren Nutzererlebnissen und robusteren Anwendungen führt.

Link zum vollständigen Quellcode