أضف ثلاثة مصاريف إلى Pocket، ثم أعِد تحميل الصفحة، وستجدها اختفت. كل ما بنيته يعيش في متغيّرات JavaScript، والمتغيّرات لا تعيش إلا ما دامت الصفحة. ولكي تتذكّر البيانات بين الزيارات، تحتاج إلى تخزينها في مكان ما، وأبسط مكان تستطيع صفحة ويب أن تخزّن فيه البيانات هو متصفّح المستخدم نفسه. لكن أولًا، يجب أن تتحوّل البيانات إلى نص.
\nJSON (اختصار JavaScript Object Notation) صيغة نصية للبيانات. يكاد شكلها يطابق صيغة كتابة الكائنات والمصفوفات في JavaScript، وهذا ليس مصادفة، وهي اليوم الصيغة الأكثر شيوعًا لإرسال البيانات بين البرامج على الويب.
\nconst expenses = [\n { id: \"exp-1\", label: \"Coffee\", amount: 450, tags: [\"work\"] },\n { id: \"exp-2\", label: \"Train\", amount: 1220, tags: [] },\n];\n\nconst text = JSON.stringify(expenses);\nconsole.log(typeof text);\nconsole.log(text);\n\nconst back = JSON.parse(text);\nconsole.log(back[1].label, back === expenses);JSON.stringify تحوّل قيمة إلى نص JSON. وJSON.parse تقرأ نص JSON وتبني منه قيمًا جديدة. والنتيجة نسخة جديدة بالمحتويات نفسها، ولهذا تكون back === expenses تساوي false.
قواعد JSON أكثر صرامة من قواعد JavaScript: أسماء الخصائص يجب أن تكون بين علامات تنصيص مزدوجة، والنصوص لا تستخدم إلا العلامات المزدوجة، والفواصل الزائدة في النهاية غير مسموحة. نادرًا ما تكتب JSON يدويًا، لكن حين تفعل، تسبّب هذه القواعد الثلاث معظم أخطاء التحليل. وللحصول على نسخة مقروءة، تُزيح JSON.stringify(value, null, 2) المخرجات بمسافتين.
يعرف JSON النصوص والأرقام والقيم المنطقية وnull والمصفوفات والكائنات البسيطة. وكل ما عدا ذلك يتغيّر أو يضيع في الطريق:
const tricky = {\n when: new Date(\"2026-10-05T09:30:00Z\"),\n note: undefined,\n format() { return \"hi\"; },\n tags: new Set([\"work\"]),\n ratio: NaN,\n};\nconsole.log(JSON.stringify(tricky));التواريخ تصبح نصوصًا بصيغة ISO ولا تعود تواريخ، وخصائص undefined والدوال تُسقط، والـ Sets والـ Maps تصبح كائنات فارغة، وNaN تصبح null. ويتجنّب Pocket كل هذا بالتصميم: المبالغ أعداد صحيحة، والتواريخ تُخزَّن نصوصًا مثل "2026-10-05"، والفئات نصوص بسيطة. واختيار بيانات تناسب JSON منذ البداية يوفّر كثيرًا من كود التحويل لاحقًا.
يحصل كل موقع على مخزن صغير للمفاتيح والقيم في متصفّح كل مستخدم، اسمه localStorage. إنه ينجو من إعادة التحميل ومن إعادة تشغيل المتصفّح، ولا يحمل إلا النصوص:
localStorage.setItem(\"pocket.theme\", \"dark\");\nconsole.log(localStorage.getItem(\"pocket.theme\")); // \"dark\"\nconsole.log(localStorage.getItem(\"nothing-here\")); // null\nlocalStorage.removeItem(\"pocket.theme\");لتخزين مصفوفة مصاريف، حوّلها إلى JSON عند الإدخال وحلّلها عند الإخراج:
\nconst STORAGE_KEY = \"pocket.expenses.v1\";\n\nfunction saveExpenses(expenses) {\n localStorage.setItem(STORAGE_KEY, JSON.stringify(expenses));\n}\n\nfunction loadExpenses() {\n try {\n const text = localStorage.getItem(STORAGE_KEY);\n const data = text === null ? [] : JSON.parse(text);\n return Array.isArray(data) ? data : [];\n } catch {\n return [];\n }\n}loadExpenses دفاعية عن قصد، لأنها تُنفَّذ مع كل تحميل للصفحة ويجب ألّا تُسقط التطبيق أبدًا. الزائر لأول مرة لم يحفظ شيئًا، فتُرجع getItem القيمة null ونبدأ بقائمة فارغة. والنص التالف يجعل JSON.parse ترمي خطأ، فتلجأ catch إلى قائمة فارغة. وبعض أوضاع الخصوصية في المتصفّحات تمنع التخزين كليًا، وهذا يرمي خطأ أيضًا يذهب إلى catch نفسها. وأخيرًا، تحمي Array.isArray من JSON صالح لكن بشكل خاطئ. والجزء .v1 في المفتاح يتيح لإصدار مستقبلي من Pocket أن يغيّر صيغة البيانات وينقل البيانات القديمة بدلًا من أن يسيء قراءتها.
ثم اربط كل ذلك: حمّل مرة واحدة عند البدء، واحفظ في كل مرة تتغيّر فيها البيانات، في المكان نفسه الذي تستدعي فيه renderExpenses أصلًا:
let expenses = loadExpenses();\nrenderExpenses();\n\nfunction setExpenses(next) {\n expenses = next;\n saveExpenses(expenses);\n renderExpenses();\n}تمرير كل تغيير عبر دالة واحدة setExpenses يعني أنك لا تستطيع أن تنسى الحفظ في معالج حدث وتتذكّره في آخر.
لترى ما هو مخزّن، افتح DevTools، واذهب إلى لوحة Application في Chrome أو Edge (أو Storage في Firefox)، ووسّع Local Storage. يمكنك هناك قراءة المدخلات وتعديلها وحذفها، وهذه أسرع طريقة لاختبار ما يفعله تطبيقك مع البيانات المفقودة أو التالفة. وهناك أيضًا sessionStorage، بالدوال نفسها، وتُمسح حين يُغلق التبويب.
صار بإمكانك الاحتفاظ بالبيانات بين الزيارات. والمصدر الكبير الآخر للبيانات هو خادم على الإنترنت، والتحدّث إليه يعني انتظار الإجابة. والانتظار هو موضوع الدرس التالي.
\n","toc":[{"id":"sec-1","text":"JSON: البيانات على شكل نص","level":2},{"id":"sec-2","text":"ما لا يستطيع JSON حمله","level":3},{"id":"sec-3","text":"localStorage: مخزن صغير في المتصفّح","level":2}],"takeaways":["JSON صيغة نصية للبيانات؛JSON.stringify تحوّل القيم إلى نص JSON، وJSON.parse تعيد نص JSON إلى قيم.","يحمل JSON النصوص والأرقام والقيم المنطقية وnull والمصفوفات والكائنات البسيطة؛ أما الدوال وundefined فتُسقط، والتواريخ تصبح نصوصًا.","localStorage لا تخزّن إلا النصوص، لكل موقع على حدة، في متصفّح المستخدم؛ احفظ باستخدام setItem(key, JSON.stringify(data)).","يجب أن ينجو التحميل من غياب المفتاح (getItem تُرجع null) ومن النص التالف (JSON.parse ترمي خطأ)، لذلك ضعه داخل try/catch مع قيمة بديلة."],"further":[{"title":"Working with JSON (MDN)","url":"https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/JSON"},{"title":"JSON.stringify() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify"},{"title":"Window.localStorage (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage"}],"quiz":[{"q":"استُدعيت localStorage.setItem("expenses", expenses) مع مصفوفة من الكائنات. ما الذي يُخزَّن؟
"[object Object],[object Object]".","why":"صحيح. كل كائن يتحوّل إلى “[object Object]” فتضيع البيانات. خزّن JSON.stringify(expenses) بدلًا من ذلك."},{"text":"المصفوفة، جاهزة للاستخدام حين تقرؤها مجددًا.","why":"localStorage لا تخزّن إلا النصوص. وكل ما عدا ذلك يُحوَّل أولًا بـ String()."},{"text":"لا شيء؛ setItem ترمي خطأ مع القيم غير النصية.","why":"لا ترمي أي خطأ. إنها تحوّل القيمة إلى نص بصمت، ولهذا يسهل أن يفوتك هذا الخطأ."}],"answer":0},{"q":"ماذا يُنتج JSON.stringify({ label: "Tea", note: undefined, amount: 300 })؟
{"label":"Tea","amount":300}","why":"صحيح. الخصائص التي قيمتها undefined (والدوال) تُحذف، لأن JSON لا يملك طريقة لكتابتها."},{"text":"{"label":"Tea","note":undefined,"amount":300}","why":"undefined ليست JSON صالحًا، لذلك لا تكتبها stringify أبدًا داخل كائن."},{"text":"{"label":"Tea","note":null,"amount":300}","why":"stringify تُسقط خصائص undefined بدلًا من تحويلها إلى null. وحدها null نفسها تُكتب null."}],"answer":0},{"q":"يحمّل Pocket البيانات بـ JSON.parse(localStorage.getItem("pocket.expenses")) في الزيارة الأولى، ولم يُحفظ شيء بعد. ماذا يحدث؟
getItem ترمي خطأ مع المفاتيح غير المعروفة.","why":"getItem تُرجع null للمفتاح المفقود؛ ولا ترمي خطأ."},{"text":"يُرجع null، لأن JSON.parse(null) تعامل null على أنها نص JSON “null”.","why":"صحيح. ثم ينهار الكود لاحقًا حين يستدعي .map على null. استخدم قيمة بديلة بـ ?? [] أو بفحص صريح."},{"text":"يُرجع مصفوفة فارغة.","why":"لا شيء هنا يُنشئ مصفوفة. عليك أن توفّر القيمة البديلة، المصفوفة الفارغة، بنفسك."}],"answer":1}],"exercise":{"kind":"web","mode":"js","starter":{"js":"// Pocket's storage helpers. In this playground, localStorage works but starts\n// empty on every run; on a real page it keeps its data between visits.\nconst STORAGE_KEY = \"pocket.expenses.v1\";\n\nfunction saveExpenses(expenses) {\n localStorage.setItem(STORAGE_KEY, expenses);\n}\n\nfunction loadExpenses() {\n return JSON.parse(localStorage.getItem(STORAGE_KEY));\n}\n\nsaveExpenses([{ id: \"exp-1\", label: \"Coffee\", amount: 450 }]);\nconsole.log(localStorage.getItem(STORAGE_KEY));\n"},"solution":{"js":"// Pocket's storage helpers. In this playground, localStorage works but starts\n// empty on every run; on a real page it keeps its data between visits.\nconst STORAGE_KEY = \"pocket.expenses.v1\";\n\nfunction saveExpenses(expenses) {\n localStorage.setItem(STORAGE_KEY, JSON.stringify(expenses));\n}\n\nfunction loadExpenses() {\n try {\n const text = localStorage.getItem(STORAGE_KEY);\n const data = text === null ? [] : JSON.parse(text);\n return Array.isArray(data) ? data : [];\n } catch {\n return [];\n }\n}\n\nsaveExpenses([{ id: \"exp-1\", label: \"Coffee\", amount: 450 }]);\nconsole.log(localStorage.getItem(STORAGE_KEY));\n"},"checks":[{"id":"saves-json","test":"localStorage.clear();\nsaveExpenses([{ id: 'a', label: 'Tea', amount: 300 }]);\nconst raw = localStorage.getItem('pocket.expenses.v1');\ntry { const back = JSON.parse(raw); return Array.isArray(back) && back[0].label === 'Tea' && back[0].amount === 300; } catch { return false; }\n"},{"id":"round-trip","test":"localStorage.clear();\nconst data = [{ id: 'a', label: 'Tea', amount: 300 }, { id: 'b', label: 'Bus', amount: 270 }];\nsaveExpenses(data);\nconst back = loadExpenses();\nreturn Array.isArray(back) && back.length === 2 && back[1].label === 'Bus' && back[1].amount === 270 && back !== data;\n"},{"id":"missing","test":"localStorage.clear();\nconst out = loadExpenses();\nreturn Array.isArray(out) && out.length === 0;\n"},{"id":"corrupt","test":"localStorage.clear();\nlocalStorage.setItem('pocket.expenses.v1', '[{\"id\": \"a\", oops');\ntry { const out = loadExpenses(); return Array.isArray(out) && out.length === 0; } catch { return false; }\n"},{"id":"wrong-shape","test":"localStorage.clear();\nlocalStorage.setItem('pocket.expenses.v1', '{\"label\":\"not a list\"}');\ntry { const out = loadExpenses(); return Array.isArray(out) && out.length === 0; } catch { return false; }\n"}],"title":"احفظ Pocket وحمّله بأمان","prompt":"دوال التخزين في Pocket تُضيّع البيانات. أصلحها مستخدمًا localStorage الحقيقية (وهي تعمل في بيئة التجربة هذه، لكنها تبدأ فارغة مع كل تشغيل):
saveExpenses(expenses) بحيث تخزّن المصاريف بصيغة JSON تحت STORAGE_KEY.loadExpenses() بحيث تُرجع المصفوفة المحفوظة، وتُرجع مصفوفة فارغة [] بدلًا من الانهيار حين لا يكون هناك شيء محفوظ، أو حين لا يكون النص المحفوظ JSON صالحًا، أو حين يكون JSON صالحًا لكنه ليس مصفوفة.[object Object]. غلّف البيانات بـ JSON.stringify(...) قبل setItem.","getItem تُرجع null حين لا يكون هناك شيء محفوظ. افحص ذلك قبل التحليل.","ضع التحليل داخل try { … } catch { return []; }، واختم بـ return Array.isArray(data) ? data : [];."],"explanation":"لا تحتفظ localStorage إلا بالنصوص، لذلك يجب تحويل المصفوفة إلى نص بـ JSON.stringify عند الإدخال؛ وإلا فإنها تُحوَّل بـ String() وتصبح [object Object]. ويحمي التحميل من ثلاثة أنواع مختلفة من الفشل: مفتاح مفقود (getItem تُرجع null)، ونص ليس JSON (JSON.parse ترمي خطأ، فتحوّله catch إلى قائمة فارغة)، وJSON بشكل خاطئ (Array.isArray ترفضه). وكتلة try نفسها تلتقط أيضًا حالة المتصفّحات التي تمنع التخزين كليًا، فلا يمكن أن ينهار تحميل الصفحة هنا.
saveExpenses تخزّن المصاريف نصَّ JSON","round-trip":"المصاريف المحفوظة تُحمَّل كما هي دون تغيير","missing":"التحميل مع عدم وجود شيء محفوظ يُرجع []","corrupt":"تحميل JSON غير صالح يُرجع [] بدلًا من رمي خطأ","wrong-shape":"تحميل JSON ليس مصفوفة يُرجع []"}},"words":617,"readMinutes":4}