Blog

Obsługa formularzy w React Native na wyższym poziomie

28 czerwca 2023 10 min czytania

Zaawansowane techniki obsługi formularzy w React Native. Walidacja, optymalizacja wydajności i komponenty formularzy wielokrotnego użytku.

Obsługa formularzy w React Native na wyższym poziomie
React NativeFormularzeWalidacjaWydajnośćReact Hook FormZod

Obsługa formularzy w React Native na wyższym poziomie

Lepsza obsługa formularzy w React Native z Zod i React Hook Form

Obsługa formularzy to podstawowa część każdej aplikacji, która przyjmuje dane od użytkownika, a z odpowiednimi narzędziami i bibliotekami może być prostym i płynnym procesem. Ten artykuł pokaże ci, jak obsługiwać formularze w aplikacji react-native za pomocą react-hook-form i zod. Łącząc te dwie biblioteki, uzyskamy wydajny mechanizm obsługi formularzy. Żeby to zilustrować, zbudujmy prosty formularz rejestracji.

Pełny kod źródłowy znajdziesz na końcu artykułu.

Deklaracja schematu w Zod

Na początek deklarujemy schemat za pomocą zod. Ten schemat określa oczekiwany kształt danych formularza i ustawia walidację dla każdego pola. Zod oferuje mnóstwo rozbudowanych funkcji walidacyjnych do definiowania takich reguł.

Oto pełny schemat zod:

Artykuł zakłada, że znasz podstawy zod.

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>;

W tym schemacie używamy zod, żeby określić, co powinno zawierać każde pole. Na przykład pola name i surname powinny być stringami o długości od 3 do 20 znaków, a pole phoneNumber powinno być liczbą.

Niektóre pola mają też bardziej złożone reguły. Na przykład pole email powinno być stringiem i przyjmować tylko poprawne adresy e-mail. Pole gender powinno mieć jedną z predefiniowanych wartości płci ('Male', 'Female' lub 'Other').

Na koniec pole birthDate jest typu date i powinno zawierać poprawną datę z zakresu od 1900-01-01 do 2023-01-01. Jeśli żadna data nie zostanie podana, domyślnie przyjmuje bieżącą.

Z zod łatwo tworzymy złożone reguły walidacji. Dzięki temu mamy gwarancję, że dane, które dostaniemy z formularza, będą zgodne z tym, czego oczekujemy.

Kolejny krok to wywnioskowanie typu schematu. Zod oferuje metodę infer, która wyprowadza typ TypeScript z danego schematu zod.

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

Ten wywnioskowany typ wykorzystujemy później w useForm, żeby dane formularza były zgodne ze schematem.

Konfiguracja formularza w React Hook Form

Następnie konfigurujemy formularz za pomocą hooka useForm z 'react-hook-form'. Ten hook przyjmuje jako argument nasz schemat zod (przez zodResolver), żeby obsłużyć walidację formularza.

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

Resolver to miejsce, w którym przekazujemy schemat. Właściwość defaultValues pozwala podać domyślne wartości pól formularza. Tutaj ustawiamy domyślną wartość birthDate na bieżącą datę. Właściwość mode decyduje, kiedy ma się odbywać walidacja. W tym przypadku walidacja nastąpi onBlur, czyli wtedy, gdy użytkownik opuści pole.

Renderowanie pól i walidacja

Do zarządzania każdym polem formularza używamy komponentu Controller z react-hook-form. Daje nam propsy field i fieldState, za pomocą których zarządzamy wartością pola, stanem błędu i walidacją.

Na przykład tak konfigurujemy pole name:

<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}
      />
    );
  }}
/>

Oto, co robi każdy z propsów:

  • control: tutaj przekazujesz prop control z hooka useForm. Jest niezbędny, żeby Controller mógł współpracować ze stanem formularza.

  • name: to klucz, pod którym dostępna jest wartość inputa w formularzu. Gdy pobierasz lub ustawiasz wartości formularza, używany jest właśnie ten klucz. Musi być unikalny wśród wszystkich pól formularza.

  • render: to funkcja, która zwraca element inputa. Funkcja dostarcza propsy field i fieldState.

  • field: zawiera propsy onChange, onBlur i value. Powinny być podpięte bezpośrednio do kontrolowanego komponentu. W tym przypadku onChange jest połączony z onChangeText komponentu TextInput, który przechwytuje to, co wpisuje użytkownik, i zapisuje to w stanie formularza.

  • fieldState: zawiera prop error, który daje informacje o błędach walidacji dla tego pola.

Wewnątrz propa render dostosowujemy TextInput. onBlur i onChangeText są podpięte do odpowiednich metod z field, a prop value jest połączony z bieżącą wartością formularza dla tego inputa. Prop errorMessage jest powiązany z komunikatem błędu na wypadek nieudanej walidacji.

Jeśli więc przy wysłaniu formularza albo przy walidacji w czasie rzeczywistym pole ‘name’ nie spełni wymagań walidacji zdefiniowanych w schemacie Zod, komunikat błędu pojawi się w tym polu TextInput.

Ręczne wywoływanie walidacji w React Hook Form

Szczególny przypadek pojawia się przy polu birthDate, które korzysta z komponentu date pickera (tutaj RNDateTimePicker). W tej sytuacji walidacja wymaga specjalnej obsługi, bo interakcja użytkownika z date pickerem różni się od typowych pól tekstowych.

<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>
    );
  }}
/>

Gdy użytkownik wybiera datę, wywoływane jest zdarzenie onChange. W tym handlerze najpierw sprawdzamy, czy typ zdarzenia to 'set', co oznacza, że użytkownik ustawił datę. Następnie sprawdzamy, czy jest timestamp, żeby mieć pewność, że data została wybrana.

Po potwierdzeniu tych warunków zamieniamy timestamp na obiekt Date w JavaScripcie za pomocą new Date(e.nativeEvent.timestamp). Potem ta nowa wartość trafia do onChange, który aktualizuje wartość pola birthDate w formularzu.

Jednak w przeciwieństwie do typowych pól tekstowych, które automatycznie uruchamiają walidację przy zmianach, date pickery nie wywołują walidacji w ten sam sposób. Dlatego po aktualizacji wartości musimy wywołać walidację ręcznie. Robimy to, wywołując methods.trigger('birthDate').

Metoda trigger, którą udostępnia react-hook-form, uruchamia walidację konkretnego pola. Tutaj uruchamia walidację pola birthDate od razu po ustawieniu daty, dzięki czemu nasze reguły walidacji są stosowane natychmiast.

Na koniec, jeśli wystąpią błędy walidacji, zostaną wyświetlone przez {!!error?.message && {error.message}}, gdzie error?.message zawiera komunikat błędu walidacji zdefiniowany w schemacie zod.

Wysyłanie formularza w React Hook Form

Pakiet react-hook-form udostępnia wydajne metody do obsługi wysyłania formularzy i błędów.

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"}
/>;

Rozłóżmy ten proces na części:

Handler onSubmit dostaje dane formularza jako argument. W tym scenariuszu tylko je logujemy, ale w prawdziwych aplikacjach można je wysłać na serwer albo dalej przetwarzać, zależnie od potrzeb aplikacji.

Funkcja onError natomiast jest wywoływana, gdy przy wysyłaniu formularza wystąpią błędy walidacji. Obiekt errors zawiera szczegółowe informacje o wszystkich polach, które nie przeszły walidacji. W tym przykładzie po prostu logujemy te błędy.

Jeśli błąd wystąpi w każdym polu, obiekt błędów będzie wyglądał tak:

    {
      "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"
        }
      }
    }

Wstępna walidacja z Zod

Poniższy blok kodu pokazuje podejście, w którym dane formularza są ręcznie wstępnie walidowane metodą safeParse z Zod jeszcze przed zdarzeniem wysłania formularza. Choć walidację formularza załatwia już metoda handleSubmit z React Hook Form, wstępna walidacja może dać developerom większą kontrolę nad procesem walidacji.

<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");
    }
  }}
/>

Przeanalizujmy powyższy kod:

  • Zdarzenie onPress przycisku Button służy do uruchomienia funkcji, która wykonuje wstępną walidację przed wysłaniem formularza.

  • Metoda getValues z methods (udostępnianych przez React Hook Form) służy do pobrania bieżących wartości formularza.

  • Te wartości trafiają następnie do metody safeParse z signUpFormSchema (schematu zod, który utworzyliśmy na początku). Na tym etapie odbywa się wstępna walidacja zod. W przeciwieństwie do metody parse z zod, safeParse nie rzuca błędu, gdy walidacja się nie powiedzie. Zamiast tego zwraca obiekt zawierający wartość logiczną success oraz, jeśli walidacja się nie powiodła, obiekt error.

  • Instrukcja warunkowa sprawdza, czy result.success ma wartość false (co oznacza, że walidacja się nie powiodła). Jeśli tak, wyświetla alert z błędem walidacji.

  • Jeśli result.success ma wartość true (co oznacza udaną walidację), wyświetla alert z informacją, że walidacja z zod się powiodła.

Choć to podejście może wydawać się zbędne, bo handleSubmit z React Hook Form już waliduje formularz przy użyciu schematu przekazanego przez zod, w pewnych scenariuszach wciąż może się przydać. Na przykład możesz chcieć wykonać pewne akcje dopiero po ręcznej walidacji albo walidować pola formularza w czasie rzeczywistym, gdy użytkownik go wypełnia. W takich przypadkach wstępna walidacja metodą safeParse z zod bywa bardzo przydatna.

A tak wyglądałby obiekt błędu zod:

    {
      "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"
    }

To rzeczywiście duży obiekt i w naszym przypadku mogą się w nim znaleźć nawet niepotrzebne pola. Na szczęście zod udostępnia metodę do formatowania błędów.

Wystarczy użyć result.error.format(), a resztą zod zajmie się wewnętrznie.

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");
}

Sformatowany obiekt błędu wyglądałby tak:

    {
      "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"
        ]
      }
    }

Najnowszy kod

Poniżej znajduje się najnowsza wersja kodu (bez importów i stylów). Jeśli chcesz zobaczyć pełny kod źródłowy, zajrzyj na koniec artykułu.

// 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...

Ta przykładowa aplikacja jest napisana z użyciem expo go. To znaczy, że możesz ją łatwo przetestować, skanując poniższy kod QR! (jeśli kod QR nie działa, skorzystaj z linku do kodu źródłowego na końcu artykułu.)

Podsumowanie

W tym artykule sprawdziliśmy, jak skutecznie wykorzystać połączenie React Hook Form, Zod i TypeScriptu, żeby zbudować solidną walidację formularzy w aplikacji React Native. Zobaczyliśmy, jak elastyczność i możliwości tych bibliotek pozwalają pisać czysty, type-safe kod, który radzi sobie ze złożonymi wymaganiami walidacji.

Połączenie React Hook Form i Zod pozwala czerpać korzyści z obu bibliotek. React Hook Form upraszcza obsługę formularzy, optymalizuje re-rendery i oferuje takie funkcje jak zarządzanie stanem formularza i obsługa błędów. Z kolei Zod daje dodatkową warstwę bezpieczeństwa: pozwala określić, jakie dane są dozwolone w każdym polu formularza, i egzekwować te reguły.

Pamiętaj, że choć pokazane tu techniki zastosowaliśmy w prostym formularzu rejestracji, sprawdzą się przy każdym formularzu przyjmującym dane od użytkownika w twoich aplikacjach React Native. Stosując te strategie, zadbasz o to, żeby formularze były przyjazne dla użytkownika, solidne i łatwe w utrzymaniu, co przełoży się na lepsze doświadczenia użytkowników i bardziej niezawodne aplikacje.

Link do pełnego kodu źródłowego