طلب تعديلات على الموقع الجغرافي

يمكن أن يكون الاستخدام المناسب لمعلومات الموقع الجغرافي مفيدًا لمستخدمي تطبيقك. على سبيل المثال، إذا كان تطبيقك يساعد المستخدم في العثور على طريقه أثناء المشي أو القيادة، أو إذا كان تطبيقك يتتبّع الموقع الجغرافي لملفات الأصول، يجب أن يحصل على الموقع الجغرافي للجهاز على فترات منتظمة. بالإضافة إلى الموقع الجغرافي (خط العرض وخط الطول)، قد تحتاج إلى تزويد المستخدم بمزيد من المعلومات، مثل الاتجاه (الاتجاه الأفقي للسفر) أو الارتفاع أو سرعة الجهاز. تتوفّر هذه المعلومات وغيرها في عنصر Location الذي يمكن لتطبيقك استرجاعه من موفِّر الموقع الجغرافي المدمج . استجابةً لذلك، تعمل واجهة برمجة التطبيقات على تحديث تطبيقك بشكل دوري بأفضل موقع جغرافي متاح، وذلك استنادًا إلى موفّري المواقع الجغرافية المتاحين حاليًا مثل WiFi وGPS (نظام تحديد المواقع العالمي). ويتم تحديد دقة الموقع الجغرافي من خلال مقدّمي الخدمات وأذونات تحديد الموقع الجغرافي التي طلبتها والخيارات التي أعددتها في طلب الموقع الجغرافي.

يوضّح لك هذا الدرس كيفية طلب تحديثات منتظمة عن الموقع الجغرافي للجهاز باستخدام طريقة requestLocationUpdates() في موفِّر الموقع الجغرافي المدمج.

الحصول على آخر موقع جغرافي معروف

يشكّل آخر موقع جغرافي معروف للجهاز قاعدة مفيدة للبدء، ما يضمن أن يكون للتطبيق موقع جغرافي معروف قبل بدء عمليات تحديث الموقع الجغرافي الدورية. يوضّح لك الدرس حول التعرّف على آخر موقع جغرافي معروف كيفية التعرّف على آخر موقع جغرافي معروف من خلال الاتصال برقم getLastLocation(). تفترض المقتطفات في الأقسام التالية أنّ تطبيقك سبق له استرداد آخر موقع جغرافي معروف وتخزينه كعنصر Location في المتغيّر العام mCurrentLocation.

تقديم طلب موقع جغرافي

قبل طلب تعديلات على الموقع الجغرافي، يجب أن يتصل تطبيقك بخدمات الموقع الجغرافي ويقدّم طلبًا للحصول على الموقع الجغرافي. يوضّح لك الدرس المتعلق بموضوع تغيير إعدادات الموقع الجغرافي كيفية إجراء ذلك. بعد تقديم طلب الموقع الجغرافي، يمكنك بدءتلقّي التعديلات العادية من خلال الاتصال بالرقم requestLocationUpdates().

استنادًا إلى نموذج الطلب، يستدعي مزوّد الموقع الجغرافي المدمج إما طريقة callback الخاصة بـ LocationCallback.onLocationResult() ويمرّر إليها قائمة بكائنات Location، أو يُصدر PendingIntent يحتوي على الموقع الجغرافي في بياناته الموسّعة. تتأثر دقة التحديثات ومعدّل تكرارها بأذونات الموقع الجغرافي التي طلبتها والخيارات التي ضبطتها في عنصر طلب الموقع الجغرافي.

توضّح لك هذه الدرس كيفية الحصول على التعديل باستخدام أسلوب callback LocationCallback . استخدِم الدالة requestLocationUpdates()، مع تمرير نسختك من عنصر LocationRequest وLocationCallback. حدِّد طريقة startLocationUpdates() كما هو موضّح في نموذج الرمز البرمجي التالي:

override fun onResume() {
    super.onResume()
    if (requestingLocationUpdates) startLocationUpdates()
}

private fun startLocationUpdates() {
    fusedLocationClient.requestLocationUpdates(locationRequest,
            locationCallback,
            Looper.getMainLooper())
}

@Override
protected void onResume() {
    super.onResume();
    if (requestingLocationUpdates) {
        startLocationUpdates();
    }
}

private void startLocationUpdates() {
    fusedLocationClient.requestLocationUpdates(locationRequest,
            locationCallback,
            Looper.getMainLooper());
}

يُرجى العلم أنّ المقتطف أعلاه يشير إلى علامة منطقية، requestingLocationUpdates، تُستخدَم لتتبُّع ما إذا كان المستخدم قد فعّل أو أوقف تعديلات الموقع الجغرافي. إذا أوقف المستخدمون تعديلات الموقع الجغرافي، يمكنك إبلاغهم بمتطلبات الموقع الجغرافي لتطبيقك. لمزيد من المعلومات عن الاحتفاظ بقيمة العلامة المنطقية في جميع نُسخ الحدث، اطّلِع على حفظ حالة الحدث.

تحديد الإجراء الذي يتم تنفيذه عند تحديث الموقع الجغرافي

يستدعي موفِّر الموقع الجغرافي المدمج طريقة معاودة الاتصال LocationCallback.onLocationResult(). تحتوي الوسيطة الواردة على عنصر قائمة Location يحتوي على خطي العرض والطول للموقع الجغرافي. يوضّح المقتطف التالي كيفية تنفيذ واجهة LocationCallback وتحديد الطريقة، ثم الحصول على الطابع الزمني لتعديل الموقع الجغرافي وعرض خط العرض وخط الطول والطابع الزمني على واجهة المستخدم في تطبيقك:

private lateinit var locationCallback: LocationCallback

// ...

override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    locationCallback = object : LocationCallback() {
        override fun onLocationResult(locationResult: LocationResult?) {
            locationResult ?: return
            for (location in locationResult.locations){
                // Update UI with location data
                // ...
            }
        }
    }
}

private LocationCallback locationCallback;

// ...

@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...

    locationCallback = new LocationCallback() {
        @Override
        public void onLocationResult(LocationResult locationResult) {
            if (locationResult == null) {
                return;
            }
            for (Location location : locationResult.getLocations()) {
                // Update UI with location data
                // ...
            }
        }
    };
}

إيقاف تحديثات الموقع الجغرافي

ننصحك بالتفكير في ما إذا كنت تريد إيقاف تعديلات الموقع الجغرافي عندما يتوقف التركيز على النشاط، مثل عندما ينتقل المستخدم إلى تطبيق آخر أو إلى نشاط مختلف في التطبيق نفسه. يمكن أن يكون ذلك مفيدًا لتقليل استهلاك الطاقة، شرط ألا يحتاج التطبيق إلى جمع المعلومات حتى عندما يكون قيد التشغيل في الخلفية. يوضّح هذا القسم كيفية إيقاف عمليات التعديل في الأسلوب onPause() للنشاط.

لإيقاف تحديثات الموقع الجغرافي، اتصل بـ removeLocationUpdates()، مع تضمين LocationCallback، كما هو موضّح في نموذج الرمز البرمجي التالي:

override fun onPause() {
    super.onPause()
    stopLocationUpdates()
}

private fun stopLocationUpdates() {
    fusedLocationClient.removeLocationUpdates(locationCallback)
}

@Override
protected void onPause() {
    super.onPause();
    stopLocationUpdates();
}

private void stopLocationUpdates() {
    fusedLocationClient.removeLocationUpdates(locationCallback);
}

استخدِم قيمة منطقية، requestingLocationUpdates، لتتبُّع ما إذا كانت تعديلات الموقع الجغرافي مفعّلة حاليًا. في طريقة onResume() الخاصة بالنشاط، تحقَّق مما إذا كانت تعديلات الموقع الجغرافي نشطة في الوقت الحالي، وفعِّلها إن لم تكن نشطة:

override fun onResume() {
    super.onResume()
    if (requestingLocationUpdates) startLocationUpdates()
}

@Override
protected void onResume() {
    super.onResume();
    if (requestingLocationUpdates) {
        startLocationUpdates();
    }
}

حفظ حالة النشاط

يمكن أن يؤدي تغيير في إعدادات الجهاز، مثل تغيير اتجاه الشاشة أو اللغة، إلى إتلاف النشاط الحالي. لذلك، يجب أن يخزن تطبيقك أي معلومات يحتاج إليها لإعادة إنشاء النشاط. تتمثل إحدى طرق إجراء ذلك في حالة مثيل مخزّنة في Bundle.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام الدالة المرجعية onSaveInstanceState() للنشاط لحفظ حالة المثيل:

override fun onSaveInstanceState(outState: Bundle?) {
    outState?.putBoolean(REQUESTING_LOCATION_UPDATES_KEY, requestingLocationUpdates)
    super.onSaveInstanceState(outState)
}

@Override
protected void onSaveInstanceState(Bundle outState) {
    outState.putBoolean(REQUESTING_LOCATION_UPDATES_KEY,
            requestingLocationUpdates);
    // ...
    super.onSaveInstanceState(outState);
}

حدِّد طريقة updateValuesFromBundle() لاستعادة القيم المحفوظة من النسخة السابقة من النشاط، إذا كانت متاحة. استدعِ الطريقة من طريقة onCreate() للنشاط، كما هو موضّح في نموذج الرمز البرمجي التالي:

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    updateValuesFromBundle(savedInstanceState)
}

private fun updateValuesFromBundle(savedInstanceState: Bundle?) {
    savedInstanceState ?: return

    // Update the value of requestingLocationUpdates from the Bundle.
    if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) {
        requestingLocationUpdates = savedInstanceState.getBoolean(
                REQUESTING_LOCATION_UPDATES_KEY)
    }

    // ...

    // Update UI to match restored state
    updateUI()
}

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...
    updateValuesFromBundle(savedInstanceState);
}

private void updateValuesFromBundle(Bundle savedInstanceState) {
    if (savedInstanceState == null) {
        return;
    }

    // Update the value of requestingLocationUpdates from the Bundle.
    if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) {
        requestingLocationUpdates = savedInstanceState.getBoolean(
                REQUESTING_LOCATION_UPDATES_KEY);
    }

    // ...

    // Update UI to match restored state
    updateUI();
}

لمزيد من المعلومات حول حفظ حالة المثيل، يُرجى الاطّلاع على مرجع فئة نشاط Android.

ملاحظة: للحصول على مساحة تخزين دائمة، يمكنك تخزين الإعدادات المفضّلة للمستخدم في SharedPreferences تطبيقك. اضبط الإعداد المفضّل المشترَك في طريقة onPause() لنشاطك، ثم استرجع الإعداد المفضّل في onResume(). لمزيد من المعلومات عن حفظ الإعدادات المفضّلة، يُرجى الاطّلاع على مقالة حفظ مجموعات مفاتيح القيمة.

مصادر إضافية

لمزيد من المعلومات، يمكنك الاطّلاع على المراجع التالية:

نماذج

• نموذج تطبيق يوضّح تلقّي آخر المعلومات حول الموقع الجغرافي في Android