Maps API على Wear OS

خريطة على جهاز قابل للارتداء

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

توضِّح هذه الصفحة وظائف واجهة برمجة التطبيقات المتاحة على جهاز Wear OS، وhelps you get started building your app.

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

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

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

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

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

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

لضبط لون خلفية أولي مخصّص، استخدِم سمة 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 في نشاطك، أضِف دالّة callback وضبط سلوك دالّة callback لتنفيذ الإجراء اللازم لإغلاق كما هو موضّح أدناه:

Kotlin

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

    // ...
}

      

Java

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. يتم بدء عملية callback عندما تكون الخريطة جاهزة للاستخدام. في طريقة الاستدعاء، يمكنك إضافة علامات أو خطوط متعددة إلى الخريطة أو إضافة مستمعين أو تحريك الكاميرا. في المثال أدناه، تتم إضافة علامة بالقرب من دار أوبرا سيدني:

Kotlin

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

      

Java

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

      

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

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

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

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

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

يُفعِّل نموذج الرمز البرمجي التالي وضع الإضاءة السينمائية في النشاط:

Kotlin

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

      

Java

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

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

الوظائف
الوضع التفاعلي بالكامل والوضع البسيط

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

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

للحصول على قائمة كاملة بالاختلافات بين "الوضع البسيط" و"الوضع التفاعلي بالكامل"، اطّلِع على مستندات الوضع البسيط.

شريط أدوات الخريطة شريط أدوات الخريطة متوقف ولا يمكن تفعيله على جهاز قابل للارتداء.
عناصر التحكّم في واجهة المستخدم تكون عناصر التحكّم في واجهة المستخدم غير مفعَّلة تلقائيًا على الأجهزة القابلة للارتداء. ويشمل ذلك عناصر التحكّم في التكبير/التصغير والبوصلة و"موقعي الجغرافي". يمكنك تفعيلها باستخدام فئة UiSettings كالمعتاد.
الإيماءات تعمل إيماءات اللمسة الواحدة على النحو المتوقّع. ومن الأمثلة على ذلك النقر والسحب للتدوير على الخريطة والنقر مرّتين للتكبير والنقر بإصبعَين للتصغير. يختلف مدى توفّر إيماءات اللمس المتعدّد حسب جهاز المستخدم. تشمل أمثلة إيماءات اللمس المتعدّدة الضغط بإصبعَين لإمالة الخريطة، والتصغير أو التكبير بإصبعَين، والدوران بإصبعَين.
الخرائط الداخلية والمباني تكون الخرائط الداخلية غير مفعّلة تلقائيًا على الجهاز القابل للارتداء. يمكنك تفعيلها من خلال الاتصال بالرقم: GoogleMap.setIndoorEnabled(true). إذا كانت الخرائط الداخلية مفعَّلة، ستعرِض الخريطة مستوى الأرضية التلقائي. لا يتوفّر عنصر واجهة المستخدم أداة اختيار المستوى على الأجهزة القابلة للارتداء.
تراكب المربّعات العناصر المركّبة على مربّعات البيانات غير متاحة على الأجهزة القابلة للارتداء.

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

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

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