Maps API على Wear OS

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

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

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

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

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

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

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

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

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

أضف 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))
}

      

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

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

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

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

1. يمكنك تحديث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتضمين نظام التشغيل Android 6.0 (واجهة برمجة التطبيقات 23) أو النظام الأساسي الأحدث، الذي يوفر واجهات برمجة التطبيقات التي تسمح للأنشطة بالدخول في وضع عدم النشاط. للحصول على معلومات حول كيفية تحديث حزمة SDK، راجع مستندات Android حول إضافة حزم SDK.
2. تأكد من أن مشروعك يستهدف الإصدار Android 6.0 أو إصدارًا أحدث، من خلال تعيين 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) آليًا. يبلغ هذا الإعداد واجهة برمجة التطبيقات (API) بضرورة التحميل المسبق لمربعات الخرائط اللازمة لاستخدامها في "وضع الاستراحة".
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

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

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

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

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

الوظائف المتوافقة في واجهة برمجة تطبيقات الخرائط على نظام التشغيل Wear OS

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

أفضل الممارسات للتطوير باستخدام واجهة برمجة تطبيقات الخرائط على نظام التشغيل Wear OS

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

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