Maps API على Wear OS

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

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

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

البدء على Wear OS

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

Kotlin

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


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

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

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

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

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

  1. حدِّث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتضمين الإصدار 6.0 من نظام التشغيل Android (المستوى 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 في نشاطك حتى تتمكن من تلقي تغييرات حالة الوضع المحيط.
  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(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 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 للاستماع إلى إيماءة النقر مع الاستمرار. عندما ينقر المستخدم مع الاستمرار على مكان ما في صورة &quot;التجوّل الافتراضي&quot;، ستتلقّى حدث onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). اتصل بـ DismissOverlayView.show() لعرض زر الخروج.

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

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

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

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

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

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

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

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

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

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

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