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

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

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

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

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

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

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

استنادًا إلى نموذج الطلب، يستدعي مزوّد الموقع الجغرافي المدمج إما طريقة callback الخاصة بـ 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() method للنشاط، تحقَّق مما إذا كانت تعديلات الموقع الجغرافي مفعّلة حاليًا، وفعِّلها إذا لم تكن كذلك:

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() activity's كما هو موضّح في المثال التالي للرمز البرمجي:

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