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 &&
表单提交: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 应用中任何基于表单的用户输入。运用这些策略,你可以让表单易用、可靠、易于维护,从而带来更好的用户体验和更健壮的应用。