{"id":"l-rn-3-4","courseId":"react-native-apps","lang":"ar","kind":"lesson","summary":"ابنِ نموذج إضافة رحلة في Trailhead بحيث يعمل مع لوحة مفاتيح الهاتف، فينتقل بين الحقول، ويبقى ظاهرًا فوق لوحة المفاتيح، ويحفظ من النقرة الأولى، ويتحقّق من المدخلات برسائل خطأ واضحة لكل حقل.","html":"

النماذج هي المكان الذي تختلف فيه تطبيقات الجوّال عن الويب أكثر من أي مكان آخر. لوحة المفاتيح تغطّي نصف الشاشة، ولا يوجد مفتاح Tab، والنقرة الأولى على زرّ أحيانًا لا تفعل إلا إغلاق لوحة المفاتيح، والكتابة على الزجاج بطيئة لدرجة أن كل رسالة خطأ غير ضرورية تبدو شخصية. لنموذج “Log a hike” في Trailhead خمسة حقول: الاسم، والتاريخ، والمسافة، والمدّة، والملاحظات. وهكذا تجعله مريحًا.

\n

مسوّدة من النصوص الخام

\n

احفظ كل ما كتبه المستخدم في كائن واحد من النصوص، كما كُتب بالضبط. وحلّله حين تحتاج إلى أرقام، كما فعلت مع parseDistanceKm في القسم 1:

\n
src/app/new-hike.tsx
import { useRef, useState, type ComponentRef } from 'react';\nimport { TextInput } from 'react-native';\n\ntype Draft = { name: string; date: string; distance: string; duration: string; notes: string };\n\n// Today's date in the phone's time zone. toISOString() would give the UTC date,\n// which is already tomorrow (or still yesterday) for part of the day in most places.\nfunction localToday() {\n  const now = new Date();\n  const pad = (n: number) => String(n).padStart(2, '0');\n  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;\n}\n\nconst emptyDraft = (): Draft => ({ name: '', date: localToday(), distance: '', duration: '', notes: '' });\n\nexport default function NewHike() {\n  const [draft, setDraft] = useState<Draft>(emptyDraft);\n  const [submitted, setSubmitted] = useState(false);\n  const [touched, setTouched] = useState<Partial<Record<keyof Draft, boolean>>>({});\n  const distanceRef = useRef<ComponentRef<typeof TextInput>>(null);\n  const durationRef = useRef<ComponentRef<typeof TextInput>>(null);\n\n  const set = (field: keyof Draft) => (text: string) => setDraft((d) => ({ ...d, [field]: text }));\n  // …errors, save and JSX below\n}
\n

تعطي الدالة المساعدة set('distance') كل حقل onChangeText دون خمس دوال شبه متطابقة. وتخزين النصوص يعني أن “8,” تبقى “8,” أثناء الكتابة، بدلًا من أن تنهار إلى 8 أو NaN.

\n

التنقّل بين الحقول

\n

لا يوجد مفتاح Tab، فيقوم مفتاح الإدخال بالمهمّة. سمِّه باستخدام returnKeyType="next"، وحين يُضغط، ركّز على الحقل التالي عبر ref:

\n
TSX
<TextInput\n  value={draft.name}\n  onChangeText={set('name')}\n  placeholder=\"Ridge Loop\"\n  autoCapitalize=\"words\"\n  returnKeyType=\"next\"\n  submitBehavior=\"submit\"\n  onSubmitEditing={() => distanceRef.current?.focus()}\n  onBlur={() => setTouched((t) => ({ ...t, name: true }))}\n/>\n<TextInput\n  ref={distanceRef}\n  value={draft.distance}\n  onChangeText={set('distance')}\n  keyboardType=\"decimal-pad\"\n  returnKeyType=\"next\"\n  onSubmitEditing={() => durationRef.current?.focus()}\n  onBlur={() => setTouched((t) => ({ ...t, distance: true }))}\n/>
\n

يُبقي submitBehavior="submit" لوحة المفاتيح مفتوحة بينما ينتقل التركيز، فلا تومض مغلقةً ثم مفتوحةً من جديد. وفي الحقل الأخير استخدم returnKeyType="done" ودعه يرسل النموذج. وتنبيه صريح: لوحات المفاتيح الرقمية على iOS ليس فيها مفتاح إدخال أصلًا، فينقر المستخدمون على الحقل التالي أو على زرّ في شريط أدوات. هذا طبيعي، وسبب آخر لعدم الاعتماد على لوحة المفاتيح وحدها.

\n

إبقاء الحقول فوق لوحة المفاتيح

\n

حين تنفتح لوحة المفاتيح، تستقرّ فوق تطبيقك. والحقل القريب من الأسفل (الملاحظات) يختفي خلفها. الإصلاح المعتاد يغلّف النموذج بـ KeyboardAvoidingView ويضع ScrollView بداخله:

\n
TSX
import { KeyboardAvoidingView, Platform, ScrollView } from 'react-native';\n\n<KeyboardAvoidingView style={{ flex: 1 }} behavior={Platform.OS === 'ios' ? 'padding' : undefined}>\n  <ScrollView\n    contentContainerStyle={{ padding: 16, gap: 16 }}\n    keyboardShouldPersistTaps=\"handled\"\n    keyboardDismissMode=\"on-drag\"\n  >\n    {/* fields and the Save button */}\n  </ScrollView>\n</KeyboardAvoidingView>
\n

على iOS، تضيف padding حشوًا سفليًا يساوي ارتفاع لوحة المفاتيح، فينكمش الـ ScrollView ويمكن تمرير الحقل المركّز عليه إلى منطقة الرؤية. أما على Android فعادةً ما تتغيّر أبعاد النافذة لاستيعاب لوحة المفاتيح أصلًا، لذا فإن undefined هي القيمة الموصى بها. ويغلق keyboardDismissMode="on-drag" لوحة المفاتيح حين يمرّر المستخدم، وهذا يبدو طبيعيًا.

\n\n

وللنماذج الطويلة ذات الحقول الكثيرة، توصي وثائق Expo بمكتبة react-native-keyboard-controller، التي يمرّر الـ KeyboardAwareScrollView الخاص بها الحقل المركّز عليه إلى منطقة الرؤية تلقائيًا؛ ويضيف KeyboardToolbar من المكتبة نفسها فوق لوحة المفاتيح أزرارًا للسابق والتالي والإنهاء. تحتاج إلى development build، وهو ما سيحصل عليه Trailhead في القسم 4.

\n

كلمة عن التواريخ

\n

تحتفظ مسوّدة Trailhead بالتاريخ نصًّا بصيغة YYYY-MM-DD، قيمته الافتراضية تاريخ اليوم، لأن معظم الرحلات تُسجَّل في اليوم نفسه. لكن كتابة التواريخ على لوحة مفاتيح الهاتف مزعجة، لذا تعرض تطبيقات الإنتاج منتقي التاريخ الخاص بالمنصّة: عجلة أو تقويم على iOS، ونافذة حوار على Android. تغلّف حزمة المجتمع @react-native-community/datetimepicker الاثنين معًا، وهي مثال جيد على component يختلف سلوكه بين المنصّتين بما يكفي لتريد معه الملفات الخاصة بكل منصّة من القسم 2.

\n

تحقّق لا يُزعج

\n

احفظ القواعد في دالة نقية: المسوّدة تدخل، والأخطاء تخرج. والكائن الفارغ يعني أن المدخلات صالحة.

\n
src/lib/validateHike.ts
export function validateHike(d: Draft) {\n  const errors: Partial<Record<keyof Draft, string>> = {};\n  if (!d.name.trim()) errors.name = 'Give the hike a name.';\n  if (parseDistanceKm(d.distance) === null) errors.distance = 'Enter a distance in km, like 8.4.';\n  return errors;\n}
\n

ثم قرّر متى تعرض كل رسالة. عرض الأخطاء من أول ضغطة مفتاح يعاقب الناس لأنهم لم ينتهوا من الكتابة. وانتظار نافذة تنبيه بعد Save يُخفي النموذج خلف قائمة يجب أن يحفظوها. النمط الذي ينجح: اعرض خطأ الحقل بعد أن يغادره المستخدم (touched) أو يضغط Save (submitted)، بجوار الحقل، وأبقِه حيًّا من تلك اللحظة فيختفي لحظة إصلاحه.

\n
TSX
const errors = validateHike(draft);\nconst show = (field: keyof Draft) => (submitted || touched[field]) && errors[field];\n\nfunction save() {\n  setSubmitted(true);\n  if (Object.keys(errors).length > 0) return;\n  dispatch({ type: 'added', hike: toHike(draft) });\n  router.back();\n}\n\n// under the distance input:\n{show('distance') ? <Text style={{ color: '#b42318' }}>{errors.distance}</Text> : null}
\n

لمستان لإمكانية الوصول تكلّف كلٌّ منهما سطرًا واحدًا: أعطِ كل حقل accessibilityLabel يطابق تسميته المرئية، وأبقِ نص الخطأ تحت حقله مباشرة ليصل إليه قارئ الشاشة بعده.

\n

تحوّل toHike المسوّدة الصالحة إلى Hike حقيقي (تحلّل الأرقام وتولّد معرّفًا). وبعد الحفظ، يعيد router.back() المستخدم إلى السجلّ، حيث تكون الرحلة الجديدة في الأعلى أصلًا لأن الـ reducer وضعها هناك.

\n

يفتح النموذج حاليًا شاشةً عادية مُضافة إلى الـ stack. في الدرس التالي ستعرضه بوصفه modal، وتحمي الشاشات خلف تسجيل الدخول، وتسمح للروابط بفتح Trailhead على رحلة محدّدة.

\n","toc":[{"id":"sec-1","text":"مسوّدة من النصوص الخام","level":2},{"id":"sec-2","text":"التنقّل بين الحقول","level":2},{"id":"sec-3","text":"إبقاء الحقول فوق لوحة المفاتيح","level":2},{"id":"sec-4","text":"كلمة عن التواريخ","level":2},{"id":"sec-5","text":"تحقّق لا يُزعج","level":2}],"takeaways":["احفظ مسوّدة النموذج نصوصًا خامًا في كائن state واحد، ولا تحلّلها وتتحقّق منها إلا حين تحتاج إلى النتيجة.","اربط الحقول ببعضها باستخدام returnKeyType="next" والـ refs، فينقلك مفتاح الإدخال إلى الحقل التالي بدلًا من إغلاق لوحة المفاتيح.","غلّف النموذج بـ KeyboardAvoidingView مع behavior="padding" على iOS، وأعطِ الـ ScrollView الداخلي keyboardShouldPersistTaps="handled".","تحقّق من المدخلات في دالة نقية تُرجع كائن أخطاء، واعرض كل خطأ بجوار حقله بعد أول محاولة حفظ أو بعد مغادرة الحقل."],"further":[{"title":"Keyboard handling","url":"https://docs.expo.dev/guides/keyboard-handling/"},{"title":"KeyboardAvoidingView","url":"https://reactnative.dev/docs/keyboardavoidingview"},{"title":"ScrollView keyboardShouldPersistTaps","url":"https://reactnative.dev/docs/scrollview#keyboardshouldpersisttaps"}],"quiz":[{"q":"

يقول المستخدمون إنهم مضطرون للنقر على Save مرتين في نموذج Trailhead حين تكون لوحة المفاتيح مفتوحة. النقرة الأولى تغلق لوحة المفاتيح فقط. ما الإصلاح؟

","options":[{"text":"استدعِ Keyboard.dismiss() في بداية دالة الحفظ.","why":"دالة الحفظ لم تعمل أصلًا في النقرة الأولى، فالكود داخلها لا يستطيع المساعدة."},{"text":"اضبط keyboardShouldPersistTaps="handled" على الـ ScrollView الذي يحوي النموذج.","why":"صحيح. افتراضيًا، النقرة خارج الحقل المركّز عليه أثناء ظهور لوحة المفاتيح تغلق لوحة المفاتيح فقط؛ أما handled فتسمح للنقرات على الأزرار بالمرور."},{"text":"انقل زرّ Save فوق الحقول.","why":"النقرة تُبتلع أينما كان الزر، ما دام داخل ذلك الـ ScrollView."}],"answer":1},{"q":"

على iOS، يختفي حقل الملاحظات في أسفل النموذج خلف لوحة المفاتيح حين يُركَّز عليه. ما الإعداد المعتاد لإصلاح ذلك؟

","options":[{"text":"KeyboardAvoidingView مع behavior="padding" وflex: 1 حول الـ ScrollView الخاص بالنموذج.","why":"صحيح. يضيف الـ view حشوًا سفليًا يساوي ارتفاع لوحة المفاتيح، فينكمش الـ ScrollView ويستطيع تمرير الحقل إلى منطقة الرؤية."},{"text":"position: 'absolute' على حقل الملاحظات مع zIndex مرتفع.","why":"لوحة المفاتيح نافذة نظام فوق تطبيقك؛ ولا يوجد zIndex يضع الـ view الخاص بك فوقها."},{"text":"اضبط autoFocus على حقل الملاحظات.","why":"هذا يفتح لوحة المفاتيح عند التركيب، فيحدث التداخل أبكر، ولا يختفي."}],"answer":0},{"q":"

متى يجب أن يعرض Trailhead الخطأ “Distance must be a number” تحت حقل المسافة؟

","options":[{"text":"مع كل ضغطة مفتاح منذ الحرف الأول.","why":"كتابة “8,” في الطريق إلى “8,4” غير صالحة للحظة. والأخطاء أثناء الكتابة مجرّد ضجيج."},{"text":"في نافذة تنبيه فقط بعد Save، تسرد كل الأخطاء دفعة واحدة.","why":"نافذة التنبيه تُخفي النموذج، ويضطر المستخدم إلى تذكّر القائمة بعد إغلاقها."},{"text":"بعد أن يغادر المستخدم الحقل أو يضغط Save، بجوار الحقل، مع تحديثه حيًّا بعد ظهوره.","why":"صحيح. انتظر حتى ينتهي المستخدم من الحقل، ثم أبقِ الرسالة متزامنة بينما يصلحها."}],"answer":2},{"q":"

كيف تجعل مفتاح الإدخال في حقل الاسم ينقل التركيز إلى حقل المسافة؟

","options":[{"text":"tabIndex={2} على حقل المسافة.","why":"هذه سمة ويب. لوحات مفاتيح الهواتف ليس فيها ترتيب Tab يمكن ضبطه."},{"text":"returnKeyType="next" على حقل الاسم وautoFocus على حقل المسافة.","why":"autoFocus يعمل مرة واحدة عند التركيب، لا حين يُضغط مفتاح الإدخال في حقل الاسم."},{"text":"لا شيء؛ لوحات مفاتيح الجوّال تنتقل إلى الحقل التالي تلقائيًا.","why":"لا تفعل. دون معالجة ذلك، يغلق مفتاح الإدخال لوحة المفاتيح في الحقل ذي السطر الواحد."},{"text":"returnKeyType="next" مع onSubmitEditing={() => distanceRef.current?.focus()}، وref على حقل المسافة.","why":"صحيح. تسمية المفتاح تقول Next، والمعالج ينقل التركيز."}],"answer":3}],"exercise":{"kind":"web","mode":"js","starter":{"js":"// Return an object with one message per invalid field. {} means the draft is valid.\n// `today` is the current date as 'YYYY-MM-DD', passed in so the function stays pure.\nfunction validateHikeForm(draft, today) {\n const errors = {};\n if (draft.name === '') errors.name = 'Give the hike a name.';\n return errors;\n}\n\nconst draft = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' };\nconsole.log(validateHikeForm(draft, '2026-10-05'));\n"},"solution":{"js":"function isRealDate(text) {\n if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(text)) return false;\n const [y, m, d] = text.split('-').map(Number);\n const date = new Date(Date.UTC(y, m - 1, d));\n return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;\n}\n\nfunction validateHikeForm(draft, today) {\n const errors = {};\n const name = draft.name.trim();\n if (!name) errors.name = 'Give the hike a name.';\n else if (name.length > 60) errors.name = 'Keep the name under 60 characters.';\n\n if (!isRealDate(draft.date)) errors.date = 'Use a real date like 2026-10-04.';\n else if (draft.date > today) errors.date = \"That date hasn't happened yet.\";\n\n const cleaned = draft.distance.trim().replace(',', '.');\n const km = Number(cleaned);\n if (!/^\\d+(\\.\\d+)?$/.test(cleaned) || km <= 0 || km > 200) errors.distance = 'Enter a distance in km, like 8.4.';\n\n const duration = draft.duration.trim();\n if (duration && (!/^\\d+$/.test(duration) || Number(duration) < 1 || Number(duration) > 1440)) {\n errors.duration = 'Enter whole minutes between 1 and 1440.';\n }\n\n if (draft.notes.length > 500) errors.notes = 'Notes are limited to 500 characters.';\n return errors;\n}\n\nconst draft = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' };\nconsole.log(validateHikeForm(draft, '2026-10-05'));\n"},"checks":[{"id":"valid-draft","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return typeof validateHikeForm === 'function' && keys({}) === '' && keys({ duration: '135', notes: 'Windy.' }) === '';"},{"id":"name","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return keys({ name: ' ' }) === 'name' && keys({ name: 'x'.repeat(61) }) === 'name';"},{"id":"date","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return keys({ date: '04/10/2026' }) === 'date' && keys({ date: '2026-02-30' }) === 'date' && keys({ date: '2026-10-06' }) === 'date' && keys({ date: '2026-10-05' }) === '';"},{"id":"distance","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return keys({ distance: '' }) === 'distance' && keys({ distance: 'far' }) === 'distance' && keys({ distance: '0' }) === 'distance' && keys({ distance: '12.5' }) === '';"},{"id":"duration","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return keys({ duration: '2h' }) === 'duration' && keys({ duration: '0' }) === 'duration' && keys({ duration: '1441' }) === 'duration';"},{"id":"several","test":"const ok = { name: 'Ridge Loop', date: '2026-10-04', distance: '8,4', duration: '', notes: '' }; const T = '2026-10-05'; const keys = (d) => Object.keys(validateHikeForm({ ...ok, ...d }, T)).sort().join(); return keys({ name: '', distance: 'x', notes: 'n'.repeat(501) }) === 'distance,name,notes';"}],"title":"تحقّق من نموذج إضافة رحلة","prompt":"

اكتب validateHikeForm(draft, today) لنموذج Trailhead. يحمل draft النصوص الخام التي كتبها المستخدم: name وdate وdistance وduration وnotes. وtoday هو تاريخ اليوم بصيغة YYYY-MM-DD. أرجع كائنًا فيه رسالة لـ كل حقل غير صالح (أي نصّ غير فارغ)؛ وأرجع {} حين يكون كل شيء صالحًا.

\n\n","hints":["ابنِ errors حقلًا حقلًا بعبارات if؛ وكل قاعدة تفشل تضبط errors.field = '…'.","نصوص التاريخ بصيغة ISO تُقارَن بشكل صحيح كنصوص، فـ draft.date > today تعني «في المستقبل». ولرفض 2026-02-30، ابنِ new Date(Date.UTC(y, m - 1, d)) وتحقّق أن السنة والشهر واليوم تعود دون تغيير.","للمسافة، وحّد الصيغة أولًا (trim، والفاصلة إلى نقطة)، ثم اختبرها مقابل /^\\d+(\\.\\d+)?$/ قبل التحقّق من النطاق."],"explanation":"

إبقاء التحقّق في دالة نقية تحوّل المسوّدة إلى كائن أخطاء يعني أن النموذج لا يحتاج إلا إلى Object.keys(errors).length === 0 ليقرّر هل يحفظ، وأن كل حقل يستطيع البحث عن رسالته الخاصة. وتمرير today بدلًا من استدعاء new Date() داخل الدالة يجعلها حتمية النتائج، فلا تنكسر الاختبارات عند منتصف الليل. وفحص الذهاب والإياب عبر Date.UTC طريقة مختصرة لرفض التواريخ المستحيلة، التي كان Date في JavaScript سيدحرجها بصمت إلى شهر مارس.

\n","checkLabels":{"valid-draft":"المسوّدة الكاملة المعقولة ليس فيها أخطاء","name":"تُرفض الأسماء الفارغة والطويلة جدًا","date":"تُرفض التواريخ سيئة الصيغة والمستحيلة والمستقبلية","distance":"تُرفض المسافات المفقودة وغير الرقمية والصفرية","duration":"المدّة المملوءة يجب أن تكون دقائق كاملة من 1 إلى 1440","several":"يُبلَّغ عن عدّة حقول غير صالحة دفعة واحدة"}},"words":636,"readMinutes":4}