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

ويمكن أن يكون الاستخدام المناسب لمعلومات الموقع الجغرافي مفيدًا لمستخدمي تطبيقك. على سبيل المثال، إذا كان تطبيقك يساعد المستخدم في معرفة طريقه أثناء المشي أو القيادة، أو إذا كان تطبيقك يتتبّع الموقع الجغرافي لمواد العرض، سيحتاج إلى معرفة الموقع الجغرافي للجهاز على فترات منتظمة. بالإضافة إلى الموقع الجغرافي (خط العرض وخط الطول)، ننصحك بتقديم المزيد من المعلومات للمستخدم، مثل الاتجاه (الاتجاه الأفقي للتنقّل) أو ارتفاع الجهاز أو سرعته. تتوفّر هذه المعلومات وغيرها في العنصر 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