Maps API على Wear OS

باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android، يمكنك إنشاء تطبيق قابل للارتداء يستند إلى الخريطة ويعمل مباشرةً على أجهزة "Wear OS من Google". يمكن لمستخدمي تطبيقك رؤية موقعهم على الخريطة بمجرد إلقاء نظرة على معصمهم. ويمكنهم تحديد موضعهم على أحد المسارات، على سبيل المثال، ثم التكبير لمعرفة التفاصيل، أو النقر على علامة لعرض نافذة معلومات يوفّرها تطبيقك.

تصف هذه الصفحة وظائف واجهة برمجة التطبيقات المتاحة على جهاز Wear وتساعدك على بدء إنشاء تطبيقك.

بدء استخدام نظام التشغيل Wear OS

إنّ إنشاء تطبيق قابل للارتداء باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android يشبه في الأساس إنشاء تطبيق "خرائط Google" لأي جهاز Android آخر. يكمن الفرق في تصميمك ذي الشكل الأصغر للجهاز القابل للارتداء، بهدف تحسين سهولة استخدام التطبيق وأدائه.

إنّ استوديو Android هو الأداة التي يُنصح بها لتطوير نظام التشغيل Wear OS، لأنه يوفّر إمكانية إعداد المشاريع وتضمين المكتبة وتوفير سهولة عملية إنشاء المحتوى.

للحصول على مساعدة عامة بشأن تصميم تطبيق قابل للارتداء، يمكنك الاطّلاع على إرشادات تصميم Wear OS. للحصول على المساعدة في إنشاء أول تطبيق قابل للارتداء، راجع دليل إنشاء تطبيقات قابلة للارتداء.

إنشاء أول تطبيق خرائط على Wear OS

يفترض هذا الدليل السريع أنّك على دراية بحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android، وأنّك اتّبعت أدلة Wear OS لإنشاء وحدة قابلة للارتداء في تطبيقك، وأنّك تريد الآن إضافة خريطة إلى الوحدة القابلة للارتداء.

إضافة التبعيات لوحدة الملابس الخاصة بك

تأكَّد من تضمين التبعيات التالية في ملف build.gradle ضمن وحدة Wear OS في تطبيقك:

dependencies {
    // ...
    compileOnly 'com.google.android.wearable:wearable:2.9.0'
    implementation 'com.google.android.support:wearable:2.9.0'
    implementation 'com.google.android.gms:play-services-maps:18.2.0'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.3.0'
}

للمزيد من المعلومات حول التبعيات، يمكنك الاطّلاع على دليل إضافة وحدة Wear OS في مشروعك الحالي.

تنفيذ إيماءة التمرير السريع للإغلاق وضبط اللون الأولي للخلفية

ننصحك باستخدام SwipeDismissFrameLayout لعرض الخريطة على الجهاز القابل للارتداء. باستخدام الفئة SwipeDismissFrameLayout، يمكنك تنفيذ إيماءة التمرير السريع إلى التجاهل التي تمنح المستخدمين طريقة للخروج من التطبيق عن طريق التمرير سريعًا من أقصى حافة يسار الشاشة.

لضبط لون خلفية مبدئي مخصّص، استخدِم سمة XML الخاصة بـ map:backgroundColor لتحديد اللون المطلوب عرضه إلى أن يتم تحميل مربّعات الخرائط الفعلية.

أضِف العنصرَين SwipeDismissFrameLayout وbackgroundColor إلى تعريف التنسيق باعتباره حاوية SupportMapFragment:

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

عند الحصول على الكائن SwipeDismissFrameLayout في نشاطك، عليك إضافة زر استدعاء وضبط سلوك معاودة الاتصال من أجل تنفيذ إجراء الرفض اللازم كما هو موضّح أدناه:

class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {


    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {


    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

إضافة خريطة

استخدِم طريقة معاودة الاتصال في onMapReady(GoogleMap) كالمعتاد للحصول على إمكانية التعامل مع كائن GoogleMap. يتم تشغيل معاودة الاتصال عندما تكون الخريطة جاهزة للاستخدام. في طريقة معاودة الاتصال، يمكنك إضافة علامات أو خطوط متعددة إلى الخريطة، أو إضافة مستمعين، أو تحريك الكاميرا. يضيف المثال أدناه علامة بالقرب من دار أوبرا سيدني:

private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

تفعيل "وضع الإضاءة السينمائية"

تتوافق حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android مع الوضع المحيطي للتطبيقات القابلة للارتداء. أحيانًا يُطلق على التطبيقات التي تتيح وضع الاستراحة اسم التطبيقات قيد التشغيل دائمًا. يتم تفعيل "وضع الاستراحة" عندما يتوقف المستخدم عن استخدام التطبيق بشكل نشط، ويسمح له بأن يظل مرئيًا على الجهاز القابل للارتداء.

توفّر حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android إمكانية عرض الخريطة بطريقة مبسّطة ومنخفضة الألوان لاستخدامها في "وضع الإضاءة السينمائية"، ويتم تعديل نمط الخريطة تلقائيًا عند تبديل الجهاز من الوضع التفاعلي إلى وضع الصوت المحيط. تختفي جميع العلامات والكائنات وعناصر التحكم في واجهة المستخدم في وضع الصوت المحيط. يؤدي ذلك إلى تقليل استهلاك الطاقة لتطبيقك ويضمن الحصول على مظهر ومضمون متسقين مع التطبيقات المحيطة الأخرى، مثل خلفيات شاشة الساعة.

اتّبِع الخطوات التالية للتأكّد من أنّ تطبيقك يستخدم وضع الصوت المحيط في الخريطة:

1. حدِّث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتتضمن النظام الأساسي Android 6.0 (API 23) أو الإصدارات الأحدث، ما يوفّر واجهات برمجة تطبيقات تسمح بانتقال الأنشطة إلى وضع عدم النشاط. لمزيد من المعلومات حول طريقة تحديث حزمة SDK، يمكنك مراجعة مستندات Android حول إضافة حزم SDK.
2. تأكَّد من أنّ مشروعك يستهدف الإصدار 6.0 من نظام التشغيل Android أو الإصدارات الأحدث من خلال ضبط targetSdkVersion على 23 أو إصدار أحدث في بيان التطبيق.
3. أضِف البرامج الاعتمادية القابلة للارتداء إلى ملف build.gradle الخاص بتطبيقك. اطّلِع على النموذج في هذه الصفحة.
4. أضِف إدخال المكتبة المشتركة للأجهزة القابلة للارتداء إلى بيان التطبيق القابل للارتداء، كما هو موضّح في الصف التدريبي بشأن Android حول الحفاظ على ظهور التطبيق.
5. أضِف إذن WAKE_LOCK إلى بيانات التطبيقات التي يتم حملها باليد والتطبيقات القابلة للارتداء، كما هو موضّح في الصف التدريبي لنظام Android حول الحفاظ على ظهور تطبيقك.
6. في طريقة onCreate() لنشاطك، عليك استدعاء طريقة AmbientModeSupport.attach(). يشير ذلك إلى نظام التشغيل أنّ التطبيق قيد التشغيل دائمًا، وبالتالي عندما يتم إيقاف الجهاز، يجب أن يدخل في وضع الاستراحة بدلاً من الرجوع إلى خلفية شاشة الساعة.
7. يمكنك تنفيذ واجهة AmbientModeSupport.AmbientCallbackProvider في قسم "النشاط" لكي تتلقّى أي تغييرات في حالة وضع الاستراحة.
8. اضبط الخريطة بما يتوافق مع "وضع الإضاءة السينمائية". يمكنك تنفيذ هذا الإجراء من خلال ضبط السمة map:ambientEnabled="true" في ملف تنسيق XML الخاص بالنشاط، أو تنفيذ ذلك بشكل آلي من خلال ضبط GoogleMapOptions.ambientEnabled(true). يُعلِم هذا الإعداد واجهة برمجة التطبيقات بضرورة تحميل مربّعات الخرائط اللازمة مسبقًا لاستخدامها في "وضع الإضاءة السينمائية".
9. عند تبديل النشاط إلى "وضع الإضاءة السينمائية"، يستدعي النظام طريقة onEnterAmbient() في AmbientCallback التي يتم توفيرها. يمكنك إلغاء onEnterAmbient() والاتصال SupportMapFragment.onEnterAmbient(ambientDetails) أو MapView.onEnterAmbient(ambientDetails). تتبدّل واجهة برمجة التطبيقات إلى عرض غير تفاعلي ومنخفض الألوان للخريطة.
10. وبالمثل، في onExitAmbient()، يمكنك استدعاء SupportMapFragment.onExitAmbient() أو MapView.onExitAmbient(). تبديل واجهة برمجة التطبيقات بالعرض العادي للخريطة.

يعمل نموذج الرمز البرمجي التالي على تفعيل "وضع الصوت المحيط" في النشاط:

class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

يمكنك تحديث الشاشة عندما يكون التطبيق في "وضع الإضاءة السينمائية". للحصول على مزيد من التفاصيل حول تحديث المحتوى وحول "وضع الإضاءة السينمائية" بشكل عام، يمكنك الاطّلاع على دورة تدريب Android حول الحفاظ على ظهور تطبيقك.

استخدام ميزة "التجوّل الافتراضي" على نظام التشغيل Wear OS

تتوافق ميزة التجوّل الافتراضي بالكامل مع الأجهزة القابلة للارتداء.

للسماح للمستخدمين بالخروج من التطبيق عند مشاهدة بانوراما في "التجوّل الافتراضي"، استخدِم واجهة StreetViewPanorama.OnStreetViewPanoramaLongClickListener للاستماع إلى إيماءة النقر الطويل. عندما ينقر المستخدم لفترة طويلة في مكان ما على صورة "التجوّل الافتراضي"، سيصلك حدث onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). الاتصال بـ DismissOverlayView.show() لعرض زر خروج

نموذج التعليمات البرمجية

يتوفّر نموذج تطبيق على GitHub يمكنك استخدامه كنقطة بداية لتطبيقك. ويوضّح لك النموذج كيفية إعداد "خرائط Google" أساسية على نظام التشغيل Wear OS.

الوظائف المتوافقة في Maps API على نظام التشغيل Wear OS

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

أفضل ممارسات التطوير باستخدام Maps API على Wear OS

كيفية تقديم أفضل تجربة للمستخدم في تطبيقك:

• يجب أن تشغل الخريطة جزءًا كبيرًا من الشاشة. وهذا ضروري لتحسين قابلية استخدام الخريطة على شكل جهاز قابل للارتداء.
• عند تصميم تجربة المستخدم لتطبيقك، يجب أن تضع في اعتبارك حقيقة أن الجهاز القابل للارتداء يحتوي على طاقة بطارية منخفضة. سيؤثر الحفاظ على تنشيط الشاشة والخريطة مرئية في أداء البطارية.