
باستخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android، يمكنك إنشاء تطبيق للأجهزة القابلة للارتداء مستند إلى الخريطة يعمل مباشرةً على أجهزة Wear OS by Google. يمكن لمستخدمي تطبيقك الاطّلاع على موقعهم الجغرافي على الخريطة بمجرّد إلقاء نظرة على معصمهم. يمكنهم، على سبيل المثال، تحديد موقعهم الجغرافي على مسار، ثم تكبير الخريطة للاطّلاع على التفاصيل، أو النقر على علامة للاطّلاع على نافذة معلومات يوفّرها تطبيقك.
توضّح هذه الصفحة وظائف واجهة برمجة التطبيقات المتاحة على جهاز Wear وتساعدك في بدء إنشاء تطبيقك.
البدء على 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)); }
تفعيل "وضع الاستراحة"
تتيح حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android استخدام وضع العرض المحيط في تطبيقات الأجهزة القابلة للارتداء. تُسمّى التطبيقات المتوافقة مع "وضع العرض المحيط" أحيانًا تطبيقات تعمل دائمًا. يتم تفعيل "وضع الاستراحة" عندما يتوقف المستخدم عن استخدام التطبيق بشكل نشط، ويسمح هذا الوضع ببقاء التطبيق مرئيًا على الجهاز القابل للارتداء.
توفّر حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android عرضًا مبسطًا للخريطة بألوان قليلة لاستخدامه في الوضع المحيط، ويتم تعديل نمط الخريطة تلقائيًا عندما ينتقل الجهاز من الوضع التفاعلي إلى الوضع المحيط. تختفي جميع العلامات والأشكال وعناصر التحكّم في واجهة المستخدم في الوضع المحيط. يساعد ذلك في تقليل استهلاك الطاقة في تطبيقك ويضمن توفير تجربة متسقة مع التطبيقات الأخرى التي تعمل في الخلفية، مثل خلفيات شاشة الساعة.
اتّبِع الخطوات التالية للتأكّد من أنّ تطبيقك يستخدم "وضع الإضاءة السينمائية" للخريطة:
- عليك تحديث حزمة تطوير البرامج (SDK) لنظام التشغيل Android لتضمين الإصدار 6.0 من نظام التشغيل Android (المستوى 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(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
للاستماع إلى إيماءة النقر مع الاستمرار. عندما ينقر المستخدم مع الاستمرار على مكان ما في صورة "التجوّل الافتراضي"، ستتلقّى حدث onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation)
. استخدِم الأمر Call
DismissOverlayView.show()
لعرض زر الخروج.
نموذج التعليمات البرمجية
يتوفّر تطبيق نموذجي على GitHub، ويمكنك استخدامه كنقطة بداية لتطبيقك. يوضّح لك النموذج كيفية إعداد خريطة Google أساسية على Wear OS.
الوظائف المتوافقة في Maps API على Wear OS
يوضّح هذا القسم الاختلافات في الوظائف المتاحة على الخرائط على الأجهزة القابلة للارتداء مقارنةً بالأجهزة المحمولة (الهواتف والأجهزة اللوحية). من المفترض أن تعمل جميع ميزات واجهة برمجة التطبيقات غير المذكورة أدناه على النحو الموضّح في المستندات الخاصة بواجهة برمجة التطبيقات الكاملة.
الوظائف | |
---|---|
الوضع التفاعلي الكامل والوضع البسيط | يمكنك استخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لتطبيقات Android في الوضع التفاعلي الكامل أو في الوضع البسيط. ننصحك باستخدام الوضع الخفيف إذا كنت تريد تحسين الأداء على الجهاز القابل للارتداء ولا يحتاج تطبيقك إلى إتاحة التفاعل، مثل الإيماءات أو تحريك الخريطة وتكبيرها وتصغيرها. في الوضع البسيط، يتم إيقاف الغرض من بدء تشغيل تطبيق "خرائط Google" للأجهزة الجوّالة عندما ينقر المستخدم على الخريطة، ولا يمكن تفعيله على جهاز قابل للارتداء. للاطّلاع على القائمة الكاملة بالاختلافات بين الوضع المبسّط والوضع التفاعلي الكامل، راجِع مستندات الوضع المبسّط. |
شريط أدوات الخريطة | شريط أدوات الخريطة غير مفعّل ولا يمكن تفعيله على جهاز قابل للارتداء. |
عناصر التحكّم في واجهة المستخدم | يتم إيقاف عناصر التحكّم في واجهة المستخدم تلقائيًا على الأجهزة القابلة للارتداء. ويشمل ذلك عناصر التحكّم في التكبير/التصغير والبوصلة والموقع الجغرافي. يمكنك تفعيلها باستخدام الفئة
UiSettings
كالمعتاد.
|
الإيماءات | تعمل الإيماءات التي تتطلّب لمسة واحدة على النحو المتوقّع. وتشمل الأمثلة النقر مع السحب لتحريك الخريطة، والنقر مرّتين للتكبير، والنقر بإصبعين للتصغير. يختلف مدى توفّر إيماءات اللمس المتعدد حسب جهاز المستخدم. تشمل أمثلة إيماءات اللمس المتعدد الدفع بإصبعين لإمالة الخريطة، والتصغير أو التكبير بإصبعين، والتدوير بإصبعين. |
الخرائط الداخلية والمباني |
يتم إيقاف الخرائط الداخلية تلقائيًا على الأجهزة القابلة للارتداء. يمكنك تفعيلها من خلال الاتصال بالرقم GoogleMap.setIndoorEnabled(true) . في حال تفعيل الخرائط الداخلية، ستعرض الخريطة مستوى الطابق التلقائي.
لا يتوافق عنصر واجهة المستخدم أداة اختيار
المستوى مع الأجهزة القابلة للارتداء. |
تراكب مربّعات | الإعلانات المركّبة على شكل مربّعات غير متاحة على الأجهزة القابلة للارتداء. |
أفضل الممارسات لتطوير التطبيقات باستخدام Maps API على Wear OS
كيفية تقديم أفضل تجربة للمستخدم في تطبيقك:
- يجب أن تشغل الخريطة جزءًا كبيرًا من الشاشة. وهذا ضروري لتحسين قابلية استخدام الخريطة على الأجهزة القابلة للارتداء ذات التصميم الصغير.
- عند تصميم تجربة المستخدم في تطبيقك، ضَع في اعتبارك أنّ الجهاز القابل للارتداء يتميز بانخفاض طاقة البطارية. سيؤثّر إبقاء الشاشة نشطة والخريطة مرئية في أداء البطارية.