سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط Google". يتضمن هذا التحديث على تصميم الخريطة لوحة ألوان تلقائية جديدة وتحسينات على تجارب الخرائط وسهولة الاستخدام. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. للمزيد من المعلومات عن مدى التوفّر وكيفية تفعيل الميزة في وقت سابق، يُرجى الاطّلاع على نمط الخريطة الجديد في "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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 OS

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

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

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

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

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

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

عليك تحديث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتضمين نظام التشغيل Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) أو إصدارًا أحدث، والذي يقدّم واجهات برمجة التطبيقات التي تسمح للأنشطة بالانتقال إلى الوضع المموّه. لمزيد من المعلومات حول كيفية تحديث حزمة SDK، اطّلِع على مستندات Android. حول إضافة حِزم SDK
تأكَّد من أنّ مشروعك يستهدف الإصدار 6.0 من نظام التشغيل Android أو إصدارًا أحدث، وذلك من خلال ضبط targetSdkVersion على 23 أو إصدار أحدث في بيان التطبيق.
أضِف التبعيات الخاصة بالأجهزة القابلة للارتداء إلى ملف build.gradle.kts في تطبيقك. يمكنك الاطّلاع على عيّنة في هذه الصفحة.
إضافة إدخال المكتبة المشتركة للجهاز القابل للارتداء إلى بيان تطبيق الأجهزة القابلة للارتداء، كما يلي: كما هو موضح في فصل تدريب Android حول إبقاء تطبيقك مرئيًا:
يُرجى إضافة إذن WAKE_LOCK إلى بيانات التطبيقات المحمولة والقابلة للارتداء، كما هو موضح في فصل تدريب Android حول إبقاء تطبيقك مرئيًا:
في طريقة onCreate() لنشاطك، استخدِم الأسلوب AmbientModeSupport.attach(). يُعلم ذلك نظام التشغيل بأنّ التطبيق مفعّل دائمًا، لذا عندما يتم إيقاف الجهاز، من المفترض أن يدخل في الوضع السينمائي بدلاً من الرجوع إلى شاشة الساعة.
نفِّذ واجهة AmbientModeSupport.AmbientCallbackProvider في Activity كي تتمكّن من تلقّي تغييرات حالة وضع الاستراحة.
اضبط خريطتك لدعم "وضع الإضاءة السينمائية". يمكنك إجراء ذلك من خلال ضبط السمة map:ambientEnabled="true" في ملف تنسيق XML للنشاط، أو يمكنك إجراء ذلك آليًا من خلال ضبط GoogleMapOptions.ambientEnabled(true). يُعلم هذا الإعداد واجهة برمجة التطبيقات بضرورة تحميل مربّعات الخرائط اللازمة مسبقًا ل استخدامها في الوضع السينمائي.
عند تبديل النشاط إلى "وضع الإضاءة السينمائية"، يستدعي النظام onEnterAmbient() في AmbientCallback التي تقدمها. يمكنك إلغاء onEnterAmbient() والاتصال بالرقم SupportMapFragment.onEnterAmbient(ambientDetails) أو MapView.onEnterAmbient(ambientDetails). تبدِّل واجهة برمجة التطبيقات الخريطة إلى رسومات غير تفاعلية وذات ألوان منخفضة.
وبالمثل، في 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();
            }
        };
    }
}

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

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

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

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

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

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

الوظائف المتاحة في Maps API على نظام التشغيل Wear OS

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

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

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

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

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