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

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

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

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

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

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

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

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

توضّح لك هذه الوحدة التعليمية كيفية الحصول على آخر المعلومات باستخدام طريقة معاودة الاتصال 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 Activity.

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

مراجع إضافية

لمزيد من المعلومات، يمكنك الاستفادة من المَراجع التالية:

نماذج

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