Maps API على Wear OS

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

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

بدء استخدام Wear OS

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

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

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

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

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

إضافة تبعيات لوحدة Wear

تأكَّد من تضمين الارتباطات التالية في ملف 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.1.0'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.2.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 في نشاطك، أضِف معاودة اتصال واضبط سلوك معاودة الاتصال لتنفيذ إجراء الرفض الضروري كما هو موضّح في ما يلي:

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

    // ...
}

      

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

    // ...
}

      

إضافة خريطة

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

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

      

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

      

تفعيل وضع الاستراحة

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

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

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

1. حدِّث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتضمين نظام التشغيل Android 6.0 (واجهة برمجة التطبيقات 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(). وتبدّل واجهة برمجة التطبيقات إلى العرض العادي للخريطة.

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

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

      

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

      

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

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

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

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

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

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

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

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

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

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

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