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

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

Maps API على Wear OS

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

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

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

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

يُعدّ Android Studio الأداة التي يُنصح بها لتطوير نظام التشغيل Wear OS، لأنّه يوفّر عملية إعداد المشاريع وإدراج المكتبة وتوفير وسائل راحة في وضع التغليف.

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

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

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

إضافة الاعتماديات إلى وحدة Wear OS

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

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 في تطبيقك. اطّلِع على النموذج في هذه الصفحة.
يمكنك إضافة إدخال المكتبة المشتركة الخاصة بالأجهزة القابلة للارتداء إلى بيان التطبيق الخاص بالأجهزة القابلة للارتداء، كما هو موضَّح في صف تدريب Android حول إبقاء تطبيقك مرئيًا.
يمكنك إضافة إذن WAKE_LOCK إلى بيانات التطبيقات المحمولة والقابلة للارتداء، كما هو موضّح في حصة Android التدريبية حول إبقاء التطبيق مرئيًا.
في طريقة onCreate() لنشاطك، يمكنك استدعاء الطريقة AmbientModeSupport.attach(). يؤدي ذلك إلى إعلام نظام التشغيل بأنّ التطبيق قيد التشغيل دائمًا، وبالتالي عند إيقاف تشغيل الجهاز، يدخل الجهاز في وضع الاستراحة بدلاً من الرجوع إلى خلفية شاشة الساعة.
يمكنك تنفيذ واجهة AmbientModeSupport.AmbientCallbackProvider في "نشاطك" حتى يتم تطبيق التغييرات على حالة "وضع الإضاءة السينمائية".
اضبط خريطتك لدعم "وضع الإضاءة السينمائية". يمكنك إجراء ذلك من خلال ضبط السمة 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();
            }
        };
    }
}

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

استخدام ميزة "التجوّل الافتراضي" على نظام التشغيل 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

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

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