博客

React Native 进阶表单处理

2023年6月28日 10 分钟阅读

React Native 中的进阶表单处理技巧。了解校验、性能优化以及如何创建可复用的表单组件。

React Native 进阶表单处理
React Native表单校验性能React Hook FormZod

React Native 进阶表单处理

用 Zod 和 React Hook Form 改进 React Native 中的表单处理

对于任何需要用户输入的应用来说,表单处理都是基础功能。有了合适的工具和库,它可以变得简单而顺畅。本文会介绍如何在 react-native 应用中用 react-hook-form 和 zod 处理表单。把这两者结合起来,我们就能得到一套高效的表单处理机制。我们来创建一个基础的注册表单作为示例。

完整源码附在文章末尾。

用 Zod 声明 Schema

首先,我们用 zod 声明 schema。这个 schema 描述了表单数据应有的结构,并为每个字段设置校验规则。Zod 提供了大量强大的校验函数来定义这些规则。

下面是完整的 zod schema:

本文假设你已经了解 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>;

在这个 schema 中,我们用 zod 规定了每个字段应该包含什么。比如,name 和 surname 字段应该是长度在 3 到 20 个字符之间的字符串,而 phoneNumber 字段应该是数字。

有些字段的规则更复杂。比如,email 字段应该是字符串,并且只能是合法的邮箱地址。gender 字段应该是预定义的性别选项之一('Male'、'Female' 或 'Other')。

最后,birthDate 字段是日期类型,应该是 1900-01-01 到 2023-01-01 之间的合法日期。如果没有提供,默认取当前日期。

有了 zod,我们可以轻松创建复杂的校验规则。这样就能保证从表单拿到的数据符合我们的预期。

下一步是推断 schema 的类型。Zod 提供了 infer 方法,可以从给定的 zod schema 推导出 TypeScript 类型。

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

这个推断出来的类型之后会在 useForm 中使用,以确保表单数据和 schema 保持一致。

用 React Hook Form 设置表单

接下来,我们用 'react-hook-form' 的 useForm hook 来设置表单。这个 hook 接收我们的 zod schema(通过 zodResolver)作为参数来处理表单校验。

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

resolver 是我们传入 schema 的地方。defaultValues 属性可以为表单字段提供默认值,这里我们把 birthDate 的默认值设为当前日期。mode 属性决定校验在什么时候发生。这里校验会在 onBlur 时进行,也就是用户离开某个字段的时候。

字段渲染与校验

我们用 react-hook-form 的 Controller 组件来管理每个表单字段。它提供 field 和 fieldState 两个 props,我们用它们来管理字段的值、错误状态和校验。

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

每个 prop 的作用如下:

  • control:在这里传入 useForm hook 提供的 control prop。Controller 需要它来和表单 state 交互。

  • name:这是在表单中访问该输入值的 key。读取或设置表单值时,用的就是这个 key。它在所有表单字段中必须唯一。

  • render:一个返回输入元素的函数。这个函数会提供 field 和 fieldState 两个 props。

  • field:包含 onChange、onBlur 和 value 三个 props。它们应该直接连接到你的受控组件上。这里 onChange 连接到 TextInput 的 onChangeText,用来捕获用户输入并保存到表单 state 中。

  • fieldState:其中包含 error prop,提供该字段校验错误的信息。

在 render prop 内部,我们对 TextInput 做了定制。onBlur 和 onChangeText 分别绑定到 field 中对应的方法,value prop 绑定到该输入当前的表单值。errorMessage prop 则在校验失败时连接到错误信息。

所以,在提交表单或实时校验时,如果 ‘name’ 字段不满足 Zod schema 中定义的校验要求,错误信息就会显示在这个 TextInput 字段里。

用 React Hook Form 自定义触发校验

处理 birthDate 字段时会遇到一个特殊情况,它使用的是日期选择器组件(这里是 RNDateTimePicker)。在这种情况下,校验过程需要特殊处理,因为用户和日期选择器的交互方式不同于普通的文本输入。

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

当用户选择日期时,会触发 onChange 事件。在这个事件处理函数里,我们先检查事件类型是否为 'set',它表示用户已经设置了日期。接着检查 timestamp 是否存在,以确保确实选择了日期。

确认这些条件后,我们用 new Date(e.nativeEvent.timestamp) 把 timestamp 转换成 JavaScript 的 Date 对象。然后把这个新值传给 onChange,更新表单中 birthDate 字段的值。

不过,普通文本输入在值变化时会自动触发校验,日期选择器却不会以同样的方式触发校验。因此,我们需要在值更新后手动触发校验,做法是调用 methods.trigger('birthDate')。

react-hook-form 提供的 trigger 方法会对指定字段发起校验。这里,一旦设置了日期,它就会触发 birthDate 字段的校验,确保我们的校验规则立刻生效。

最后,如果有校验错误,会通过 {!!error?.message && {error.message}} 显示出来,其中 error?.message 就是我们在 zod schema 中定义的校验错误信息。

表单提交:React Hook Form

React-hook-form 包提供了高效的方法来处理表单提交和错误。

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

我们来拆解一下这个过程:

onSubmit 处理函数接收表单数据作为参数。在这个例子里我们只是把数据打印出来,但在真实应用中,可以把它发送到服务器,或者根据应用需求做进一步处理。

而 onError 函数会在提交表单时出现校验错误的情况下被调用。errors 对象包含所有校验失败字段的详细信息。在这个例子里,我们只是把这些错误打印出来。

如果每个字段都有错误,error 对象会是下面这样:

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

用 Zod 预校验

下面的代码块展示了一种做法:在表单提交事件之前,用 Zod 的 safeParse 方法手动预校验表单数据。虽然 React Hook Form 的 handleSubmit 方法已经负责了表单校验,但预校验可以让开发者对校验过程有更多的控制。

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

我们来分析一下上面的代码:

  • Button 的 onPress 事件用来执行一个函数,在提交表单前做预校验。

  • 用 methods(由 React Hook Form 提供)的 getValues 方法获取当前的表单值。

  • 然后把这些值传给 signUpFormSchema(我们一开始创建的 zod schema)的 safeParse 方法。zod 的预校验就发生在这一步。和 zod 的 parse 方法不同,safeParse 在校验失败时不会抛出错误。它会返回一个对象,其中包含布尔值 success,如果校验失败,还会包含一个 error 对象。

  • 一个条件语句检查 result.success 是否为 false(表示校验失败)。如果是 false,就弹出一个提示框显示校验错误。

  • 如果 result.success 为 true(表示校验成功),就弹出一个提示框,说明 zod 校验通过。

由于 React Hook Form 的 handleSubmit 已经用 zod 提供的 schema 做了表单校验,这种做法看起来可能有些多余,但在某些特定场景下它依然有用。比如,你可能只想在手动校验通过后才执行某些操作,或者想在用户填写表单时实时校验输入。在这些情况下,用 zod 的 safeParse 方法做预校验会非常有用。

zod 的 error 对象大概是这样的:

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

这确实是一个很大的对象,里面甚至可能有我们用不到的字段。好在 zod 提供了格式化错误的方法。

我们只需要调用 result.error.format(),剩下的 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");
}

格式化后的 error 对象如下:

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

最终代码

下面是最新的代码(不含 import 和样式)。如果想查看完整源码,请看文章末尾。

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

这个示例应用是用 expo go 编写的。也就是说,你可以用下面的二维码轻松试用!(如果二维码无法使用,请参考文章末尾的源码链接。)

总结

在本文中,我们探讨了如何有效结合 React Hook Form、Zod 和 TypeScript,在 React Native 应用中实现可靠的表单校验。我们看到,这些库的灵活性和强大功能让我们能写出简洁、类型安全的代码,处理复杂的校验需求。

React Hook Form 和 Zod 搭配使用,可以同时获得两者的好处。React Hook Form 简化了表单处理,优化了重新渲染,还包含表单 state 管理和错误处理等功能。Zod 则提供了额外一层安全保障,让我们可以规定每个表单字段允许哪种数据,并强制执行这些规则。

请记住,虽然这里展示的技巧是在一个简单注册表单的场景中使用的,但它们适用于 React Native 应用中任何基于表单的用户输入。运用这些策略,你可以让表单易用、可靠、易于维护,从而带来更好的用户体验和更健壮的应用。

完整源码链接