أغراض خرائط Google لنظام التشغيل Android Automotive

من خلال Android intents، يمكنك بدء التنقّل في "خرائط Google" لنظام التشغيل Android Automotive.

نظرة عامة

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

• Intents and Intent Filters
• الطلبات الشائعة في نظام Android الأساسي

طلبات Intent

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

• الإجراء: يتم استدعاء جميع أغراض "خرائط Google" كإجراء عرض، ACTION_VIEW.

• معرّف الموارد المنتظم (URI) تستخدم أهداف "خرائط Google" سلاسل مرمّزة بمعرّف الموارد المنتظم (URI) تحدّد إجراءً تم اختياره، بالإضافة إلى بعض البيانات التي يتم تنفيذ الإجراء من خلالها.

• الحزمة: يضمن استدعاء setPackage("com.google.android.apps.maps") أن يتعامل تطبيق "خرائط Google" لنظام التشغيل Android مع Intent. إذا لم يتم ضبط الحزمة، يحدّد النظام التطبيقات التي يمكنها معالجة Intent. إذا كانت هناك تطبيقات متعددة متاحة، قد يُطلب منك اختيار التطبيق الذي تريد استخدامه.

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

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

إذا لم يتمكّن النظام من تحديد تطبيق يمكنه الاستجابة للطلب، قد يتعطّل تطبيقك. لهذا السبب، يجب أولاً التحقّق من تثبيت تطبيق مستلِم قبل عرض أحد هذه الأغراض للمستخدم.

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

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

على سبيل المثال، لتشغيل الاتجاهات المفصّلة إلى حديقة حيوان تارونغا في سيدني، يمكنك استخدام الرمز التالي:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

سلاسل طلبات البحث المرمّزة بمعرّف الموارد المنتظم (URI)

يجب أن تكون جميع السلاسل التي يتم تمريرها إلى أهداف "خرائط Google" مرمّزة بمعرّف الموارد المنتظم (URI). على سبيل المثال، يجب أن تصبح السلسلة "1st & Pike, Seattle" على النحو التالي: 1st%20%26%20Pike%2C%20Seattle. يمكن ترميز المسافات في السلسلة باستخدام %20 أو استبدالها بعلامة الجمع (+).

يمكنك استخدام طريقة android.net.Uri encode() لترميز السلاسل. على سبيل المثال:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

عرض خريطة

استخدِم الغرض geo: لعرض خريطة في موقع جغرافي ومستوى تكبير محدّدَين. على سبيل المثال:

geo:latitude,longitude?z=zoom

المعلَمات

• يحدّد latitude وlongitude نقطة مركز الخريطة.

• يضبط z مستوى التكبير الأولي للخريطة بشكل اختياري. تتراوح القيم المقبولة بين 0 (العالم بأكمله) و21 (المباني الفردية). قد يختلف الحد الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.

مثال

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

البحث عن موقع جغرافي

استخدِم هذا الغرض لعرض طلبات البحث ضمن إطار عرض محدّد:

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

المعلَمات

بالإضافة إلى المَعلمات المستخدَمة لعرض خريطة، يتيح محرّك بحث Google استخدام المَعلمة التالية:

• يحدّد q الأماكن التي يجب إبرازها على الخريطة. مَعلمة q مطلوبة لجميع طلبات البحث. تقبل هذه الدالة موقعًا جغرافيًا كاسم مكان أو عنوان. يجب أن تكون السلسلة متوافقة مع عناوين URL، لذا يجب تحويل عنوان مثل "City Hall, New York, NY" إلى City+Hall%2CNew+York%2CNY.

توجيه نتائج البحث باستخدام الإحداثيات

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

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

تؤدي إضافة خط العرض وخط الطول إلى معرّف الموارد المنتظم (URI) الخاص بالطلب إلى تحيز النتائج نحو منطقة معيّنة:

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

البحث على طول المسار

إذا تم إرسال نية من عملية البحث geo:latitude,longitude?q=query أثناء التنقّل، يؤدي ذلك إلى بدء عملية بحث على طول المسار ويتم تجاهل خط العرض وخط الطول.

البحث عن فئات محدَّدة مسبقًا

لإتاحة التكامل مع المركبة، يتيح تطبيق "خرائط Google" في السيارة استخدام النيّة التي تعرض هذه الفئات المحدّدة مسبقًا:

يكون هدف الفئة على شكل geo:lat,lng?c=category.

استخدِم c=<pre-defined category> بغض النظر عن إعدادات لغة المستخدم. تعرض "خرائط Google" النتائج ذات الصلة في اللغة والمنطقة المناسبتَين لهذه الفئة. على سبيل المثال:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

عمليات بحث أخرى حسب الفئة

إذا أدخلت عبارة بحث عامة (مثل "مطاعم" أو "مقاهٍ") في لغة المستخدم، يبحث تطبيق "خرائط Google" لنظام التشغيل Android Automotive عن بيانات المؤسسات التي تطابق المعايير. إذا تم توفير خط عرض وخط طول محدّدَين في نية geo:، يتمحور البحث حول هذا الموقع الجغرافي. إذا لم يتم تحديد موقع جغرافي (مثل geo:0,0)، تحاول "خرائط Google" العثور على بيانات المؤسسات القريبة. على سبيل المثال:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

يمكنك زيادة تحسين نتائج البحث من خلال تحديد مَعلمة التكبير مع سلسلة طلب البحث. في المثال التالي، تؤدي إضافة مستوى تكبير بقيمة 10 إلى محاولة العثور على مطاعم على مستوى المدينة بدلاً من المطاعم المجاورة:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

بدء الاتجاهات المفصّلة

للحصول على مستندات حول تشغيل الاتجاهات المفصّلة على أجهزة Android الأخرى، يُرجى الاطّلاع على تشغيل الاتجاهات المفصّلة في Google Maps Intents لنظام التشغيل Android.

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

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

المعلَمات

لبدء التنقّل، استخدِم place أو q مع waypoints، وهو أمر اختياري. لتحديد نقطة على المسار كمحطة شحن، راجِع مقالة إرسال خطة رحلة لمركبة كهربائية إلى "خرائط Google".

• يحدّد q نقطة النهاية لعمليات البحث عن التنقّل. يمكن أن يكون هذا خط عرض وخط طول أو عنوانًا منسقًا للاستعلام. إذا كانت سلسلة طلب بحث تعرض أكثر من نتيجة واحدة، سيتم اختيار النتيجة الأولى.

• يضبط "place" نقطة النهاية على المنزل أو العمل. حدِّد "home" (المنزل) للانتقال إلى منزل المستخدم، و"work" (العمل) للانتقال إلى مكان عمل المستخدم.

• يحدّد avoid الميزات التي يجب أن يحاول المسار تجنّبها. ‫avoid هو مَعلمة اختيارية ويمكن ضبطه على قيمة واحدة أو أكثر من القيم التالية:

  • ‫t لرسوم العبور
  • ‫h للطرق السريعة
  • ‫f للعبّارات

• تحدّد السمة waypoints مكانًا وسيطًا واحدًا أو أكثر لتوجيه الاتجاهات إلى الوجهة النهائية المحدّدة في السمة q. يمكنك تحديد نقاط متعددة على المسار باستخدام حرف التوجيه (|) للفصل بين الأماكن، على سبيل المثال، Berlin,Germany|Paris,France. يمكنك استخدام أي عدد تريده من النقاط على المسار. ستتم إضافة النقاط على المسار بالترتيب نفسه الذي تظهر به في عنوان URL. يمكن أن تكون كل نقطة على المسار إما عنوانًا أو إحداثيات خطوط عرض وطول مفصولة بفاصلة، ويمكنك استخدام العناوين وإحداثيات خطوط العرض والطول في الطلب نفسه. يجب أن تكون السلاسل مُعدَّلة لتجنُّب استخدام أحرف خاصة في عناوين URL، لذا يجب تحويل النقاط على المسار مثل "Berlin,Germany|Paris,France" إلى Berlin%2CGermany%7CParis%2CFrance.

أمثلة

سيطلب هذا الغرض اتجاهات مفصّلة إلى حديقة حيوان تارونغا في سيدني، أستراليا:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

إذا كنت تفضّل عدم دفع رسوم عبور أو ركوب عبّارة، يمكنك طلب مسار يحاول تجنُّب هذه الحالات:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

أو إذا أردت الانتقال إلى منزلك، استخدِم:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

لتشغيل الاتجاهات المفصّلة إلى العناوين الثلاثة التالية بالترتيب، مرِّر Taronga Zoo كوجهة نهائية q، وGoogle Sydney وSydney Opera House كنقاط على المسار:

1. ‫Google سيدني

2. دار أوبرا سيدني

3. حديقة حيوان تارونغا، سيدني، أستراليا

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

على غرار q، يمكنك تمثيل أي من النقاط على المسار باستخدام خطوط العرض والطول المفصولة بفواصل بدلاً من العنوان. على سبيل المثال، لتشغيل التنقّل نفسه مع تمرير خط العرض وخط الطول لدار أوبرا سيدني بدلاً من العنوان:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

إرسال خطة رحلة لمركبة كهربائية إلى "خرائط Google"

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

بالنسبة إلى محطات الشحن وأغراض الرحلات:

• يجب أن يحتوي على اسم وخط عرض وخط طول
• قد تحتوي اختياريًا على مخرجات الطاقة، لاستخدامها في احتساب وقت الشحن

تستخدم Google اسم محطة الشحن وخطوط العرض والطول للعثور على مكان محطة شحن مطابق لعرض بيانات وافية مثل أنواع الموصلات وإجمالي عددها وسرعاتها ومدى توفّرها في الوقت الفعلي وطرق الدفع المتوافقة ونقاط الاهتمام المضيفة. على سبيل المثال، اتجاهات القيادة داخل مواقف السيارات الخارجية للجزء الأخير من التنقل، وساعات العمل، والتقييمات. لضمان تطابق محطات الشحن بشكل جيد مع بيانات Google، استخدِم <brand name> محددًا، على سبيل المثال، ChargePoint.

المعلَمات

تتيح لك المَعلمات التالية تحديد تفاصيل الوجهة النهائية وأي نقاط على المسار، بما في ذلك تلك المحدّدة كمحطات شحن للمركبات الكهربائية.

الوجهة النهائية

لضبط محطة شحن كوجهة نهائية، استخدِم:

• ‫q: يجب أن تحتوي على قيمة خط العرض وخط الطول لمحطة الشحن.
• ‫q_type: تشير السمة 1 إلى أنّ الوجهة النهائية هي محطة شحن.
• ‫q_name: اسم الوجهة النهائية مطلوب إذا كانت قيمة q_type هي 1.
• ‫q_power_output_kw: رقم مزدوج لإخراج الطاقة في محطة الشحن بالكيلوواط اختيارية:

نقاط على المسار

بالنسبة إلى النقاط على المسار، تكون جميع المَعلمات مصفوفات متوازية مفصولة بخط عمودي (|) للقيم بالترتيب نفسه للنقاط على المسار، باستثناء الوجهة النهائية. يتم التعامل مع عدم التطابق في عدد العناصر في الصفائف المتوازية على أنه طلب مشوّه.

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

• ‫waypoints: قائمة النقاط على المسار كما هو موضّح في نية الاتجاهات المفصّلة يجب أن تكون قيمة خط العرض وخط الطول للنقاط على المسار الخاصة بمحطات الشحن.

• ‫waypoint_types: أنواع النقاط على المسار المحدّدة كرقم. 0 هي أي محطة توقّف (القيمة التلقائية) و1 هي محطة الشحن.

• ‫waypoint_names: أسماء النقاط على المسار هذا الحقل إلزامي لمحطات الشحن.

• ‫waypoint_power_outputs_kw: أرقام مزدوجة لطاقة محطة الشحن بالكيلوواط بالنسبة إلى محطات الشحن، يمكنك تحديد قيمة ناتج الطاقة لنقطة على المسار، والتي يتم استخدامها كقيمة احتياطية في حال عدم العثور على المحطة المطابقة. تعني الخانة الفارغة عدم تقديم أي قيمة.

سلوك تجربة المستخدم (UX)

بالنسبة إلى طلبات الرحلات التي تتضمّن وجهات متعددة، تظهر شاشة نظرة عامة على المسار، ولكن لا يبدأ التنقّل تلقائيًا.

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

بالنسبة إلى أي نقاط على المسار أو وجهات نهائية تم وضع علامة عليها كمحطة شحن، ستبحث "خرائط Google" عن مكان مطابق في قاعدة بيانات Google. لضمان عرض أفضل معلومات ممكنة عن محطات الشحن:

• إذا تم العثور على تطابق، تستخدم "خرائط Google" بيانات المستخدم على Google لعرض محطة الشحن في واجهة المستخدم وتقديم اقتراح بشأن محطة الشحن.

• إذا لم يتم العثور على تطابق، يتم استخدام البيانات المقدَّمة في الطلب لمحطة شحن (خط العرض وخط الطول والاسم والقدرة الكهربائية) لعرض محطة الشحن هذه في واجهة المستخدم وتقديم اقتراح شحن في محطة الشحن هذه.

أمثلة

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

الانتقال إلى وجهة نهائية عبر محطات شحن متعددة

ينتقل الطلب التالي إلى الوجهة النهائية، وهي بورت ماكواري في نيو ساوث ويلز، عبر محطتَي شحن، هما ChargePoint وEvie.

الوجهات بالترتيب:

1. محطة شحن ChargePoint (الموقع الجغرافي: ‎-32.9599188,151.6240806، الطاقة الناتجة: 6.6 كيلوواط)

2. محطة شحن Evie (الموقع الجغرافي: ‎-31.9432539,152.4699808، الطاقة الناتجة: 350 كيلوواط)

3. بورت ماكواري، نيو ساوث ويلز

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

الطاقة الناتجة غير معروفة

إذا كانت قيمة الطاقة الناتجة غير معروفة، اترك الخانة ذات الصلة في waypoint_power_outputs_kw فارغة. أو إذا كانت جميع الخانات فارغة، لن تحتاج إلى تحديد المَعلمة waypoint_power_outputs_kw.

الوجهات بالترتيب:

1. محطة شحن ChargePoint (الموقع الجغرافي: ‎-32.9599188,151.6240806، الطاقة الناتجة: غير معروفة)

2. بورت ماكواري، نيو ساوث ويلز

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

وضع علامة على الوجهة النهائية كمحطة شحن

لتحديد الوجهة النهائية كمحطة شحن، حدِّد المَعلمات q_type وq_name وq_power_output_kw.

الوجهات بالترتيب:

1. حديقة حيوان تارونغا، سيدني، أستراليا

2. محطة شحن ChargePoint (الموقع الجغرافي: ‎-32.9599188,151.6240806، ناتج الطاقة: غير معروف)

3. محطة شحن Evie (الموقع الجغرافي: ‎-31.9432539,152.4699808، ناتج الطاقة: 350 كيلوواط)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

أهداف الإجراءات

تتوفّر الأهداف التالية للإجراءات التي تتضمّن واجهات: