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

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

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

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

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

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

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

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

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

Kotlin

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

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

Java

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

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

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

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

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

Kotlin

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
                // ...
            }
        }
    }
}

Java

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، كما هو موضّح في نموذج الرمز التالي:

Kotlin

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

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

Java

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

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

Java

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

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

Kotlin

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()
}

Java

@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.