Maps API على Wear OS

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

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

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

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

استوديو Android هو الأداة المُقترَحة لتطوير تطبيقات Wear OS، لأنّه يقدّم ميزات رائعة لإعداد المشاريع وتضمين المكتبات وإنشاء حِزم التطبيقات.

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

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

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

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

تأكَّد من تضمين الاعتماديات التالية في ملف build.gradle.kts. في وحدة 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:19.0.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. تأكد من أن مشروعك يستهدف الإصدار Android 6.0 أو الإصدارات الأحدث من خلال تحديد من targetSdkVersion إلى 23 أو أعلى في بيان التطبيق.
3. يمكنك إضافة الملحقات التابعة للأجهزة القابلة للارتداء إلى ملف build.gradle.kts في تطبيقك. يمكنك الاطّلاع على عيّنة في هذه الصفحة.
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

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

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