Geolocation API في مكوّنات React
اطلب موقع المستخدم وتتّبعه باستخدام Geolocation API، وتعامل مع الأذونات ونظّف المراقبين
Geolocation API في مكوّنات React درس مجاني في React Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في React Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة React Academy 4 دروس في المجموع.
قراءة الموقع مرة واحدة
يطلب navigator.geolocation.getCurrentPosition(successCallback, errorCallback, options) موقع الجهاز مرة واحدة. تتلقى دالة النجاح كائن GeolocationPosition. يناسب ذلك الحالات التي تحتاج فيها إلى الموقع مرة واحدة، مثل العثور على أقرب متجر عند النقر على زر، بدلًا من تتبع الحركة باستمرار.
التتبع المستمر للموقع
يستدعي navigator.geolocation.watchPosition(successCallback, errorCallback, options) دالة الاستدعاء باستمرار كلما تغيّر موقع الجهاز. ويعيد قيمة رقمية باسم watchId. يناسب ذلك حالات الاستخدام الفورية مثل تتبع عمليات التوصيل أو الملاحة خطوة بخطوة، حيث يجب أن يظل الموقع محدّثًا.
كائن الموقع
يحتوي كائن GeolocationPosition على خاصية coords التي تتضمن latitude وlongitude وaccuracy (بالمتر). وتشمل الحقول الاختيارية الإضافية altitude وaltitudeAccuracy وheading وspeed. ويسجّل الحقل timestamp وقت التقاط الموقع.
رموز أخطاء تحديد الموقع الجغرافي
تتلقى دالة الخطأ كائن GeolocationPositionError يحتوي على خاصية رقمية باسم code. يعبّر الرمز 1 عن PERMISSION_DENIED (رفض المستخدم)، ويعبّر الرمز 2 عن POSITION_UNAVAILABLE (فشل في الأجهزة أو الشبكة)، ويعبّر الرمز 3 عن TIMEOUT (استغرق الطلب وقتًا أطول من اللازم). تعامل دائمًا مع الحالات الثلاث.
إلغاء المراقبة عند التنظيف
يستمر مستمع watchPosition في العمل بلا نهاية حتى توقفه. داخل useEffect، أعد دالة تنظيف تستدعي navigator.geolocation.clearWatch(watchId). إذا نسيت التنظيف، فسيستمر المراقب في العمل بعد إزالة المكوّن، مما يستنزف البطارية وقد يؤدي إلى تحديث حالة مكوّن لم يعد موجودًا.
إنشاء hook باسم useGeolocation
يدير hook باسم useGeolocation حالة status لها أربع قيم محتملة: idle (لم يُطلب الموقع بعد)، وloading (الطلب قيد التنفيذ)، وsuccess (تم استلام الموقع)، وerror (فشل الطلب). كما يحتفظ بحالتي position وerrorMessage. وبذلك تحصل المكوّنات على واجهة نظيفة ومتسقة.
التعامل بسلاسة مع رفض الإذن
عندما يرفض المستخدم تحديد الموقع الجغرافي، اعرض رسالة مفيدة توضّح سبب حاجة الميزة إلى الوصول إلى الموقع وكيفية إعادة تفعيله من إعدادات المتصفح. لا تعرض رمز خطأ خامًا للمستخدمين مطلقًا. وفّر بديلًا لإدخال العنوان يدويًا حتى تظل الميزة قابلة للاستخدام دون إذن الوصول إلى الموقع.
متطلب HTTPS لتحديد الموقع الجغرافي
مثل معظم واجهات API القوية في المتصفح، يقتصر تحديد الموقع الجغرافي على السياقات الآمنة. تكون قيمة navigator.geolocation هي undefined في صفحات HTTP العادية. أما أثناء التطوير على localhost، فيعمل دون HTTPS. في بيئة الإنتاج، تأكد دائمًا من تقديم تطبيقك عبر HTTPS، وإلا فلن يُطلب من المستخدمين منح الإذن.
خيارات الدقة والتوقيت
تقبل الوسيطة الاختيارية الثالثة في getCurrentPosition وwatchPosition كائن خيارات. يطلب enableHighAccuracy: true دقة بمستوى GPS مقابل استهلاك طاقة أكبر. وتحدد timeout الحد الأقصى لعدد المللي ثانية للانتظار. وتسمح maximumAge باستخدام موقع مخزّن مؤقتًا إذا كان قد التُقط خلال عدد المللي ثانية المحدد.
حالات الاستخدام الواقعية
يتيح تحديد الموقع الجغرافي ميزات مثل «العثور على متجر قريب مني»، وتتبع سائق التوصيل على الخريطة، وعرض حالة الطقس حسب المدينة الحالية، والمنشورات المرفقة بالموقع، وحساب المسافة بين المستخدم والوجهة. وضّح للمستخدمين دائمًا سبب حاجة التطبيق إلى موقعهم قبل طلب الإذن.
اختبار تحديد الموقع الجغرافي أثناء التطوير
يتيح Chrome DevTools ضبط موقع جهاز وهمي. افتح DevTools، وانتقل إلى قائمة النقاط الثلاث، ثم اختر More tools وبعد ذلك Sensors. يمكنك إدخال إحداثيات خط العرض وخط الطول لمحاكاة أي موقع. وهذا أسرع بكثير من الانتقال فعليًا لاختبار الميزات التي تعتمد على الموقع.
رموز أخطاء تحديد الموقع الجغرافي
ماذا يعني أن تكون قيمة code في GeolocationPositionError هي 1؟
مراجعة الدرس: Geolocation API في React
استخدم getCurrentPosition للقراءة مرة واحدة، وwatchPosition للتتبع المستمر. استدعِ clearWatch دائمًا داخل دالة التنظيف في useEffect. أنشئ hook باسم useGeolocation مع حالات idle وloading وsuccess وerror. تعامل مع رفض الإذن بسلاسة، وتذكّر أن تحديد الموقع الجغرافي يتطلب HTTPS في بيئة الإنتاج.
الأسئلة الشائعة
هل درس «Geolocation API في مكوّنات React» مجاني؟
نعم — نص درس «Geolocation API في مكوّنات React» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة React Academy، انتقل إلى CoddyKit PRO. تتضمن دورة React Academy 4 دروس في المجموع.
ماذا ستتعلم في «Geolocation API في مكوّنات React»؟
اطلب موقع المستخدم وتتّبعه باستخدام Geolocation API، وتعامل مع الأذونات ونظّف المراقبين تتمرن على React Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ React Academy؟
لا تُشترط خبرة سابقة. React Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.
كم من الوقت يستغرق درس «Geolocation API في مكوّنات React»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس React Academy هذا؟
نعم. كل درس في React Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- Clipboard API: النسخ واللصق في React
- Geolocation API في مكوّنات React
- Notifications API ومعالجة الأذونات
- IntersectionObserver للتأثيرات المحفَّزة بالتمرير