‏useSWR: الجلب وحالات التحميل والأخطاء

يُعدّ useSWR(key, fetcher, options) هو hook الأساسي. ويمثل key مفتاح الذاكرة المؤقتة (وعادةً ما يكون سلسلة URL)، ويمثل fetcher الدالة غير المتزامنة التي تعيد البيانات، أما options فهو كائن إعداد اختياري.

يعيد hook كائنًا يحتوي على data وerror وisLoading وisValidating ودالة mutate.

يمكن أن يكون key عنوان URL على شكل سلسلة، أو مصفوفة من [url, params]، أو null. وترتبط المفاتيح النصية بطلبات GET البسيطة. وتتيح مفاتيح المصفوفات تضمين متغيرات مثل userId أو filters ضمن هوية الذاكرة المؤقتة.

يؤدي تمرير null إلى تعطيل الطلب بالكامل، وهو مفيد للجلب الشرطي عندما لا تتوفر البيانات المطلوبة بعد.

تتلقى fetcher المفتاح (أو عناصر مفتاح المصفوفة موزعةً كوسائط)، ويجب أن تعيد Promise. وتصبح القيمة الناتجة عن حل Promise هي data. وإذا أطلقت fetcher استثناءً، فتُضبط الخاصية error.

مثال: (url) => fetch(url).then(r => { if (!r.ok) throw new Error(r.status); return r.json(); }).

تكون data بقيمة undefined أثناء التحميل للمرة الأولى، وتساوي القيمة التي أعادتها fetcher بعد نجاحها. وتكون error بقيمة undefined ما لم تُطلق fetcher استثناءً، وعندها تحتوي على كائن الخطأ المُطلَق.

تحققوا من if (error) لعرض رسالة خطأ، ومن if (!data) لعرض هيكل تحميل، وبذلك توفرون واجهات احتياطية واضحة.

تكون isLoading بقيمة true فقط عند عدم وجود بيانات مخزنة مؤقتًا ووجود طلب قيد التنفيذ، أي عند التحميل الأول لهذا المفتاح. أما isValidating فتكون بقيمة true في أي وقت يوجد فيه طلب قيد التنفيذ، بما في ذلك عمليات إعادة التحقق في الخلفية عندما تكون البيانات المخزنة مؤقتًا موجودة بالفعل.

استخدموا isLoading لشاشات الهياكل التحميلية، وisValidating لمؤشر تحميل خفيف يشير إلى تحديث في الخلفية.

تتيح لكم SWRConfig تحديد fetcher الافتراضية وdedupingInterval وrefreshInterval ومعالج onError وغير ذلك من الخيارات لجميع استدعاءات useSWR ضمن الشجرة التابعة لها. وبهذا تُوحَّد الإعدادات بدلًا من تكرار الخيارات في كل hook.

يمكنكم تداخل موفري SWRConfig متعددين لتحديد إعدادات افتراضية مختلفة لأقسام مختلفة من تطبيقكم.

مرروا null بوصفه المفتاح لتخطي الطلب: useSWR(isLoggedIn ? '/api/user' : null, fetcher). ولن يجلب SWR البيانات حتى يصبح المفتاح قيمة غير null.

هذا أنظف من خيار skip في React Query. ويؤدي انتقال المفتاح من null إلى سلسلة نصية تلقائيًا إلى تشغيل أول عملية جلب.

اربطوا بين hooks الخاصة بـ SWR للطلبات التابعة: const { data: user } = useSWR('/api/me', fetcher) ثم const { data: orders } = useSWR(user ? '/api/orders/' + user.id : null, fetcher). وينتظر hook الثاني حتى يكتمل الأول.

يتجنب هذا النمط سلاسل useEffect، ويحافظ على تبعية البيانات بصورة وصفية وسهلة القراءة.

إذا استدعى مكوّنا Header وSidebar كلاهما useSWR('/api/user', fetcher)، فلن يرسل SWR سوى طلب واحد، ويشارك النتيجة بينهما. ويعيد كلا المكونين التصيير معًا عند تحديث data أو error.

تحدث عملية إلغاء الازدواجية هذه تلقائيًا ضمن نافذة dedupingInterval (وقيمتها الافتراضية 2000ms)، دون أي إعداد إضافي.

يُجري refreshInterval: 5000 استطلاعًا كل 5 ثوانٍ. ويوقف refreshWhenHidden: false الاستطلاع عندما لا تكون علامة التبويب مرئية. ويعطّل shouldRetryOnError: false إعادة المحاولة التلقائية. ويعطّل revalidateOnFocus: false إعادة التحقق عند استعادة التركيز.

اجمعوا الخيارات بما يتوافق مع متطلبات حداثة بياناتكم؛ فكثيرًا ما تستخدم لوحات المعلومات refreshInterval، بينما يضبط المحتوى الثابت revalidateOnFocus: false.

بالنسبة إلى البيانات المقسمة إلى صفحات، أدرجوا رقم الصفحة في المفتاح: useSWR(['/api/items', page], fetcher). يؤدي تغيير الصفحة إلى جلب بيانات تلك الصفحة، مع تخزين الصفحات السابقة مؤقتًا.

يوفر SWR أيضًا useSWRInfinite لأنماط المؤشر أو التمرير اللانهائي، باستخدام دالة getKey التي تنشئ المفاتيح بناءً على فهرس الصفحة وبيانات الصفحة السابقة.

ماذا يحدث عند تمرير null بوصفه المفتاح إلى useSWR؟

يعيد useSWR(key, fetcher) قيم data وerror وisLoading وisValidating. وتعطّل المفاتيح التي قيمتها null الجلب للطلبات الشرطية والتابعة. وتشير isLoading إلى التحميل الأول، بينما تشير isValidating إلى أي طلب قيد التنفيذ. وتوحّد SWRConfig الإعدادات الافتراضية، ويحدث إلغاء ازدواجية الطلبات بين المكونات تلقائيًا.

تتيح خيارات مثل refreshInterval وrevalidateOnFocus وshouldRetryOnError ضبط سلوك حداثة البيانات بدقة لكل hook أو على مستوى التطبيق بأكمله.