Hooks: ‏useQuery وuseMutation

يحلل وسم القالب gql من @apollo/client سلسلة استعلام GraphQL إلى DocumentNode عند تحميل الوحدة. عرّفوا الاستعلامات خارج المكونات: const GET_USERS = gql`query GetUsers { users { id name email } }`.

ملاحظة: في كود الإنتاج، استخدموا سلاسل نصية محاطة بعلامات اقتباس مفردة ولفّوها باستخدام gql كقالب موسوم. يقبل وسم gql صيغة القالب الحرفي في مصدر JavaScript.

يعيد useQuery(GET_USERS) القيمة { loading, error, data, refetch, fetchMore, networkStatus }. تكون loading بالقيمة true أثناء الجلب الأولي. وتحتوي error على أي أخطاء في GraphQL أو الشبكة. أما data فتحتوي على نتيجة الاستعلام المطابقة لبنيته.

تحققوا من loading وerror أولًا قبل الوصول إلى data لتجنب عرض قيم فارغة.

اعرضوا مكوّنًا هيكليًا عندما تكون loading بالقيمة true. واعرضوا رسالة خطأ إذا كانت error معرّفة (استخدموا error.message لنص الخطأ). ولا تعرضوا المحتوى الفعلي إلا عندما تكون data معرّفة وتكون loading بالقيمة false.

يُعد هذا النمط ثلاثي الحالات (loading / error / data) البنية القياسية لمكوّنات Apollo Client.

يعكس كائن data بنية استعلام GraphQL. في الاستعلام query { users { id name } }، يمكنك الوصول إلى data.users، وهي مصفوفة من الكائنات {id, name}. وتتطابق أنواع TypeScript عند استخدام graphql-codegen لتوليد الخطافات المعرّفة الأنواع.

من دون codegen، تكون data من النوع any. ومع codegen، يعيد useQuery بيانات مكتملة الأنواع تلقائيًا.

مرروا المتغيرات كوسيط ثانٍ: useQuery(GET_USER, { variables: { id: userId } }). يُعاد تشغيل الاستعلام تلقائيًا عند تغيّر userId، تمامًا كما يحدث مع مصفوفة تبعيات useEffect.

يخزّن Apollo Client كل تركيبة فريدة من الاستعلام والمتغيرات بشكل منفصل، ولذلك يملك GET_USER مع id: "1" وGET_USER مع id: "2" إدخالين مستقلين في الذاكرة المؤقتة.

مرروا skip: true في الخيارات لمنع تشغيل الاستعلام: useQuery(GET_USER, { skip: !userId }). لا يرسل Apollo الطلب عندما تكون skip بالقيمة true، وتكون loading بالقيمة false، بينما تكون data غير معرّفة.

هذا هو النظير في Apollo لمفتاح SWR ذي القيمة null وخيار React Query ‏enabled: false.

تطلق الدالة refetch التي يعيدها useQuery طلب شبكة بغض النظر عن سياسة الجلب. استدعوا refetch() بعد إجراء من المستخدم قد يكون قد غيّر بيانات الخادم، مثلًا refetch() بعد إرسال نموذج.

مرروا متغيرات جديدة إلى refetch: refetch({ id: newId }) لإعادة الجلب باستخدام معاملات مختلفة.

مرروا notifyOnNetworkStatusChange: true في الخيارات لتلقي تحديثات عند تغيّر حالة الشبكة (الجلب وإعادة الجلب والاستقصاء وغير ذلك). يحتوي الحقل networkStatus على رمز رقمي من التعداد NetworkStatus.

يتيح ذلك عرض مؤشر دقيق يفيد بأن التحديث جارٍ أثناء إعادة الجلب في الخلفية، من دون إخفاء البيانات الحالية.

يعيد useMutation(CREATE_USER) القيمة [mutateFunction, { loading, error, data, reset }]. وتُستدعى دالة mutate عندما يرسل المستخدم نموذجًا. وهي تعيد Promise يحتوي على { data, errors }.

استدعوا mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) لتمرير الإدخال إلى الطفرة.

مرروا onCompleted: (data) => navigate('/dashboard') وonError: (error) => showToast(error.message) إلى خيارات useMutation. ويُستدعى هذان الردّان بعد نجاح الطفرة أو رفضها.

يتلقى onCompleted بيانات نتيجة الطفرة، وهو مفيد لتشغيل التنقل، وعرض رسائل النجاح، أو إعادة تعيين النماذج.

يكتب الخيار optimisticResponse في استدعاء mutate نتيجة اصطناعية إلى الذاكرة المؤقتة فورًا قبل استجابة الخادم. ويعرض Apollo البيانات التفاؤلية مباشرة، ثم يستبدلها باستجابة الخادم الفعلية عند وصولها.

إذا فشلت الطفرة، يعيد Apollo الحالة السابقة للذاكرة المؤقتة تلقائيًا، مما يحافظ على اتساق واجهة المستخدم.

ماذا يحدث لاستدعاء useQuery عند تمرير skip: true؟

عرّفوا الاستعلامات باستخدام وسم gql، واستدعوا useQuery(QUERY, { variables, skip })، وعالجوا حالات loading وerror وdata. يعيد useMutation دالة تشغيل وكائن حالة؛ استدعوه مع المتغيرات وعالجوا النتائج باستخدام onCompleted وonError. تحدّث الاستجابات التفاؤلية الذاكرة المؤقتة فورًا مع التراجع التلقائي عند الفشل.

يتولى خيار skip وإعادة الجلب المعتمدة على المتغيرات تحميل البيانات المشروط والمحدد بالمعاملات.