Blog

Formulários de outro nível no React Native

28 de junho de 2023 10 min de leitura

Técnicas avançadas de formulários no React Native. Aprenda sobre validação, otimização de performance e criação de componentes de formulário reutilizáveis.

Formulários de outro nível no React Native
React NativeFormuláriosValidaçãoPerformanceReact Hook FormZod

Formulários de outro nível no React Native

Melhore o tratamento de formulários no React Native com Zod e React Hook Form

O tratamento de formulários é uma parte fundamental de qualquer aplicação que precisa de input do usuário e, com as ferramentas e bibliotecas certas, pode ser um processo simples e sem atrito. Este artigo mostra como lidar com formulários em um app react-native usando react-hook-form e zod. Combinando os dois, vamos chegar a um mecanismo eficiente de tratamento de formulários. Vamos criar um formulário de cadastro básico para ilustrar isso.

O código-fonte completo está no fim do artigo.

Declaração do schema com Zod

Para começar, declaramos o nosso schema com zod. Esse schema define o formato esperado dos dados do formulário e configura as validações de cada campo. O Zod oferece várias funções de validação poderosas para definir essas regras.

Aqui está o schema zod completo:

Este artigo parte do princípio de que você conhece o básico de 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>;

Nesse schema, usamos o zod para especificar o que cada campo deve conter. Por exemplo, os campos name e surname devem ser strings com 3 a 20 caracteres, enquanto o campo phoneNumber deve ser um número.

Também temos regras mais complexas para alguns campos. Por exemplo, o campo email deve ser uma string e aceitar apenas endereços de e-mail válidos. O campo gender deve ser uma das opções de gênero predefinidas ('Male', 'Female' ou 'Other').

Por fim, o campo birthDate é do tipo date e deve ser uma data válida entre 1900-01-01 e 2023-01-01. Por padrão, ele usa a data atual se nenhuma for informada.

Com o zod, criamos regras de validação complexas com facilidade. Assim, os dados que recebemos do formulário vão corresponder com garantia ao que esperamos.

O próximo passo é inferir o tipo do schema. O Zod oferece um método infer, que deriva o tipo TypeScript de um schema zod.

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

Esse tipo inferido é usado depois no useForm para garantir que os dados do formulário estejam alinhados ao schema.

Configuração do formulário com React Hook Form

Em seguida, configuramos o formulário com o hook useForm do 'react-hook-form'. Esse hook recebe o nosso schema zod (por meio do zodResolver) como argumento para resolver a validação do formulário.

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

O resolver é onde passamos o nosso schema. A propriedade defaultValues permite informar valores padrão para os campos do formulário. Neste caso, definimos o birthDate padrão como a data atual. A propriedade mode define quando a validação deve acontecer. Neste caso, a validação acontece no onBlur, ou seja, quando o usuário sai de um campo.

Renderização e validação dos campos

Usamos o componente Controller do react-hook-form para gerenciar cada campo do formulário. Ele nos dá as props field e fieldState, que usamos para gerenciar o valor do campo, o estado de erro e a validação.

Por exemplo, assim configuramos o campo 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}
      />
    );
  }}
/>

Veja o que cada prop faz:

  • control: é aqui que você passa a prop control do hook useForm. Ela é necessária para que o Controller interaja com o estado do formulário.

  • name: é a chave para acessar o valor do input dentro do formulário. Quando você lê ou define valores do formulário, é essa chave que será usada. Ela precisa ser única entre todos os campos do formulário.

  • render: é uma função que retorna o seu elemento de input. A função fornece as props field e fieldState.

  • field: contém as props onChange, onBlur e value. Elas devem ser ligadas diretamente ao seu componente controlado. Neste caso, o onChange está conectado ao onChangeText do TextInput, que captura o que o usuário digita e guarda no estado do formulário.

  • fieldState: inclui a prop error, que traz informações sobre erros de validação desse campo.

Dentro da prop render, o TextInput é personalizado. O onBlur e o onChangeText são ligados aos métodos correspondentes do field, e a prop value é ligada ao valor atual desse input no formulário. A prop errorMessage é conectada à mensagem de erro em caso de falha na validação.

Assim, no envio do formulário ou na validação em tempo real, se o campo 'name' não cumprir os requisitos de validação definidos no schema Zod, a mensagem de erro será exibida nesse campo TextInput.

Disparando validação personalizada com React Hook Form

Um cenário especial aparece com o campo birthDate, que usa um componente de seleção de data (neste caso, o RNDateTimePicker). Nessa situação, o processo de validação precisa de um tratamento especial, porque a interação do usuário com um seletor de data é diferente da interação com inputs de texto comuns.

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

Quando o usuário seleciona uma data, o evento onChange é disparado. Dentro desse handler, primeiro verificamos se o tipo do evento é 'set', o que indica que o usuário definiu uma data. Depois, verificamos se existe um timestamp, para garantir que uma data foi selecionada.

Confirmadas essas condições, convertemos o timestamp em um objeto Date do JavaScript com new Date(e.nativeEvent.timestamp). Em seguida, esse novo valor é passado para o onChange, que atualiza o valor do campo birthDate no formulário.

Porém, diferente dos inputs de texto comuns, que disparam a validação automaticamente quando mudam, os seletores de data não disparam a validação do mesmo jeito. Por isso, precisamos disparar a validação manualmente depois que o valor é atualizado. Fazemos isso chamando methods.trigger('birthDate').

Esse método trigger, fornecido pelo react-hook-form, inicia a validação de um campo específico. Aqui, ele dispara a validação do campo birthDate assim que a data é definida, garantindo que as nossas regras de validação sejam aplicadas imediatamente.

Por fim, se houver erros de validação, eles serão exibidos via {!!error?.message && {error.message}}, onde error?.message contém a mensagem de erro de validação definida no nosso schema zod.

Envio do formulário com React Hook Form

O pacote react-hook-form oferece métodos eficientes para lidar com o envio de formulários e o tratamento de erros.

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

Vamos destrinchar o processo:

O handler onSubmit recebe os dados do formulário como argumento. Neste cenário, estamos apenas registrando esses dados no log, mas em aplicações reais eles poderiam ser enviados para um servidor ou manipulados de acordo com as necessidades da aplicação.

Já a função onError é chamada quando há erros de validação no envio do formulário. O objeto errors contém informações detalhadas sobre todos os campos que falharam na validação. Neste exemplo, estamos apenas registrando esses erros no log.

Se todos os campos tiverem erro, o objeto de erro seria o seguinte:

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

Pré-validação com Zod

O bloco de código abaixo apresenta uma forma de pré-validar manualmente os dados do formulário com o método safeParse do Zod antes do evento de envio. Embora a validação já seja feita pelo método handleSubmit do React Hook Form, a pré-validação pode dar aos desenvolvedores mais controle sobre o processo de validação do formulário.

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

Vamos analisar o código acima:

  • O evento onPress do Button é usado para executar uma função que faz a pré-validação antes do envio do formulário.

  • O método getValues de methods (fornecido pelo React Hook Form) é usado para obter os valores atuais do formulário.

  • Esses valores são então passados para o método safeParse do signUpFormSchema (um schema zod que criamos no começo). É nesse passo que acontece a pré-validação do zod. Diferente do método parse do zod, o safeParse não lança um erro quando a validação falha. Em vez disso, ele retorna um objeto com o booleano success e, se a validação falhar, um objeto de erro.

  • Uma condicional verifica se result.success é false (o que indica que a validação falhou). Se for false, ela dispara um alerta mostrando o erro de validação.

  • Se result.success for true (o que indica validação bem-sucedida), ela dispara um alerta dizendo que a validação com zod deu certo.

Mesmo que essa abordagem pareça redundante, já que o handleSubmit do React Hook Form já faz a validação do formulário com o schema fornecido via zod, ela ainda pode ser útil em cenários específicos. Por exemplo, você pode querer executar certas ações só depois de uma validação manual, ou validar os inputs do formulário em tempo real enquanto o usuário preenche. Nesses casos, a pré-validação com o método safeParse do zod pode ser bem útil.

E é assim que o objeto de erro do zod ficaria:

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

É de fato um objeto grande, e pode até ter campos desnecessários para o nosso caso. Felizmente, o zod oferece um método para formatar erros.

Podemos simplesmente usar result.error.format() e o resto é tratado internamente pelo zod.

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

O objeto de erro formatado ficaria assim:

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

O código mais recente

A seguir está o código mais recente (sem imports e styles). Se você quiser ver o código-fonte completo, confira o fim do artigo.

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

Este app de exemplo foi escrito com expo go. Ou seja, você pode testá-lo facilmente usando o QR code abaixo! (caso o QR não funcione, use o link do código-fonte no fim do artigo.)

Conclusão

Ao longo deste artigo, vimos como aproveitar de forma eficaz a combinação de React Hook Form, Zod e TypeScript para criar uma validação de formulários robusta na nossa aplicação React Native. Vimos como a flexibilidade e o poder dessas bibliotecas nos permitem produzir código limpo e type-safe, capaz de lidar com requisitos de validação complexos.

A sinergia entre React Hook Form e Zod nos permite colher os benefícios dos dois. O React Hook Form simplifica o tratamento de formulários, otimiza os re-renders e inclui recursos como gerenciamento do estado do formulário e tratamento de erros. Por outro lado, o Zod oferece uma camada extra de segurança, permitindo especificar que tipo de dado é aceito em cada campo do formulário e garantir o cumprimento dessas regras.

Lembre-se: embora as técnicas mostradas aqui sejam usadas no contexto de um formulário de cadastro simples, elas se aplicam a qualquer input de usuário baseado em formulário nas suas aplicações React Native. Usando essas estratégias, você garante que os seus formulários sejam fáceis de usar, robustos e fáceis de manter, o que leva a experiências de usuário melhores e aplicações mais robustas.

Link do código-fonte completo