useLocalStorage خطّاف التخزين المحلي
آخر تحديث: 2026-11-03
useLocalStorage خطّاف التخزين المحلي
يبقي useLocalStorage قراءات useState وكتابتها متزامنة مع localStorage: يقرأ القيمة المخزّنة كسولاً أثناء التهيئة، ويكتبها إلى القرص عند كل تحديث، فتنجو الحالة من إعادة تحميل الصفحة. وهو المثال النموذجي لخطّاف مخصّص يلتفّ على واجهة متصفح أصلية. ودالة التحديث المعادة تتصرّف تماماً كدالة useState، فلا يحتاج المستدعي إلى تعلّم واجهة ثانية لمجرد الحصول على الحفظ مجاناً.
| المجموعة | أنماط المكونات |
|---|---|
| النوع | خطاف |
| منذ الإصدار | React 16.8 |
ℹ️ ملاحظة يحوّل المحرّر JSX إلى JavaScript ويعرض الواجهة الحقيقية داخل بيئة معزولة؛ تُركَّب المكوّنات تلقائياً دون استدعاء render يدوي.
📝 الصيغة
function useLocalStorage(key, initial) {
const [value, setValue] = useState(() => {
const saved = localStorage.getItem(key) // تهيئة كسولة: اقرأ مرة واحدة فقط
return saved !== null ? JSON.parse(saved) : initial
})
useEffect(() => {
localStorage.setItem(key, JSON.stringify(value))
}, [key, value])
return [value, setValue]
}⚙️ المعاملات
| key | مفتاح التخزين في localStorage؛ ضع بادئة باسم تطبيقك لتفادي التصادم. |
|---|---|
| initial | القيمة المستخدمة حين لا يوجد شيء مخزّن محلياً؛ ويُقبل أي نوع قابل للتحويل إلى JSON. |
القيمة المرجعة：يعيد زوجاً [القيمة، setValue] يعمل تماماً مثل useState، عدا أن القراءات والكتابات تُحفظ تلقائياً في localStorage.
▶ مثال
المثال يعمل مباشرة: يُعرض تلقائياً عند التوسيع وتظهر التعديلات فوراً.
الناتج：
يزيد الضغط على الزر العدّاد ويكتبه في localStorage؛ وبعد إعادة التحميل أو فتح الصفحة من جديد يبقى العدد كما هو، ويعيد «Reset» إرجاعه إلى الصفر.💡 النقاط الأساسية
💡 نصيحة مرّر دالة للتهيئة حتى تُقرأ القيمة كسولاً، فتتجنّب لمس localStorage في كل عرض — فهو إدخال وإخراج متزامن وليس رخيصاً.
ℹ️ ملاحظة خزّن الكائنات والمصفوفات عبر تحويل JSON، واحمِ القراءة بـ try/catch تحسّباً لقيمة مخزّنة تالفة أو معدّلة يدوياً.
⚠️ تحذير localStorage مشترك لكل أصل ومحدود بحوالي 5 ميغابايت، فلا ينبغي أبداً تخزين بيانات حسّاسة مثل الرموز فيه كنص صريح.
🏷️ المزيد من أنماط المكونات
💡 حالات ذات صلة
المزيد من الحالات قريباً.
📚 دروس ذات صلة
❓ الأسئلة الشائعة
س هل سيرمي خطأً في بيئة SSR؟
ج نعم، فلا window ولا localStorage على الخادم. احمِ القراءة بفحص typeof window أو انقلها إلى useEffect.
س ما الفرق عن استخدام useState مباشرة؟
ج يضيف طبقة حفظ: القيمة الابتدائية تأتي من القرص، وكل تغيير يُكتب تلقائياً، وتبقى الواجهة مطابقة تماماً لـ useState.
س لماذا نحوّل الكائن إلى JSON عند تخزينه؟
ج لا يستطيع localStorage حمل سوى نصوص؛ وبدون التحويل ستخزّن «[object Object]» ولن تتمكّن أبداً من استعادة القيمة.
