يخزّن Trailhead التفضيلات في AsyncStorage نصوصًا غير مشفّرة، والرحلات في قاعدة بيانات SQLite يستطيع الاستعلام عنها، والـ refresh token في SecureStore مشفّرًا عبر Keychain أو Keystore. والصور ملفات على القرص تُخزَّن مساراتها في SQLite.

{"id":"l-rn-4-2","courseId":"react-native-apps","lang":"ar","kind":"lesson","summary":"اختر بين AsyncStorage وexpo-sqlite وexpo-secure-store لكل نوع من البيانات في Trailhead، واستخدم كلًّا منها بشكل صحيح، من التفضيلات إلى قاعدة بيانات الرحلات مع الـ migrations إلى token تسجيل الدخول.","html":"

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

\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

البيانات	مثال	الأداة
تفضيلات صغيرة	الوحدات (km أو mi)، آخر tab مستخدم	AsyncStorage
سجلّات منظّمة تستعلم عنها	سجلّ الرحلات، مرتّبًا ومصفّى	expo-sqlite
أسرار	الـ refresh token لتسجيل الدخول	expo-secure-store

اختيار الأداة الخاطئة نادرًا ما يفشل بصوت عالٍ. بل يفشل في صورة شاشات بطيئة، أو بيانات ضائعة بعد تحديث، أو مراجعة أمنية لا تجتازها.

\n

ثلاثة مخازن، وثلاث وظائف

\n

AsyncStorage للتفضيلات

\n

AsyncStorage مخزن مفتاح-قيمة دائم لـ النصوص. كل استدعاء فيه غير متزامن، ولا شيء مشفّر:

\n

src/lib/prefs.ts

import AsyncStorage from '@react-native-async-storage/async-storage';\n\nexport type Prefs = { units: 'km' | 'mi'; remindersOn: boolean };\nconst KEY = 'trailhead.prefs.v1';\nconst defaults: Prefs = { units: 'km', remindersOn: false };\n\nexport async function loadPrefs(): Promise<Prefs> {\n  const raw = await AsyncStorage.getItem(KEY);\n  if (!raw) return defaults;\n  try {\n    return { ...defaults, ...JSON.parse(raw) };\n  } catch {\n    return defaults;\n  }\n}\n\nexport function savePrefs(prefs: Prefs) {\n  return AsyncStorage.setItem(KEY, JSON.stringify(prefs));\n}

\n

خزّن قيمة JSON واحدة تحت مفتاح مرقّم بإصدار بدلًا من مفاتيح صغيرة كثيرة، وادمجها مع القيم الافتراضية عند القراءة (حتى يحصل تفضيل جديد أُضيف في الإصدار الثاني على قيمة معقولة لدى المستخدمين القدامى)، واصمد أمام البيانات التالفة باستخدام try. ثبّته بالأمر npx expo install @react-native-async-storage/async-storage. وإن كان تطبيقك يستخدم expo-sqlite أصلًا، فإن expo-sqlite/kv-store يقدّم الواجهة البرمجية نفسها مدعومة بـ SQLite، فتستغني عن الاعتمادية الإضافية.

\n

اقرأ التفضيلات مرة واحدة عند بدء التشغيل، واحفظها في context مثل الرحلات، واكتبها مجددًا حين تتغيّر. استدعاء getItem داخل الـ components في كل render يحوّل شاشة سريعة إلى شاشة تومض بالقيم الافتراضية أولًا.

\n

ويصبح AsyncStorage بطيئًا ومربكًا حين تبدأ بتخزين قوائم من السجلّات فيه: كل قراءة تحلّل الكتلة كلها، ولا طريقة لطلب «الرحلات التي تتجاوز 10 km في 2026» دون تحميل كل شيء.

\n

expo-sqlite لسجلّ الرحلات

\n

سجلّ الرحلات بيانات منظّمة ترتّبها وتصفّيها وتجمعها، وهذا ما وُجدت قاعدة البيانات من أجله. يعطيك expo-sqlite ملف قاعدة بيانات SQLite حقيقيًا على الجهاز. يفتحه SQLiteProvider ويشغّل الإعداد الخاص بك قبل أن يُرسم أي ابن:

\n

src/app/_layout.tsx

import { Stack } from 'expo-router';\nimport { SQLiteProvider, type SQLiteDatabase } from 'expo-sqlite';\n\nasync function migrate(db: SQLiteDatabase) {\n  const row = await db.getFirstAsync<{ user_version: number }>('PRAGMA user_version');\n  let version = row?.user_version ?? 0;\n\n  if (version === 0) {\n    await db.execAsync(`\n      PRAGMA journal_mode = WAL;\n      CREATE TABLE hikes (\n        id TEXT PRIMARY KEY NOT NULL,\n        name TEXT NOT NULL,\n        date TEXT NOT NULL,\n        distanceKm REAL NOT NULL,\n        favorite INTEGER NOT NULL DEFAULT 0\n      );\n    `);\n    version = 1;\n  }\n  if (version === 1) {\n    await db.execAsync('ALTER TABLE hikes ADD COLUMN photoUri TEXT');\n    version = 2;\n  }\n  await db.execAsync(`PRAGMA user_version = ${version}`);\n}\n\nexport default function RootLayout() {\n  return (\n    <SQLiteProvider databaseName=\"trailhead.db\" onInit={migrate}>\n      <Stack />\n    </SQLiteProvider>\n  );\n}

\n

PRAGMA user_version رقم يخزّنه SQLite في الملف نيابةً عنك. كل كتلة if ترقّي خطوة واحدة، فالمستخدم على الإصدار 0 يشغّل الاثنتين، والمستخدم على الإصدار 1 يشغّل الثانية فقط. لا تعدّل أبدًا خطوة قديمة بعد إطلاقها؛ بل أضف خطوة جديدة.

\n

بعد ذلك تستطيع أي شاشة استخدام قاعدة البيانات:

\n

TSX

import { useSQLiteContext } from 'expo-sqlite';\n\nconst db = useSQLiteContext(); // in a component or custom hook\n\n// …later, inside an async function such as an effect or a save handler:\nconst hikes = await db.getAllAsync<Hike>('SELECT * FROM hikes ORDER BY date DESC');\nawait db.runAsync(\n  'INSERT INTO hikes (id, name, date, distanceKm) VALUES (?, ?, ?, ?)',\n  hike.id, hike.name, hike.date, hike.distanceKm,\n);

\n

عمليًا ستستدعي هذه من الـ provider الخاص بالـ reducer: حمّل الرحلات مرة واحدة إلى الـ state، واكتب إلى SQLite كلما غيّرها action.

\n\n

SecureStore للأسرار

\n

يتيح الـ refresh token لـ Trailhead تسجيل الدخول بصمت. ومن يقرؤه يستطيع التصرّف بوصفه المستخدم، لذا يوضع في expo-secure-store، الذي يشفّر القيم باستخدام Keychain في iOS وKeystore في Android:

\n

src/lib/session.ts

import * as SecureStore from 'expo-secure-store';\n\nconst TOKEN_KEY = 'trailhead.refreshToken';\n\nexport const saveToken = (token: string) => SecureStore.setItemAsync(TOKEN_KEY, token);\nexport const readToken = () => SecureStore.getItemAsync(TOKEN_KEY);\nexport const clearToken = () => SecureStore.deleteItemAsync(TOKEN_KEY);

\n

هذا ما كانت حالة isLoading في useSession من القسم السابق تنتظره: عند بدء التشغيل، يقرّر readToken() هل يصل المستخدم إلى الـ tabs أم إلى شاشة تسجيل الدخول. صُمّم SecureStore للقيم الصغيرة؛ وقد رفضت بعض إصدارات المنصّات قيمًا تتجاوز نحو 2 KB. احفظ فيه الـ tokens والمفاتيح، ولا تحفظ فيه كائنات كاملة أو ملفات أبدًا. وهو لا يعمل على الويب، فتحتاج نسخة الويب إلى نهج مختلف.

\n

مكان الملفات على القرص

\n

صورة الدرب عدّة ميغابايتات. لا تضعها في SQLite ولا في AsyncStorage. احتفظ بالملف على القرص (يدير expo-file-system مجلّد المستندات الخاص بتطبيقك)، وخزّن الـ URI الخاص به فقط في عمود photoUri. تبقى قاعدة بياناتك صغيرة وسريعة، ويحمّل component الصورة الملف مباشرة.

\n

كل هذه البيانات تصمد أمام تحديثات التطبيق، بما فيها التحديثات عبر الهواء، وتُحذف حين يُزيل المستخدم التطبيق، مع استثناء غريب: على iOS قد تبقى قيم الـ Keychain المحفوظة عبر SecureStore بعد إعادة التثبيت، فلا تعتبر غياب قاعدة البيانات دليلًا على عدم وجود token. وإن كان فقدانها مؤلمًا، فزامنها مع خادمك، وهذا بالضبط سبب وجود الحسابات في Trailhead.

\n

التالي: أدقّ جزء في التعامل مع الجهاز، أي طلب الإذن لاستخدام موقعه وكاميرته.

\n","toc":[{"id":"sec-1","text":"AsyncStorage للتفضيلات","level":2},{"id":"sec-2","text":"expo-sqlite لسجلّ الرحلات","level":2},{"id":"sec-3","text":"SecureStore للأسرار","level":2},{"id":"sec-4","text":"مكان الملفات على القرص","level":2}],"takeaways":["AsyncStorage مخزن مفتاح-قيمة للنصوص، غير مشفّر وغير متزامن، مناسب للتفضيلات الصغيرة وغير مناسب للأسرار.","يخزّن expo-sqlite البيانات المنظّمة التي تستعلم عنها وترتّبها وتصفّيها؛ شغّل الـ migrations الخاصة بالمخطّط (schema) داخل onInit مستخدمًا PRAGMA user_version.","مرّر قيم SQL دائمًا بوصفها معاملات (?)، ولا تبنِ نص SQL بنفسك أبدًا.","يشفّر expo-secure-store القيم الصغيرة باستخدام Keychain أو Keystore الخاص بالمنصّة؛ ومكان الـ tokens والمفاتيح هناك.","خزّن الملفات مثل الصور في نظام الملفات، واحتفظ بمساراتها فقط في قاعدة البيانات."],"further":[{"title":"Store data","url":"https://docs.expo.dev/develop/user-interface/store-data/"},{"title":"SQLite","url":"https://docs.expo.dev/versions/latest/sdk/sqlite/"},{"title":"SecureStore","url":"https://docs.expo.dev/versions/latest/sdk/securestore/"}],"quiz":[{"q":"

أين يجب أن يحتفظ Trailhead بالـ refresh token الذي يتلقّاه بعد تسجيل الدخول؟

","options":[{"text":"في AsyncStorage، تحت مفتاح مثل auth.refreshToken.","why":"AsyncStorage غير مشفّر. وعلى جهاز مخترق أو له نسخة احتياطية، يمكن قراءة الـ token نصًّا عاديًا."},{"text":"في متغيّر بيئة يبدأ بـ EXPO_PUBLIC_.","why":"هذه تُدمج في حزمة التطبيق وقت البناء؛ فلا تستطيع حمل قيم خاصة بكل مستخدم، ويستطيع أي أحد قراءتها."},{"text":"في expo-secure-store، الذي يشفّره باستخدام Keychain على iOS وKeystore على Android.","why":"صحيح. الأسرار الصغيرة مثل الـ tokens هي بالضبط ما صُمّم له."},{"text":"في جدول tokens داخل قاعدة بيانات SQLite.","why":"ملف قاعدة البيانات غير مشفّر افتراضيًا، فسيقبع الـ token نصًّا عاديًا بجوار الرحلات."}],"answer":2},{"q":"

أيّ سطر آمن لحفظ اسم رحلة كتبه المستخدم؟

","options":[{"text":"db.runAsync(`INSERT INTO hikes (name) VALUES ('${name}')`)","why":"اسم يحتوي على علامة اقتباس، مثل O’Brien Ridge، يكسر العبارة، ويمكن لمدخلات مصمّمة بخبث أن تغيّر الـ SQL نفسه."},{"text":"db.runAsync('INSERT INTO hikes (name) VALUES (?)', name)","why":"صحيح. تُربط القيمة بوصفها معاملًا، فتُعامَل دائمًا كبيانات، لا كـ SQL أبدًا."},{"text":"db.execAsync('INSERT INTO hikes (name) VALUES (' + JSON.stringify(name) + ')')","why":"اقتباس JSON ليس اقتباس SQL، وexecAsync لا يربط المعاملات. إنه بناء للنصوص بخطوات إضافية."}],"answer":1},{"q":"

يضيف الإصدار الثاني من Trailhead عمود elevationM إلى جدول الرحلات. المستخدمون الحاليون لديهم جدول الإصدار الأول أصلًا. ما الطريقة الموثوقة؟

","options":[{"text":"في migration داخل onInit، اقرأ PRAGMA user_version؛ وإن كانت 1، فشغّل ALTER TABLE hikes ADD COLUMN elevationM INTEGER واضبط الإصدار على 2.","why":"صحيح. الـ migrations المرقّمة بالإصدارات ترقّي قاعدة بيانات كل مستخدم مرة واحدة بالضبط، بالترتيب، أيًّا كان الإصدار الذي يبدأ منه."},{"text":"احذف قاعدة البيانات عند بدء التشغيل وأعد إنشاءها بالمخطّط الجديد.","why":"هذا يمسح سجلّ رحلات كل مستخدم عند التحديث. البيانات على الجهاز ملك المستخدم؛ ولا يمكنك إعادة تحميلها من أي مكان."},{"text":"غيّر عبارة CREATE TABLE؛ وسيحدّث SQLite الجداول الموجودة لتطابقها.","why":"CREATE TABLE IF NOT EXISTS يتخطّى الجداول الموجودة كليًا، فلا يحصل المستخدمون القدامى على العمود الجديد أبدًا."}],"answer":0}],"exercise":{"kind":"choice","multiple":true,"options":["units-async","log-sqlite","token-async","photo-secure","token-secure","log-async"],"correct":["units-async","log-sqlite","token-secure"],"title":"ضع كل قطعة بيانات في المخزن الصحيح","prompt":"

كتب زميلك مسوّدة خطّة التخزين في Trailhead. اختر كل سطر في الخطّة كنت ستوافق عليه في مراجعة الكود.

\n","hints":["اطرح سؤالين عن كل قطعة بيانات: هل هي سرّية، وهل ستحتاج إلى الاستعلام عنها أو تصفيتها؟","SecureStore للأسرار الصغيرة؛ والصور بالميغابايتات.","ثلاثة أسطر صحيحة."],"explanation":"

التفضيلات صغيرة وغير ضارّة، فيناسبها AsyncStorage (قيمة JSON واحدة تحت مفتاح مرقّم بإصدار). وسجلّ الرحلات بيانات منظّمة ترتّبها وتصفّيها، فمكانه expo-sqlite مع migrations مرقّمة بالإصدارات. والـ refresh token سرّ، فمكانه expo-secure-store، مشفّرًا عبر Keychain أو Keystore. الـ tokens في AsyncStorage تقبع نصًّا عاديًا؛ والصور في SecureStore تتجاوز الحجم الذي صُمّم له؛ وسجلّ من 600 رحلة في AsyncStorage يعني تحليل كل شيء مع كل استعلام.

\n","checkLabels":{},"optionText":{"units-async":{"text":"خزّن تفضيل الوحدات لدى المستخدم (km أو mi) وإعداد التذكيرات قيمةَ JSON واحدة في AsyncStorage تحت trailhead.prefs.v1.","why":"موافقة. التفضيلات الصغيرة غير السرّية هي ما وُجد AsyncStorage من أجله، والمفتاح المرقّم بإصدار يسهّل التغييرات المستقبلية."},"log-sqlite":{"text":"خزّن سجلّ الرحلات في جدول expo-sqlite، مع معالجة تغييرات المخطّط عبر migrations مبنية على PRAGMA user_version.","why":"موافقة. السجلّات المنظّمة التي تستعلم عنها مكانها قاعدة بيانات، والـ migrations المرقّمة تحافظ على بيانات المستخدمين القدامى سليمة."},"token-async":{"text":"خزّن الـ refresh token في AsyncStorage ليُحمَّل بسرعة عند بدء التشغيل.","why":"رفض. AsyncStorage غير مشفّر. وسرعة بدء التشغيل لا تبرّر حفظ بيانات اعتماد نصًّا عاديًا."},"photo-secure":{"text":"خزّن كل صورة درب نصًّا بترميز base64 في expo-secure-store لتبقى الصور خاصة.","why":"رفض. صُمّم SecureStore للقيم الصغيرة؛ والصور ذات الميغابايتات مكانها نظام الملفات، مع حفظ مساراتها فقط في SQLite."},"token-secure":{"text":"خزّن الـ refresh token في expo-secure-store واحذفه عند تسجيل الخروج.","why":"موافقة. يشفّره SecureStore بمخزن المفاتيح الخاص بالمنصّة، وحذفه عند تسجيل الخروج لا يترك شيئًا خلفه."},"log-async":{"text":"احتفظ بالرحلات الـ 600 كلها مصفوفة JSON واحدة في AsyncStorage وصفّها في JavaScript.","why":"رفض. كل قراءة تحلّل السجلّ كله، وكل كتابة تعيد كتابته، ولا طريقة للاستعلام دون تحميل كل شيء."}}},"words":601,"readMinutes":4}