{"id":"l-rn-4-1","courseId":"react-native-apps","lang":"ar","kind":"lesson","summary":"حمّل كتالوج الدروب في Trailhead من خادم باستخدام fetch، وصمّم حالات التحميل والخطأ والفراغ والنجاح صراحةً، وألغِ الطلبات القديمة، وتعامل مع الشبكات المتقلّبة التي تعيش عليها الهواتف.","html":"

حتى الآن، عاشت بيانات Trailhead على الهاتف. أما الميزة التالية، كتالوج الدروب القريبة منك، فتأتي من خادم. على حاسوب محمول متصل بشبكة Wi-Fi المكتب، الطلب مجرّد إجراء شكلي. أما على هاتف عند بداية درب وفيه خطّ إشارة واحد، فهو أبطأ ما يفعله تطبيقك وأقلّه موثوقية: تستغرق الطلبات ثواني، أو تفشل في منتصفها، أو لا تعود أبدًا. والتصميم لهذا الواقع هو معظم العمل.

\n

أربع حالات، وقيمة واحدة

\n

كل شاشة تحمّل بيانات لها أربع حالات على الأقل يمكن أن يراها المستخدم: التحميل (loading)، والخطأ (error)، والفراغ (empty: اكتمل التحميل ولا يوجد شيء)، والنجاح (success). مثّلها بقيمة واحدة، فلا يمكن أن تحدث تركيبات مستحيلة:

\n
src/lib/types.ts
export type Trail = { id: string; name: string; lengthKm: number; difficulty: 'easy' | 'moderate' | 'hard' };\n\nexport type Load<T> =\n  | { status: 'loading' }\n  | { status: 'error'; message: string }\n  | { status: 'success'; data: T };
\n

الفراغ ليس حالة منفصلة؛ إنه نجاح بصفر عناصر، والشاشة تقرّر كيف تعرضه.

\n
\n تبدأ الشاشة في حالة loading. الاستجابة الناجحة تنقلها إلى success، التي تعرض القائمة أو حالة الفراغ. والفشل ينقلها إلى error، وزرّ إعادة المحاولة يعيدها إلى loading. والسحب للتحديث ينقلها من success إلى loading من جديد.\n \n loading\n \n success\n القائمة أو حالة الفراغ\n \n error\n رسالة + إعادة المحاولة\n \n استجابة ok\n \n فشل\n \n إعادة\n \n تحديث\n
الطلب ينتقل بين حالات صريحة
\n

الجلب مع التنظيف

\n
src/app/(tabs)/explore.tsx
import { useCallback, useEffect, useState } from 'react';\nimport { ActivityIndicator, FlatList, Pressable, Text, View } from 'react-native';\nimport type { Load, Trail } from '../../lib/types';\n\nconst API = process.env.EXPO_PUBLIC_API_URL;\n\nasync function getTrails(signal: AbortSignal): Promise<Trail[]> {\n  const res = await fetch(`${API}/trails?near=current`, { signal });\n  if (!res.ok) throw new Error(`Server responded ${res.status}`);\n  return res.json();\n}\n\nexport default function Explore() {\n  const [state, setState] = useState<Load<Trail[]>>({ status: 'loading' });\n  const [attempt, setAttempt] = useState(0);\n  const retry = useCallback(() => setAttempt((n) => n + 1), []);\n\n  useEffect(() => {\n    const controller = new AbortController();\n    setState({ status: 'loading' });\n    getTrails(controller.signal)\n      .then((data) => setState({ status: 'success', data }))\n      .catch(() => {\n        if (controller.signal.aborted) return;\n        setState({ status: 'error', message: 'Could not load trails. Check your connection and try again.' });\n      });\n    return () => controller.abort();\n  }, [attempt]);\n\n  if (state.status === 'loading') return <ActivityIndicator style={{ flex: 1 }} size=\"large\" />;\n\n  if (state.status === 'error') {\n    return (\n      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center', gap: 12, padding: 24 }}>\n        <Text style={{ textAlign: 'center' }}>{state.message}</Text>\n        <Pressable onPress={retry} accessibilityRole=\"button\"><Text>Try again</Text></Pressable>\n      </View>\n    );\n  }\n\n  return (\n    <FlatList\n      data={state.data}\n      keyExtractor={(t) => t.id}\n      renderItem={({ item }) => <Text style={{ padding: 16 }}>{item.name} · {item.lengthKm} km</Text>}\n      ListEmptyComponent={<Text style={{ padding: 24 }}>No trails within 50 km. Try a wider search.</Text>}\n    />\n  );\n}
\n

ثلاثة تفاصيل تحمل الثقل. يُفحص res.ok يدويًا، لأن fetch يعامل الـ 500 على أنه توصيل ناجح لأخبار سيئة. ويلغي الـ AbortController الطلب في دالة التنظيف، فمغادرة الشاشة (أو إعادة المحاولة) لا تسمح أبدًا لاستجابة قديمة بالكتابة فوق استجابة حديثة. ورسالة الخطأ تخبر المستخدم بما يفعل، بدلًا من طباعة TypeError: Network request failed.

\n

يأتي EXPO_PUBLIC_API_URL من ملف .env. المتغيّرات التي تبدأ بـ EXPO_PUBLIC_ تُدرج مباشرة في حزمة JavaScript، وهذا يعني أيضًا أنها قابلة للقراءة من أي أحد يفكّ حزمة تطبيقك. ضع فيها العناوين، ولا تضع المفاتيح السرّية أبدًا.

\n\n

السحب للتحديث والشبكات البطيئة

\n

يتوقّع المستخدمون أن يسحبوا القائمة إلى الأسفل لإعادة تحميلها. يدعم FlatList ذلك بخاصّيتين:

\n
TSX
<FlatList\n  // …\n  refreshing={refreshing}\n  onRefresh={async () => {\n    setRefreshing(true);\n    try { setState({ status: 'success', data: await getTrails(new AbortController().signal) }); }\n    catch { /* keep the old list and show a short \"Couldn't refresh\" message */ }\n    finally { setRefreshing(false); }\n  }}\n/>
\n

يُبقي التحديث القائمة القديمة ظاهرة أثناء التحميل، وهذا ألطف من مؤشّر التحميل بملء الشاشة في التحميل الأول. وإن فشل التحديث، فاحتفظ بالبيانات القديمة واعرض رسالة قصيرة، بدلًا من استبدال قائمة سليمة تمامًا بشاشة خطأ.

\n

والشبكات المتقلّبة حجّة أيضًا لصالح إعادة المحاولة التلقائية مع تأخير يتزايد بين المحاولات (ثانية، ثم ثانيتان، ثم أربع)، فيتعافى التطبيق وحده من انقطاع قصير في الإشارة. لا تُعِد المحاولة إلا لما يمكن أن ينجح لاحقًا: انتهاء المهلة أو 503 قد ينجحان، أما 404 أو 401 فلن ينجحا، لذا فالفشل السريع ألطف. ستكتب هذه الدالة المساعدة في التمرين.

\n

غياب الاتصال حالة طبيعية، لا خطأ

\n

في تطبيق للمشي الجبلي، غياب الإشارة هو الوضع المتوقّع لساعات متواصلة. تعامل معه على هذا الأساس. اعرض آخر قائمة حمّلتها، مع شريط هادئ يذكر وقت آخر تحديث، بدلًا من شاشة خطأ. ودع المستخدمين يواصلون تسجيل الرحلات، واحفظها على الجهاز، وأرسلها حين يعود الاتصال. تخبرك حزمة المجتمع @react-native-community/netinfo هل الجهاز متصل، وتُعلمك حين يتغيّر ذلك، وتلك هي اللحظة لإعادة محاولة الأعمال المؤجّلة.

\n

لا شيء من ذلك يحتاج إلى أن يكون ذكيًا من اليوم الأول. المهم هو القرار: لكل شاشة، ماذا يرى المستخدم دون شبكة؟ اكتب الإجابة قبل أن تكتب الـ fetch، وصمّم حالات الفراغ والخطأ وغياب الاتصال بالعناية نفسها التي تصمّم بها المسار السعيد.

\n

متى تستخدم مكتبة للبيانات

\n

الكود أعلاه جيد لشاشة واحدة. أما في تطبيق حقيقي فستكرّره في كل مكان، وسيبقى ينقصك التخزين المؤقت (عُد إلى شاشة فترى البيانات فورًا)، ومنع تكرار الطلبات، وإعادة الجلب في الخلفية، وإعادة المحاولة. تتولّى TanStack Query كل ذلك عبر useQuery، وتتضمّن وثائقها الإعداد الصغير الخاص بـ React Native الذي يعيد الجلب حين يعود التطبيق إلى الواجهة. تعلّم النسخة اليدوية أولًا لتعرف ما تفعله المكتبة، ثم استخدم المكتبة في بيئة الإنتاج.

\n

التالي: بيانات يجب أن تصمد دون أي شبكة على الإطلاق، مخزّنة على الجهاز.

\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":["مثّل الطلب بقيمة حالة واحدة (loading أو error أو success) بدلًا من عدّة قيم منطقية قد يناقض بعضها بعضًا.","fetch لا يرفض (reject) إلا عند فشل الشبكة؛ تحقّق من response.ok بنفسك لاستجابات 404 و500.","ألغِ الطلبات الجارية في دالة التنظيف الخاصة بالـ effect، لأن المستخدمين يغادرون الشاشات قبل أن تنتهي الطلبات البطيئة.","كل قائمة تحمّل بيانات تحتاج إلى أربع حالات مصمّمة، منها حالة فراغ وحالة خطأ مع زرّ لإعادة المحاولة.","على الهاتف، localhost هو الهاتف نفسه؛ وجّه الـ development builds إلى عنوان حاسوبك على الشبكة أو إلى API منشور."],"further":[{"title":"Networking","url":"https://reactnative.dev/docs/network"},{"title":"Using fetch","url":"https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch"},{"title":"RefreshControl","url":"https://reactnative.dev/docs/refreshcontrol"}],"quiz":[{"q":"

يُرجع الـ API الخاص بـ Trailhead الاستجابة 404 Not Found لدرب محذوف. ماذا يفعل await fetch(url)؟

","options":[{"text":"يرمي خطأ، فتتعامل معه كتلة catch.","why":"لا يرفض fetch إلا حين لا تصل أي استجابة على الإطلاق (عدم اتصال، فشل DNS، إلغاء). والـ 404 استجابة."},{"text":"يُحَلّ (resolve) باستجابة قيمة ok فيها false وstatus تساوي 404، ويجب أن تتحقّق منها.","why":"صحيح. تحقّق بـ if (!res.ok) وارمِ خطأ أو تعامل معه بنفسك."},{"text":"يُحَلّ بالقيمة undefined.","why":"يُحَلّ fetch دائمًا بكائن Response حين يجيب الخادم، أيًّا كان رمز الحالة."}],"answer":1},{"q":"

يفتح مستخدم شاشة تفاصيل درب ثم يعود فورًا. ينتهي الطلب بعد ثانيتين ويستدعي setState. ما الذي كان يجب أن يفعله الـ effect؟

","options":[{"text":"لا شيء؛ يتجاهل React Native تحديثات الـ state من الشاشات المُزالة، فالأمر غير ضار.","why":"يُسقَط التحديث، لكن الطلب استهلك بيانات وبطارية، ويمكن لاستجابة سابقة بطيئة أن تكتب فوق استجابة أحدث حين يتغيّر المعرّف."},{"text":"غلّف الاستدعاء بـ setTimeout ليعمل بعد التنقّل.","why":"تأخير الطلب لا يمنعه من الانتهاء بعد أن تختفي الشاشة."},{"text":"أنشأ AbortController واستدعى controller.abort() في دالة التنظيف.","why":"صحيح. الإلغاء يوقف الطلب عند إزالة الشاشة أو حين يتغيّر المعرّف، فلا تصل الاستجابات القديمة أبدًا."}],"answer":2},{"q":"

أيّ شكل للـ state يناسب شاشة الكتالوج في Trailhead أكثر؟

","options":[{"text":"{ status: 'loading' } | { status: 'error'; error: string } | { status: 'success'; trails: Trail[] }","why":"صحيح. لا توجد إلا التركيبات الصالحة، وتجبرك TypeScript على التعامل مع كلٍّ منها."},{"text":"isLoading وhasError وtrails في ثلاثة استدعاءات useState منفصلة.","why":"لا شيء يمنع أن تكون isLoading وhasError صحيحتين معًا، أو أن تظهر دروب قديمة بجوار خطأ."},{"text":"trails: Trail[] | null، حيث null تعني التحميل أو الخطأ.","why":"يبدو التحميل والخطأ متماثلين، فلا تستطيع الشاشة عرض الرسالة الصحيحة."},{"text":"مصفوفة trails واحدة تبدأ فارغة.","why":"المصفوفة الفارغة لا تميّز بين «ما زال يُحمّل» و«لا دروب قريبة»، وهما شاشتان مختلفتان جدًا."}],"answer":0}],"exercise":{"kind":"web","mode":"js","starter":{"js":"const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\n// Run task(attempt). Retry failures with a doubling delay; give up fast on errors\n// that can't succeed later. `sleep` is injectable so tests don't really wait.\nasync function withRetry(task, { retries = 2, baseDelayMs = 1000, sleep = wait } = {}) {\n return task(1);\n}\n\n// Demo: fails twice with a 503, then succeeds.\nlet calls = 0;\nconst flaky = async () => {\n calls += 1;\n if (calls < 3) throw Object.assign(new Error('Service unavailable'), { status: 503 });\n return ['Ridge Loop', 'Lake Trail'];\n};\nwithRetry(flaky, { baseDelayMs: 10 }).then((v) => console.log('got', v, 'after', calls, 'calls'), (e) => console.log('failed:', e.message));\n"},"solution":{"js":"const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nfunction isRetryable(error) {\n const status = error && error.status;\n if (typeof status !== 'number') return true; // network failure, timeout\n if (status === 408 || status === 429) return true;\n return status < 400 || status >= 500;\n}\n\nasync function withRetry(task, { retries = 2, baseDelayMs = 1000, sleep = wait } = {}) {\n for (let attempt = 1; ; attempt++) {\n try {\n return await task(attempt);\n } catch (error) {\n if (attempt > retries || !isRetryable(error)) throw error;\n await sleep(baseDelayMs * 2 ** (attempt - 1));\n }\n }\n}\n\nlet calls = 0;\nconst flaky = async () => {\n calls += 1;\n if (calls < 3) throw Object.assign(new Error('Service unavailable'), { status: 503 });\n return ['Ridge Loop', 'Lake Trail'];\n};\nwithRetry(flaky, { baseDelayMs: 10 }).then((v) => console.log('got', v, 'after', calls, 'calls'), (e) => console.log('failed:', e.message));\n"},"checks":[{"id":"returns-value","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); const v = await withRetry(async () => 'ok', { sleep }); return v === 'ok' && delays.length === 0;"},{"id":"retries-then-succeeds","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); let n = 0; const v = await withRetry(async (attempt) => { n++; if (attempt < 3) throw fail(503); return 'done'; }, { retries: 2, baseDelayMs: 100, sleep }); return v === 'done' && n === 3;"},{"id":"backoff","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); let n = 0; try { await withRetry(async () => { n++; throw new Error('offline'); }, { retries: 3, baseDelayMs: 100, sleep }); } catch {} return n === 4 && delays.join() === '100,200,400';"},{"id":"gives-up","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); let caught; try { await withRetry(async () => { throw fail(500); }, { retries: 1, baseDelayMs: 1, sleep }); } catch (e) { caught = e; } return caught instanceof Error && caught.status === 500;"},{"id":"no-retry-4xx","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); let n = 0; let caught; try { await withRetry(async () => { n++; throw fail(404); }, { retries: 3, sleep }); } catch (e) { caught = e; } return n === 1 && caught?.status === 404 && delays.length === 0;"},{"id":"retry-429","test":"const delays = []; const sleep = async (ms) => { delays.push(ms); }; const fail = (status) => Object.assign(new Error('x' + status), { status }); let n = 0; const v = await withRetry(async () => { n++; if (n === 1) throw fail(429); if (n === 2) throw fail(408); return 'ok'; }, { retries: 2, baseDelayMs: 50, sleep }); return v === 'ok' && n === 3 && delays.join() === '50,100';"}],"title":"أعِد محاولة الطلبات المتعثّرة مع تأخير متزايد","prompt":"

اكتب withRetry(task, { retries, baseDelayMs, sleep }) لاستدعاءات الـ API في Trailhead على إشارة الجبال الضعيفة.

\n\n

انتظر دائمًا باستخدام الـ sleep المعطاة لك، لكي تستطيع الفحوص تسجيل التأخيرات.

\n","hints":["حلقة for (let attempt = 1; ; attempt++) وبداخلها try { return await task(attempt); } catch (error) { … } أبسط قراءةً من التعاود.","في الـ catch، استسلم (throw error) حين تكون attempt > retries أو حين لا يكون الخطأ قابلًا لإعادة المحاولة؛ وإلا await sleep(baseDelayMs * 2 ** (attempt - 1)).","اكتب isRetryable(error) منفصلة: لا status رقمية → true؛ 408 أو 429 → true؛ وإلا فأعِد المحاولة فقط حين تكون status >= 500."],"explanation":"

يمنح التأخير المتزايد أُسّيًا (exponential backoff) انقطاعَ الإشارة القصير وقتًا للتعافي دون إغراق خادم يعاني، وتصنيف الأخطاء يمنع التطبيق من إعادة محاولة طلبات لن تنجح أبدًا: فالـ 404 أو 401 يفشل بالطريقة نفسها ثلاث مرات، لكن أبطأ. وحقن sleep قرار تصميمي صغير بعائد كبير: بيئة الإنتاج تستخدم مؤقّتًا حقيقيًا، والاختبارات تعمل فورًا مع التحقّق من التأخيرات بدقّة. ومكتبات مثل TanStack Query تطبّق السياسة نفسها نيابةً عنك.

\n","checkLabels":{"returns-value":"المهمّة الناجحة تُرجع قيمتها دون انتظار","retries-then-succeeds":"المهمّة التي تفشل مرتين ثم تنجح تُرجع قيمتها","backoff":"تتضاعف التأخيرات بين المحاولات (100، 200، 400)","gives-up":"بعد المحاولة الأخيرة، يُرمى آخر خطأ","no-retry-4xx":"يُرمى الـ 404 فورًا دون إعادة محاولة","retry-429":"تُعاد محاولة استجابات 429 و408"}},"words":578,"readMinutes":3}