المدونة

التعامل مع النماذج في React Native بمستوى أعلى

28 يونيو 2023 10 دقائق للقراءة

تقنيات متقدمة للتعامل مع النماذج في React Native. تعرّف على التحقق من صحة المدخلات وتحسين الأداء وإنشاء مكونات نماذج قابلة لإعادة الاستخدام.

التعامل مع النماذج في React Native بمستوى أعلى
React Nativeالنماذجالتحقق من الصحةالأداءReact Hook FormZod

التعامل مع النماذج في React Native بمستوى أعلى

حسّن التعامل مع النماذج في React Native باستخدام Zod وReact Hook Form

التعامل مع النماذج (forms) جزء أساسي من أي تطبيق يحتاج إلى مدخلات من المستخدم، ومع الأدوات والمكتبات المناسبة يمكن أن يكون عملية بسيطة وسلسة. سيرشدك هذا المقال إلى طريقة التعامل مع النماذج في تطبيق react-native باستخدام react-hook-form وzod. وبالجمع بين الاثنين سنحصل على آلية فعّالة للتعامل مع النماذج. لننشئ نموذج تسجيل بسيطًا لتوضيح ذلك.

الكود المصدري الكامل موجود في نهاية المقال.

تعريف الـ Schema باستخدام Zod

في البداية نعرّف الـ schema باستخدام zod. يحدد هذا الـ schema الشكل المتوقع لبيانات النموذج، ويضبط قواعد التحقق لكل حقل. ويوفر Zod مجموعة كبيرة من دوال التحقق القوية لتعريف هذه القواعد.

إليك الـ schema الكامل في zod:

يفترض هذا المقال أنك تعرف أساسيات 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 التي تستخرج نوع TypeScript لأي schema في zod.

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

يُستخدم هذا النوع المستنتج لاحقًا في useForm لضمان توافق بيانات النموذج مع الـ schema.

إعداد النموذج باستخدام React Hook Form

بعد ذلك نُعدّ النموذج باستخدام الـ hook المسمى useForm من 'react-hook-form'. يأخذ هذا الـ hook الـ schema الخاص بنا في zod (عبر zodResolver) كوسيط ليتولى التحقق من النموذج.

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

الـ resolver هو المكان الذي نمرر فيه الـ schema. وتتيح لنا الخاصية defaultValues تقديم قيم افتراضية لحقول النموذج. في هذه الحالة نضبط القيمة الافتراضية لـ birthDate لتكون التاريخ الحالي. أما الخاصية mode فتحدد متى يحدث التحقق. في هذه الحالة سيحدث التحقق عند onBlur، أي عندما يغادر المستخدم الحقل.

عرض الحقول والتحقق منها

نستخدم المكوّن Controller من react-hook-form لإدارة كل حقل في النموذج. يوفر لنا الـ props المسماة field وfieldState، ونستخدمها لإدارة قيمة الحقل وحالة الخطأ والتحقق.

فمثلًا، هكذا نُعدّ حقل 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: هنا تمرر الـ prop المسمى control من الـ hook المسمى useForm. وهو ضروري ليتعامل Controller مع حالة النموذج.

  • name: هذا هو المفتاح للوصول إلى قيمة المدخل داخل النموذج. عندما تسترجع قيم النموذج أو تضبطها، يُستخدم هذا المفتاح. ويجب أن يكون فريدًا بين كل حقول النموذج.

  • render: دالة تعيد عنصر الإدخال الخاص بك. وتوفر الدالة الـ props المسماة field وfieldState.

  • field: يحتوي على الـ props المسماة onChange وonBlur وvalue. ويجب ربطها مباشرة بالمكوّن المتحكَّم به (controlled component). في هذه الحالة يُربط onChange بـ onChangeText في TextInput، فيلتقط مدخلات المستخدم ويخزنها في حالة النموذج.

  • fieldState: يتضمن الـ prop المسمى error الذي يعطي معلومات عن أخطاء التحقق في هذا الحقل.

داخل الـ prop المسمى render يُخصَّص TextInput. يُربط onBlur وonChangeText بالدوال المقابلة لهما من field، ويُربط الـ prop المسمى value بالقيمة الحالية لهذا المدخل في النموذج. ويُوصل الـ prop المسمى errorMessage برسالة الخطأ في حال فشل التحقق.

وهكذا، عند إرسال النموذج أو عند التحقق اللحظي، إذا لم يستوفِ الحقل 'name' شروط التحقق المعرّفة في الـ schema الخاص بـ Zod، فستظهر رسالة الخطأ في حقل 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 للتأكد من اختيار تاريخ.

بعد التأكد من هذه الشروط، نحوّل الـ timestamp إلى كائن Date في JavaScript باستخدام new Date(e.nativeEvent.timestamp). ثم نمرر هذه القيمة الجديدة إلى onChange، فتتحدث قيمة الحقل birthDate في النموذج.

لكن على عكس حقول النص المعتادة التي تطلق التحقق تلقائيًا عند التغيير، لا تطلق منتقيات التاريخ التحقق بالطريقة نفسها. لذلك نحتاج إلى تشغيل التحقق يدويًا بعد تحديث القيمة. ونحقق ذلك باستدعاء methods.trigger('birthDate').

دالة trigger هذه التي توفرها react-hook-form تبدأ التحقق لحقل معين. وهنا تطلق التحقق للحقل birthDate بمجرد تحديد التاريخ، ما يضمن تطبيق قواعد التحقق فورًا.

وأخيرًا، إذا كانت هناك أي أخطاء تحقق، فستُعرض عبر {!!error?.message && {error.message}}، حيث يحتوي error?.message على رسالة خطأ التحقق كما عرّفناها في الـ schema الخاص بـ zod.

إرسال النموذج مع 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 على معلومات مفصلة عن كل الحقول التي فشلت في التحقق. في هذا المثال نكتفي بطباعة هذه الأخطاء.

وفي حال كان في كل حقل خطأ، سيكون كائن الخطأ كالتالي:

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

تعرض كتلة الكود أدناه طريقة للتحقق المسبق اليدوي من بيانات النموذج باستخدام الدالة safeParse في Zod قبل حدث إرسال النموذج. ورغم أن التحقق من النموذج تتولاه أصلًا الدالة handleSubmit في React Hook Form، فإن التحقق المسبق يمنح المطورين تحكمًا أكبر في عملية التحقق.

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

لنحلل الكود أعلاه:

  • يُستخدم الحدث onPress في الزر Button لتنفيذ دالة تقوم بالتحقق المسبق قبل إرسال النموذج.

  • تُستخدم الدالة getValues من methods (التي توفرها React Hook Form) لاسترجاع القيم الحالية للنموذج.

  • تُمرَّر هذه القيم بعد ذلك إلى الدالة safeParse من signUpFormSchema (الـ schema الذي أنشأناه في zod في البداية). في هذه الخطوة يحدث التحقق المسبق في zod. وعلى عكس الدالة parse في zod، لا ترمي safeParse خطأ عند فشل التحقق، بل تعيد كائنًا يحتوي على القيمة المنطقية success، وكائن خطأ إذا فشل التحقق.

  • تتحقق عبارة شرطية مما إذا كانت result.success تساوي false (ما يعني أن التحقق فشل). إذا كانت كذلك، تُظهر تنبيهًا يعرض خطأ التحقق.

  • إذا كانت result.success تساوي true (ما يعني نجاح التحقق)، تُظهر تنبيهًا يقول إن التحقق نجح باستخدام zod.

ورغم أن هذا النهج قد يبدو زائدًا لأن handleSubmit في React Hook Form تتحقق أصلًا من النموذج باستخدام الـ schema المقدّم عبر zod، فإنه قد يكون مفيدًا في حالات معينة. فمثلًا، قد تريد تنفيذ إجراءات معينة فقط بعد التحقق اليدوي، أو قد تريد التحقق من مدخلات النموذج لحظيًا أثناء تعبئة المستخدم له. في مثل هذه الحالات يكون التحقق المسبق باستخدام الدالة safeParse في zod مفيدًا جدًا.

وهكذا يبدو كائن الخطأ في 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"
    }

إنه فعلًا كائن كبير، وقد يحتوي حتى على حقول لا نحتاج إليها في حالتنا. لحسن الحظ يوفر 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");
}

وسيبدو كائن الخطأ المنسّق كالتالي:

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

الكود النهائي

فيما يلي أحدث نسخة من الكود (من دون الاستيرادات والأنماط). إذا أردت رؤية الكود المصدري الكامل، فارجع إلى نهاية المقال.

// 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. أي أنك تستطيع تجربته بسهولة عبر رمز QR أدناه! (إذا لم يعمل رمز QR، فارجع إلى رابط الكود المصدري في نهاية المقال.)

الخلاصة

استكشفنا في هذا المقال كيف نستفيد بفعالية من الجمع بين React Hook Form وZod وTypeScript لإنشاء تحقق متين من النماذج في تطبيق React Native. ورأينا كيف تتيح لنا مرونة هذه المكتبات وقوتها كتابة كود نظيف وآمن من حيث الأنواع (type-safe) يستطيع التعامل مع متطلبات تحقق معقدة.

التكامل بين React Hook Form وZod يتيح لنا جني فوائد الاثنين معًا. تبسّط React Hook Form التعامل مع النماذج، وتحسّن إعادة العرض (re-rendering)، وتتضمن ميزات مثل إدارة حالة النموذج ومعالجة الأخطاء. ومن ناحية أخرى يوفر Zod طبقة أمان إضافية، فيتيح لنا تحديد نوع البيانات المسموح به لكل حقل وفرض هذه القواعد.

تذكّر أنه رغم استخدام التقنيات المعروضة هنا في سياق نموذج تسجيل بسيط، فإنها تنطبق على أي مدخلات مستخدم قائمة على النماذج في تطبيقات React Native. وباتباع هذه الاستراتيجيات يمكنك ضمان أن تكون نماذجك سهلة الاستخدام ومتينة وسهلة الصيانة، ما يؤدي إلى تجارب مستخدم أفضل وتطبيقات أكثر متانة.

رابط الكود المصدري الكامل