{"id":"l-rn-3-5","courseId":"react-native-apps","lang":"ar","kind":"lesson","summary":"اعرض نموذج إضافة رحلة في Trailhead بوصفه modal، وأبقِ المستخدمين غير المسجّلين على شاشة تسجيل الدخول باستخدام Stack.Protected، وافتح رحلات محدّدة من الـ deep links، مع فهم كيف تُطابَق الـ URLs مع ملفات المسارات.","html":"

ثلاثة مواقف لا تناسب نمط «أضف شاشة» الذي استخدمته حتى الآن. تسجيل رحلة مهمّة قصيرة يبدؤها المستخدم وينهيها، فيجب أن تبدو منفصلة عن التصفّح. وبعض الشاشات يجب ألا توجد إلا للمستخدمين المسجّلين. ويجب أن ينفتح Trailhead على الرحلة الصحيحة حين ينقر أحدهم على رابط في تذكير أو رسالة. يتعامل Expo Router مع الثلاثة في ملف الـ layout.

\n

نموذج إضافة رحلة بوصفه modal

\n

الـ modal شاشة تُعرض فوق السياق الحالي، وتنزلق عادةً من الأسفل. على iOS تظهر بطاقةً تبقى الشاشة السابقة مرئية خلفها، ويستطيع المستخدمون سحبها إلى الأسفل للإلغاء. اجعل النموذج modal بضبط طريقة عرضه في الـ Stack الجذري:

\n
src/app/_layout.tsx
<Stack>\n  <Stack.Screen name=\"(tabs)\" options={{ headerShown: false }} />\n  <Stack.Screen name=\"hikes/[id]\" options={{ title: 'Hike' }} />\n  <Stack.Screen name=\"new-hike\" options={{ presentation: 'modal', title: 'Log a hike' }} />\n</Stack>
\n

يبقى فتحه بـ router.push('/new-hike') (أو Link)؛ وإغلاقه بعد الحفظ بـ router.back()، الذي يُزيل الـ modal كأي شاشة. لا يملك Android ورقة على شكل بطاقة افتراضيًا، فيظهر الـ modal صفحةً بملء الشاشة بحركة مختلفة؛ لذا أعطِ النموذج زرّ Cancel ظاهرًا في headerLeft ليكون للمنصّتين مخرج واضح.

\n

حين يحوي النموذج مدخلات غير محفوظة، فإن سحبه بعيدًا يُضيّع ما كتبه المستخدم. في النماذج الطويلة، اطلب التأكيد قبل التجاهل باستخدام Alert عند Cancel؛ أما في نموذج قصير مثل نموذج Trailhead، فمسوّدة تُعاد كتابتها بسرعة مقايضة مقبولة.

\n

المسارات المحميّة

\n

يزامن Trailhead الرحلات مع حساب، لذا تتطلّب معظم الشاشات تسجيل الدخول. يغلّف Stack.Protected المسارات بشرط:

\n
src/app/_layout.tsx
import { Stack } from 'expo-router';\nimport { useSession } from '../state/session';\n\nexport default function RootLayout() {\n  const { isSignedIn, isLoading } = useSession();\n  if (isLoading) return null; // the splash screen is still showing\n\n  return (\n    <Stack>\n      <Stack.Protected guard={!isSignedIn}>\n        <Stack.Screen name=\"sign-in\" options={{ headerShown: false }} />\n      </Stack.Protected>\n\n      <Stack.Protected guard={isSignedIn}>\n        <Stack.Screen name=\"(tabs)\" options={{ headerShown: false }} />\n        <Stack.Screen name=\"hikes/[id]\" options={{ title: 'Hike' }} />\n        <Stack.Screen name=\"new-hike\" options={{ presentation: 'modal', title: 'Log a hike' }} />\n      </Stack.Protected>\n    </Stack>\n  );\n}
\n

حين يكون guard قيمته false، تصبح تلك المسارات غير متاحة: التنقّل إليها، بما في ذلك من deep link، يرسل المستخدم إلى أول شاشة متاحة بدلًا منها، وتُحذف أي مدخلات لها في السجلّ. تسجيل الدخول يقلب قيمة isSignedIn، فيُعاد الـ render للـ layout، وتظهر الشاشات المحميّة دون أن تستدعي router على الإطلاق. وتسجيل الخروج يفعل العكس، فيمسح أيضًا الـ back stack، فلا تستطيع إيماءة الرجوع كشف شاشة خاصة بالمستخدم المسجّل.

\n

useSession هو context مثل الذي بنيته قبل درسين. تغطّي isLoading اللحظة عند بدء التشغيل التي يكون فيها Trailhead ما زال يقرأ الـ token المحفوظ من التخزين الآمن (القسم 4)؛ ورسم لا شيء بينما شاشة البداية ظاهرة يتجنّب وميض صفحة تسجيل الدخول للمستخدمين المسجّلين أصلًا.

\n\n

الـ deep links

\n

الـ deep link (الرابط العميق) يفتح التطبيق على شاشة محدّدة. أعطِ Trailhead مخطّط URL (scheme) في app.json:

\n
app.json
{\n  \"expo\": {\n    \"name\": \"Trailhead\",\n    \"scheme\": \"trailhead\"\n  }\n}
\n

الآن يفتح trailhead://hikes/42 التطبيق ويرسم /hikes/42 بالـ Stack نفسه الذي بنيته، بما في ذلك زرّ رجوع إلى السجلّ. تحصل على هذا مجانًا من التوجيه المبني على الملفات: كل مسار له URL أصلًا. المخطّطات جزء من الإعدادات الأصلية للتطبيق، لذا اختبرها في development build؛ فلـ Expo Go مخطّطه الخاص. ومن الطرفية:

\n
Terminal
npx uri-scheme open trailhead://hikes/42 --ios\nnpx uri-scheme open trailhead://hikes/42 --android
\n

للمخطّطات المخصّصة نقطة ضعف: أي تطبيق يستطيع ادّعاء trailhead://. وللروابط التي تشاركها على الويب، استخدم الـ universal links (على iOS) والـ App Links (على Android)، التي تستخدم نطاق https:// الخاص بك وتتطلّب استضافة ملف تحقّق صغير عليه. يشرح دليل الروابط في Expo الاثنين خطوة بخطوة.

\n\n

كيف يختار الـ URL مساره

\n

حين يصل رابط، يقارن Expo Router مساره بكل ملف مسار. ومعرفة القواعد تُزيل التخمين:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
القاعدةمثال
المجموعات مثل (tabs) لا تضيف جزءًا(tabs)/stats.tsx يطابق /stats
index لا يضيف جزءًاsettings/index.tsx يطابق /settings
[name] يطابق جزءًا واحدًا بالضبطhikes/[id].tsx يطابق /hikes/42
[...name] يطابق جزءًا متبقّيًا أو أكثر، بوصفها مصفوفةtrails/[...path].tsx يطابق /trails/alps/mont-blanc
الثابت يتغلّب على الديناميكي، والديناميكي على الشامل/hikes/new يختار hikes/new.tsx بدلًا من hikes/[id].tsx
الـ query string تصبح params إضافية/hikes/42?units=mi يضيف units

هذا الترتيب هو سبب قدرتك على إضافة hikes/new.tsx بجوار hikes/[id].tsx بأمان. وفي التمرين ستكتب أداة المطابقة هذه بنفسك، وهي أسرع طريقة لكي لا تفاجئك مرة أخرى أبدًا.

\n

بهذا يكتمل التنقّل. أما القسم 4 فيصل Trailhead بالعالم الخارجي: خادم، وتخزين الجهاز، ومستشعراته.

\n","toc":[{"id":"sec-1","text":"نموذج إضافة رحلة بوصفه modal","level":2},{"id":"sec-2","text":"المسارات المحميّة","level":2},{"id":"sec-3","text":"الـ deep links","level":2},{"id":"sec-4","text":"كيف يختار الـ URL مساره","level":2}],"takeaways":["شاشة Stack مع presentation: 'modal' تنزلق إلى الأعلى كورقة على iOS؛ وأغلقها باستخدام router.back() بعد الحفظ.","يُخفي Stack.Protected مع guard المسارات حين يكون الشرط false، فلا يستطيع المستخدمون غير المسجّلين الوصول إليها، حتى من deep link.","الـ scheme في app.json يجعل trailhead://hikes/42 يفتح المسار /hikes/[id]؛ والمخطّطات المخصّصة تحتاج إلى development build، لا إلى Expo Go.","عند مطابقة URL، لا تضيف المجموعات ولا index أي جزء، والأجزاء الثابتة تتغلّب على الديناميكية، و[...rest] يلتقط كل ما تبقّى."],"further":[{"title":"Modals","url":"https://docs.expo.dev/router/advanced/modals/"},{"title":"Protected routes","url":"https://docs.expo.dev/router/advanced/protected/"},{"title":"Linking into your app","url":"https://docs.expo.dev/linking/into-your-app/"}],"quiz":[{"q":"

في Trailhead الملفان src/app/hikes/new.tsx وsrc/app/hikes/[id].tsx معًا. أيّهما يُرسم للعنوان /hikes/new؟

","options":[{"text":"[id].tsx، مع id بقيمة “new”، لأن المسارات الديناميكية تطابق أي شيء.","why":"المسارات الديناميكية تطابق فعلًا أي جزء، لكن الجزء الثابت الذي يطابق تمامًا هو المفضّل."},{"text":"الملف الذي أُنشئ أولًا.","why":"المطابقة لا تعتمد على عمر الملف. إنها ترتّب المسارات بحسب درجة تحديدها."},{"text":"لا هذا ولا ذاك؛ يُبلغ Expo Router عن تعارض عند بدء التشغيل.","why":"الإخوة الثابتون والديناميكيون إعداد طبيعي ومدعوم."},{"text":"new.tsx، لأن الجزء الثابت يتغلّب على الجزء الديناميكي.","why":"صحيح. يطابق /hikes/new المسار الثابت؛ أما /hikes/42 فيذهب إلى [id].tsx."}],"answer":3},{"q":"

ينقر مستخدمون غير مسجّلين على رابط في بريد قديم إلى trailhead://hikes/42. يقع مسار الرحلة داخل <Stack.Protected guard={isSignedIn}>. ماذا يحدث؟

","options":[{"text":"تنفتح شاشة الرحلة، ثم تعرض خطأ فورًا.","why":"المسارات المحميّة لا تُرسم أصلًا ما دام الـ guard قيمته false، فلا تُركَّب شاشة الرحلة أبدًا."},{"text":"يصل المستخدم إلى أول شاشة متاحة (شاشة تسجيل الدخول في Trailhead) بدلًا من المسار المحمي.","why":"صحيح. ما دام الـ guard قيمته false يكون المسار غير متاح، ويُعاد توجيه التنقّل إليه."},{"text":"ينهار التطبيق لأن المسار غير موجود.","why":"المسارات المحميّة مخفيّة، لا محذوفة؛ ويتعامل Expo Router مع المحاولة بلطف."}],"answer":1},{"q":"

أضفت scheme بقيمة trailhead إلى app.json وجرّبت trailhead://hikes/42 في Expo Go. لا شيء ينفتح. لماذا؟

","options":[{"text":"المخطّطات المخصّصة تُسجَّل في الإعدادات الأصلية للتطبيق، فتعمل في development build أو build إنتاجي من Trailhead، لا داخل Expo Go.","why":"صحيح. Expo Go تطبيق مختلف له مخطّطه الخاص؛ ابنِ Trailhead نفسه لتختبر روابطه."},{"text":"يجب أن تبدأ المخطّطات بـ https.","why":"الـ universal links والـ App Links تستخدم https، لكن المخطّطات المخصّصة مثل trailhead:// صالحة أيضًا."},{"text":"الـ deep links لا تعمل إلا حين يكون التطبيق مفتوحًا أصلًا.","why":"يستطيع الـ deep link تشغيل التطبيق من الصفر وفتح المسار المطابق مباشرة."}],"answer":0}],"exercise":{"kind":"web","mode":"js","starter":{"js":"const ROUTES = [\n '(tabs)/index',\n '(tabs)/stats',\n 'settings/index',\n 'settings/units',\n 'hikes/new',\n 'hikes/[id]',\n 'hikes/[id]/photos',\n 'trails/[...path]',\n];\n\n// Return { route, params } for the best matching route file, or null.\nfunction matchRoute(url, routes) {\n const path = url.replace(/^\\//, '');\n const route = routes.find((r) => r === path);\n return route ? { route, params: {} } : null;\n}\n\nconsole.log(JSON.stringify(matchRoute('/hikes/42?units=mi', ROUTES)));\n"},"solution":{"js":"const ROUTES = [\n '(tabs)/index',\n '(tabs)/stats',\n 'settings/index',\n 'settings/units',\n 'hikes/new',\n 'hikes/[id]',\n 'hikes/[id]/photos',\n 'trails/[...path]',\n];\n\nfunction segmentsOf(route) {\n const segs = route.split('/').filter((s) => !/^\\(.+\\)$/.test(s));\n if (segs[segs.length - 1] === 'index') segs.pop();\n return segs;\n}\n\nfunction tryMatch(route, parts) {\n const pattern = segmentsOf(route);\n const params = {};\n let rank = '';\n for (let i = 0; i < pattern.length; i++) {\n const seg = pattern[i];\n const catchAll = seg.match(/^\\[\\.\\.\\.(\\w+)\\]$/);\n const dynamic = seg.match(/^\\[(\\w+)\\]$/);\n if (catchAll) {\n const rest = parts.slice(i);\n if (rest.length === 0) return null;\n params[catchAll[1]] = rest;\n return { route, params, rank: rank + '1' };\n }\n if (i >= parts.length) return null;\n if (dynamic) {\n params[dynamic[1]] = parts[i];\n rank += '2';\n } else if (seg === parts[i]) {\n rank += '3';\n } else {\n return null;\n }\n }\n return pattern.length === parts.length ? { route, params, rank } : null;\n}\n\nfunction matchRoute(url, routes) {\n const [path, query = ''] = url.split('?');\n const parts = path.split('/').filter(Boolean);\n let best = null;\n for (const route of routes) {\n const m = tryMatch(route, parts);\n if (m && (!best || m.rank > best.rank)) best = m;\n }\n if (!best) return null;\n const params = { ...best.params };\n for (const [key, value] of new URLSearchParams(query)) params[key] = value;\n return { route: best.route, params };\n}\n\nconsole.log(JSON.stringify(matchRoute('/hikes/42?units=mi', ROUTES)));\n"},"checks":[{"id":"groups-index","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); return typeof matchRoute === 'function' && m('/')?.route === '(tabs)/index' && m('/stats')?.route === '(tabs)/stats' && m('/settings')?.route === 'settings/index' && m('/settings/units')?.route === 'settings/units';"},{"id":"dynamic","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); const a = m('/hikes/42'); const b = m('/hikes/42/photos'); return a?.route === 'hikes/[id]' && a.params.id === '42' && b?.route === 'hikes/[id]/photos' && b.params.id === '42';"},{"id":"static-wins","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); return m('/hikes/new')?.route === 'hikes/new';"},{"id":"catch-all","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); const a = m('/trails/alps/mont-blanc'); return a?.route === 'trails/[...path]' && Array.isArray(a.params.path) && a.params.path.join('/') === 'alps/mont-blanc' && m('/trails') === null;"},{"id":"query-slash","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); const a = m('/hikes/7?units=mi'); return a?.route === 'hikes/[id]' && a.params.id === '7' && a.params.units === 'mi' && m('/stats/')?.route === '(tabs)/stats';"},{"id":"no-match","test":"const R = ['(tabs)/index', '(tabs)/stats', 'settings/index', 'settings/units', 'hikes/new', 'hikes/[id]', 'hikes/[id]/photos', 'trails/[...path]']; const m = (u) => matchRoute(u, R); return m('/nope') === null && m('/settings/units/extra') === null;"}],"title":"طابق deep link مع ملف مسار","prompt":"

اكتب matchRoute(url, routes) بالطريقة التي يختار بها Expo Router شاشة لـ deep link. الـ routes مسارات ملفات دون .tsx (انظر ROUTES). أرجع { route, params } لأفضل مطابقة، أو null.

\n\n","hints":["حوّل كل مسار إلى أجزاء الـ URL الخاصة به أولًا: أسقط أجزاء (group) وindex الأخير. وقسّم مسار الـ URL باستخدام .split('/').filter(Boolean).","امشِ على أجزاء المسار بالتوازي مع أجزاء الـ URL. الجزء الحرفي يجب أن يساوي جزء الـ URL؛ و[x] يلتقطه؛ و[...x] يلتقط parts.slice(i) وينهي المطابقة. وبعد ذلك يجب أن تتطابق الأطوال.","للترتيب، ابنِ نصًّا لكل مطابقة برقم واحد لكل جزء (3 للثابت، 2 للديناميكي، 1 للشامل) واحتفظ بالمطابقة ذات النص الأكبر. وnew URLSearchParams(query) يمرّ على أزواج الـ query."],"explanation":"

يوحّد الحل كل ملف مسار إلى أجزاء URL، ويحاول مطابقته جزءًا جزءًا بينما يجمع الـ params، ويعطي كل جزء درجة بحيث تفوز المسارات الأكثر تحديدًا: مقارنة نصوص الدرجات ترتّب الثابت قبل الديناميكي قبل الشامل من اليسار إلى اليمين. ولهذا يصل /hikes/new إلى hikes/new.tsx بينما يذهب /hikes/42 إلى hikes/[id].tsx، ولهذا أيضًا يجب أن تظل الشاشة تتحقّق من id: فأداة المطابقة تقبل أي جزء على الإطلاق.

\n","checkLabels":{"groups-index":"المجموعات وملفات index لا تضيف جزءًا إلى الـ URL","dynamic":"الأجزاء الديناميكية تُطابَق وتصبح params نصية","static-wins":"المسار الثابت يتغلّب على الديناميكي","catch-all":"المسارات الشاملة تجمع الأجزاء المتبقّية في مصفوفة","query-slash":"الـ query strings تصبح params والشرطات المائلة الأخيرة تُتجاهَل","no-match":"المسارات غير المعروفة أو الطويلة جدًا تُرجع null"}},"words":646,"readMinutes":4}