حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

خدمة الاتجاهات

المطوّرون في المنطقة الاقتصادية الأوروبية

ملاحظة: مكتبات من جهة الخادم

نظرة عامة

يمكنك حساب الاتجاهات (باستخدام مجموعة متنوعة من وسائل النقل) باستخدام العنصر DirectionsService. يتواصل هذا العنصر مع خدمة الاتجاهات في Google Maps API التي تتلقّى طلبات الاتجاهات وتعرض مسارًا فعالاً. مدة التنقّل هي العامل الأساسي الذي يتم تحسينه، ولكن قد يتم أخذ عوامل أخرى في الاعتبار، مثل المسافة وعدد المنعطفات وغيرها. يمكنك التعامل مع نتائج الاتجاهات هذه بنفسك أو استخدام العنصر DirectionsRenderer لعرض هذه النتائج.

عند تحديد نقطة الانطلاق أو الوجهة في طلب الحصول على اتجاهات، يمكنك تحديد سلسلة طلب بحث (مثل "شيكاغو، إلينوي" أو "داروين، نيو ساوث ويلز، أستراليا")، أو قيمة LatLng، أو عنصر مكان.

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

الخطوات الأولى

قبل استخدام خدمة Directions في Maps JavaScript API، تأكَّد أولاً من تفعيل Directions API (الإصدار القديم) في Google Cloud Console، وذلك في المشروع نفسه الذي أعددته لـ Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة، اتّبِع الخطوات التالية:

انتقِل إلى وحدة تحكّم Google Cloud.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات JavaScript الخاصة بخرائط Google وانقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Directions API (الإصدار القديم).
إذا ظهرت واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، فعِّلها على https://console.cloud.google.com/apis/library/directions-backend.googleapis.com

الأسعار والسياسات

الأسعار

للتعرّف على سياسات الأسعار والاستخدام لخدمة JavaScript Directions، راجِع مقالة الاستخدام والفوترة في Directions API (الإصدار القديم).

السياسات

يجب أن يكون استخدام خدمة "الاتجاهات" متوافقًا مع السياسات الموضّحة لواجهة برمجة التطبيقات Directions API (الإصدار القديم).

طلبات الحصول على الاتجاهات

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

لاستخدام الاتجاهات في Maps JavaScript API، أنشئ عنصرًا من النوع DirectionsService واستدعِ DirectionsService.route() لبدء طلب إلى خدمة الاتجاهات، مع تمرير حرفي DirectionsRequest يحتوي على عبارات الإدخال وطريقة ردّ يتم تنفيذها عند تلقّي الردّ.

يحتوي العنصر الحرفي DirectionsRequest على الحقول التالية:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

في ما يلي شرح لهذه الحقول:

تحدّد السمة origin (مطلوبة) الموقع الجغرافي الذي سيتم منه حساب الاتجاهات. يمكن تحديد هذه القيمة كـ String (مثلاً، "شيكاغو، إلينوي") أو كقيمة LatLng أو كعنصر Place. في حال استخدام عنصر Place، يمكنك تحديد معرّف مكان أو سلسلة طلب بحث أو موقع جغرافي LatLng. يمكنك استرداد أرقام تعريف الأماكن من خدمات ترميز المواقع الجغرافية والبحث عن الأماكن والإكمال التلقائي للأماكن في Maps JavaScript API. للاطّلاع على مثال يستخدم معرّفات الأماكن من خدمة Place Autocomplete، راجِع الإكمال التلقائي للأماكن والاتجاهات.
تحدّد السمة destination (مطلوبة) الموقع الجغرافي النهائي الذي سيتم حساب الاتجاهات إليه. الخيارات هي نفسها الخيارات الخاصة بالحقل origin الموضّح أعلاه.
تحدّد السمة travelMode (مطلوبة) وسيلة النقل التي سيتم استخدامها عند احتساب الاتجاهات. يتم تحديد القيم الصالحة في وسائل النقل أدناه.
تحدّد السمة transitOptions (اختيارية) قيمًا تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي TRANSIT. يتم توضيح القيم الصالحة في خيارات النقل أدناه.
تحدّد السمة drivingOptions (اختيارية) قيمًا تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي DRIVING. تم توضيح القيم الصالحة في القسم خيارات القيادة أدناه.
تحدّد السمة unitSystem (اختيارية) نظام الوحدات الذي سيتم استخدامه عند عرض النتائج. القيم الصالحة هي تلك المحدّدة في أنظمة الوحدات أدناه.
تحدّد السمة waypoints[] (اختيارية) مصفوفة من عناصر DirectionsWaypoint. تعدّل نقاط الطريق مسارًا من خلال توجيهه عبر المواقع الجغرافية المحدّدة. يتم تحديد نقطة الطريق كعنصر حرفي مع الحقول الموضّحة أدناه:
- تحدّد location الموقع الجغرافي لنقطة الطريق، إما كـ LatLng أو ككائن Place أو كـ String سيتم تحويله إلى رمز جغرافي.
- ‫stopover هو قيمة منطقية تشير إلى أنّ نقطة الطريق هي محطة توقّف على المسار، ما يؤدي إلى تقسيم المسار إلى مسارين.
(لمزيد من المعلومات حول نقاط الطريق، يُرجى الاطّلاع على القسم استخدام نقاط الطريق في المسارات أدناه).
تحدّد السمة optimizeWaypoints (اختيارية) أنّه يمكن تحسين المسار باستخدام waypoints المقدَّمة من خلال إعادة ترتيب نقاط الطريق بترتيب أكثر فعالية. إذا كانت true، ستعرض خدمة "الاتجاهات" waypoints المعاد ترتيبها في الحقل waypoint_order.(لمزيد من المعلومات، يُرجى الاطّلاع على استخدام نقاط المرور في المسارات أدناه).
provideRouteAlternatives (اختياري) عند ضبطه على true، يشير إلى أنّ خدمة "الاتجاهات" قد تقدّم أكثر من مسار بديل واحد في الردّ. يُرجى العِلم أنّ توفير بدائل للطرق قد يؤدي إلى زيادة وقت استجابة الخادم. تتوفّر هذه الميزة فقط للطلبات التي لا تتضمّن نقاط توقّف وسيطة.
avoidFerries (اختياري) عند ضبطه على true، يشير إلى أنّه يجب أن تتجنّب المسارات المحسوبة العبّارات، إذا أمكن ذلك.
avoidHighways (اختياري) عند ضبطه على true، يشير إلى أنّه يجب تجنُّب الطرق السريعة الرئيسية في المسارات المحسوبة، إذا أمكن ذلك.
avoidTolls (اختيارية) عند ضبطها على true، يشير ذلك إلى أنّه يجب أن تتجنّب المسارات المحسوبة الطرق ذات رسوم العبور، إذا أمكن ذلك.
تمثّل السمة region (اختيارية) رمز المنطقة، ويتم تحديدها كقيمة من حرفين تمثّل نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد. (لمزيد من المعلومات، يُرجى الاطّلاع على قسم تفضيل منطقة معيّنة أدناه).

ملاحظة: تم الآن إيقاف الحقل durationInTraffic نهائيًا. كانت هذه السمة سابقًا الطريقة المقترَحة لعملاء "خطة Premium" في "منصة خرائط Google" لتحديد ما إذا كان يجب أن تتضمّن النتيجة مدة زمنية تأخذ في الاعتبار أحوال حركة المرور الحالية. يجب الآن استخدام الحقل drivingOptions بدلاً من ذلك.

في ما يلي نموذج DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

وسائل النقل

عند احتساب الاتجاهات، عليك تحديد وسيلة النقل التي تريد استخدامها. تتوفّر حاليًا وسائط النقل التالية:

DRIVING (القيمة التلقائية) تشير إلى اتجاهات القيادة العادية باستخدام شبكة الطرق.
BICYCLING يطلب اتجاهات خاصة بالدراجات عبر المسارات المخصّصة للدراجات والشوارع المفضّلة.
TRANSIT يطلب الحصول على الاتجاهات عبر مسارات وسائل النقل العام.
WALKING طلبات الحصول على اتجاهات المشي عبر مسارات المشاة والأرصفة

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

ملاحظة: قد لا تتضمّن اتجاهات المشي مسارات واضحة للمشاة، لذا ستعرض تحذيرات في DirectionsResult. ويجب عرض هذه التحذيرات للمستخدم دائمًا. في حال عدم استخدام DirectionsRenderer التلقائي، تكون أنت المسؤول عن ضمان عرض التحذيرات.

خيارات النقل العام

تختلف الخيارات المتاحة لطلب الاتجاهات بين وسائل النقل. عند طلب اتجاهات النقل العام، سيتم تجاهل الخيارات avoidHighways وavoidTolls وwaypoints[] وoptimizeWaypoints. يمكنك تحديد خيارات توجيه خاصة بالنقل العام من خلال عنصر TransitOptions الحرفي.

تعتمد اتجاهات النقل العام على الوقت. سيتم عرض الاتجاهات للأوقات المستقبلية فقط.

يحتوي حرف الكائن TransitOptions على الحقول التالية:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

في ما يلي شرح لهذه الحقول:

تحدّد السمة arrivalTime (اختيارية) وقت الوصول المطلوب كعنصر Date. إذا تم تحديد وقت الوصول، سيتم تجاهل وقت المغادرة.
تحدّد السمة departureTime (اختيارية) وقت المغادرة المطلوب كعنصر Date. سيتم تجاهل departureTime في حال تحديد arrivalTime. يتم ضبط القيمة التلقائية على الوقت الحالي في حال عدم تحديد قيمة لكل من departureTime أو arrivalTime.
‫modes[] (اختياري) هي مصفوفة تحتوي على قيمة حرفية واحدة أو أكثر من قيم TransitMode. لا يمكن تضمين هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح واجهة برمجة تطبيقات. يحدّد كل TransitMode وسيلة نقل عام مفضّلة. يُسمح بالقيم التالية:
- يشير BUS إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالحافلة.
- يشير RAIL إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار والترام والقطار الخفيف ومترو الأنفاق.
- يشير SUBWAY إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بواسطة مترو الأنفاق.
- يشير TRAIN إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار.
- يشير TRAM إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالترام والقطار الخفيف.
تحدّد السمة routingPreference (اختيارية) الإعدادات المفضّلة لمسارات النقل العام. باستخدام هذا الخيار، يمكنك تحديد الخيارات التي يتم عرضها بدلاً من قبول أفضل مسار تلقائي تختاره واجهة برمجة التطبيقات. لا يمكن تحديد هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح API. يُسمح بالقيم التالية:
- يشير FEWER_TRANSFERS إلى أنّ المسار المحسوب يجب أن يفضّل عددًا محدودًا من عمليات تغيير وسائل النقل.
- تشير LESS_WALKING إلى أنّ المسار المحسوب يجب أن يفضّل السير لمسافات قصيرة.

في ما يلي نموذج DirectionsRequest حسب وسيلة النقل العام:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

خيارات القيادة

يمكنك تحديد خيارات التوجيه لتعليمات القيادة من خلال العنصر DrivingOptions.

يحتوي عنصر DrivingOptions على الحقول التالية:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

في ما يلي شرح لهذه الحقول:

تحدّد السمة departureTime (مطلوبة لكي يكون الكائن الحرفي drivingOptions صالحًا) وقت المغادرة المطلوب ككائن Date. يجب ضبط القيمة على الوقت الحالي أو وقت في المستقبل. لا يمكن أن يكون تاريخًا سابقًا. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المنسّق لضمان معالجتها بشكل متّسق في جميع المناطق الزمنية). بالنسبة إلى عملاء "خطة Premium" في Google Maps Platform، إذا تضمّن الطلب departureTime، ستعرض واجهة برمجة التطبيقات أفضل مسار وفقًا لحالات حركة المرور المتوقّعة في الوقت الحالي، وستتضمّن الوقت المتوقّع في حركة المرور (duration_in_traffic) في الردّ. في حال عدم تحديد وقت المغادرة (أي إذا لم يتضمّن الطلب drivingOptions)، سيكون المسار الذي يتم عرضه مسارًا جيدًا بشكل عام بدون أخذ حالة حركة المرور في الاعتبار.
تحدّد السمة trafficModel (اختيارية) الافتراضات التي يجب استخدامها عند احتساب الوقت المستغرَق في حركة المرور. يؤثر هذا الإعداد في القيمة المعروضة في الحقل duration_in_traffic ضمن الاستجابة، والذي يتضمّن الوقت المتوقّع في حركة المرور استنادًا إلى المتوسطات السابقة. القيمة التلقائية هي bestguess. يُسمح بالقيم التالية:
- تشير القيمة bestguess (القيمة التلقائية) إلى أنّ duration_in_traffic المعروضة يجب أن تكون أفضل تقدير لوقت السفر استنادًا إلى المعلومات المتوفّرة عن كلّ من حالات حركة المرور السابقة وحركة المرور المباشرة. تزداد أهمية بيانات حركة المرور المباشرة كلما اقترب وقت departureTime من الوقت الحالي.
- تشير pessimistic إلى أنّ duration_in_traffic يجب أن تكون أطول من وقت السفر الفعلي في معظم الأيام، على الرغم من أنّ بعض الأيام التي تشهد ازدحامًا مروريًا سيئًا بشكل خاص قد تتجاوز هذه القيمة.
- تشير optimistic إلى أنّ مدة السفر التي يتم عرضها duration_in_traffic يجب أن تكون أقصر من مدة السفر الفعلية في معظم الأيام، مع العلم أنّ بعض الأيام التي تكون فيها حركة المرور جيدة قد تكون أسرع من هذه القيمة.

ملاحظة: للتأكّد من أنّ طلبك يستخدم معلومات حركة المرور الحالية، اضبط قيمة departureTime على "الآن". تتم محاسبة الطلبات التي تستخدم معلومات حركة المرور بسعر أعلى. مزيد من المعلومات عن كيفية إصدار فواتير منتجات "منصة خرائط Google"

في ما يلي نموذج DirectionsRequest لتعليمات القيادة:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

أنظمة الوحدات

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

تحدّد السمة UnitSystem.METRIC ما إذا كان سيتم استخدام النظام المتري. يتم عرض المسافات بالكيلومترات.
تحدّد السمة UnitSystem.IMPERIAL استخدام نظام القياس الإمبراطوري (الإنجليزية). يتم عرض المسافات باستخدام الأميال.

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

تحديد المنطقة المفضّلة للاتجاهات

تعرض خدمة Directions API من "خرائط Google" نتائج عناوين تتأثر بالنطاق (المنطقة أو البلد) الذي تم تحميل برنامج JavaScript الأساسي منه. (بما أنّ معظم المستخدمين يحمّلون https://maps.googleapis.com/، يؤدي ذلك إلى ضبط نطاق ضمني على الولايات المتحدة). إذا حمّلت برنامج الإعداد من نطاق معتمَد آخر، ستحصل على نتائج متأثرة بهذا النطاق. على سبيل المثال، قد يؤدي البحث عن "القاهرة" إلى عرض نتائج مختلفة عن التطبيقات التي يتم تحميلها في https://maps.googleapis.com/ (مصر) مقارنةً بالتطبيقات التي يتم تحميلها في http://maps.google.es/ (المملكة العربية السعودية).

يمكنك أيضًا ضبط خدمة "الاتجاهات" لعرض نتائج متحيزة لمنطقة معيّنة باستخدام المَعلمة region. تتلقّى هذه المَعلمة رمز منطقة، ويتم تحديده كعلامة فرعية لمنطقة Unicode مكوّنة من حرفَين (غير رقميَين). في معظم الحالات، يتم ربط هذه العلامات مباشرةً بقيم ccTLD المكوّنة من حرفين (مثل "نطاق المستوى الأعلى")، مثل "uk" في "co.uk" مثلاً. في بعض الحالات، تتيح العلامة region أيضًا رموز ISO-3166-1 التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى لرموز البلدان (مثل "GB" لـ "بريطانيا العظمى").

عند استخدام المَعلمة region:

حدِّد بلدًا أو منطقة واحدة فقط. يتم تجاهل القيم المتعددة، وقد يؤدي ذلك إلى تعذُّر تنفيذ الطلب.
استخدِم علامات فرعية للمناطق تتألف من حرفين فقط (تنسيق Unicode CLDR). ستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.

لا تتوفّر ميزة "تفضيل منطقة معيّنة" إلا في البلدان والمناطق التي تتوفّر فيها ميزة الاتجاهات. راجِع تفاصيل تغطية "منصة خرائط Google" للاطّلاع على التغطية الدولية لواجهة Directions API (الإصدار القديم).

عرض الاتجاهات

يتطلّب بدء طلب اتجاهات إلى DirectionsService باستخدام طريقة route() تمرير دالة ردّ يتم تنفيذها عند اكتمال طلب الخدمة. ستعرض دالة معاودة الاتصال هذه الرمزين DirectionsResult وDirectionsStatus في الردّ.

حالة طلب البحث عن الاتجاهات

قد تعرض DirectionsStatus القيم التالية:

يشير OK إلى أنّ الردّ يتضمّن DirectionsResult صالحًا.
تشير NOT_FOUND إلى أنّه تعذّر ترميز موقع جغرافي واحد على الأقل من المواقع الجغرافية المحدّدة في مصدر الطلب أو وجهته أو نقاط وسطه.
يشير الرمز ZERO_RESULTS إلى أنّه لم يتم العثور على أي مسار بين نقطة الانطلاق والوجهة.
يشير MAX_WAYPOINTS_EXCEEDED إلى أنّه تم تقديم عدد كبير جدًا من حقول DirectionsWaypoint في DirectionsRequest. يُرجى الاطّلاع على القسم أدناه حول حدود نقاط الطريق.
يشير الرمز MAX_ROUTE_LENGTH_EXCEEDED إلى أنّ المسار المطلوب طويل جدًا ولا يمكن معالجته. يحدث هذا الخطأ عند عرض توجيهات أكثر تعقيدًا. حاوِل تقليل عدد نقاط المرور أو المنعطفات أو التعليمات.
يشير الرمز INVALID_REQUEST إلى أنّ DirectionsRequest المقدَّم غير صالح. تتضمّن الأسباب الأكثر شيوعًا لظهور رمز الخطأ هذا الطلبات التي لا تتضمّن مصدرًا أو وجهة، أو طلبات النقل التي تتضمّن نقاط توقّف.
يشير الرمز OVER_QUERY_LIMIT إلى أنّ صفحة الويب أرسلت عددًا كبيرًا جدًا من الطلبات خلال الفترة الزمنية المسموح بها.
يشير REQUEST_DENIED إلى أنّه غير مسموح لصفحة الويب باستخدام خدمة الاتجاهات.
يشير الرمز UNKNOWN_ERROR إلى تعذُّر معالجة طلب الاتجاهات بسبب حدوث خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.

يجب التأكّد من أنّ طلب البحث عن الاتجاهات قد عرض نتائج صالحة من خلال التحقّق من هذه القيمة قبل معالجة النتيجة.

عرض DirectionsResult

يحتوي DirectionsResult على نتيجة طلب البحث عن الاتجاهات، ويمكنك إما معالجة النتيجة بنفسك أو تمريرها إلى عنصر DirectionsRenderer، الذي يمكنه معالجة عرض النتيجة على خريطة تلقائيًا.

لعرض DirectionsResult باستخدام DirectionsRenderer، عليك تنفيذ ما يلي:

أنشئ عنصر DirectionsRenderer.
استدعِ الدالة setMap() في أداة العرض لربطها بالخريطة التي تم تمريرها.
استدعِ الدالة setDirections() في أداة العرض، مع تمرير DirectionsResult كما هو موضّح أعلاه. بما أنّ أداة العرض هي MVCObject، ستتعرّف تلقائيًا على أي تغييرات في خصائصها وتعدّل الخريطة عند تغيير الاتجاهات المرتبطة بها.

يحسب المثال التالي الاتجاهات بين موقعَين جغرافيَّين على الطريق السريع 66، حيث يتم ضبط نقطة البداية ونقطة النهاية من خلال القيمتَين "start" و"end" المحدّدتَين في القوائم المنسدلة. يتولّى DirectionsRenderer عرض الخط المتعدد الأضلاع بين المواقع الجغرافية المحدّدة وتحديد مواضع العلامات في نقطة البداية والوجهة وأي نقاط طريق، إذا كان ذلك منطبقًا.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

في نص HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

عرض مثال

يوضّح المثال التالي الاتجاهات باستخدام وسائل نقل مختلفة بين Haight-Ashbury وOcean Beach في سان فرانسيسكو، كاليفورنيا:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

في نص HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

عرض مثال

لا يعالج العنصر DirectionsRenderer عرض الخط المتعدد الأضلاع وأي علامات مرتبطة به فحسب، بل يمكنه أيضًا معالجة العرض النصي للاتجاهات كسلسلة من الخطوات. لإجراء ذلك، اتّصِل بالدالة setPanel() على DirectionsRenderer، مع تمرير <div> الذي سيتم عرض هذه المعلومات فيه. ويضمن ذلك أيضًا عرض معلومات حقوق الطبع والنشر المناسبة وأي تحذيرات قد تكون مرتبطة بالنتيجة.

سيتم تقديم الاتجاهات النصية باستخدام إعداد اللغة المفضّلة في المتصفّح، أو اللغة المحدّدة عند تحميل JavaScript الخاص بواجهة برمجة التطبيقات باستخدام المَعلمة language. (لمزيد من المعلومات، يُرجى الاطّلاع على الأقلمة). في ما يتعلّق بتوجيهات النقل العام، سيتم عرض الوقت حسب المنطقة الزمنية التي تقع فيها محطة النقل العام.

المثال التالي مطابق للمثال الموضّح أعلاه، ولكنّه يتضمّن لوحة <div> يتم فيها عرض الاتجاهات:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

في نص HTML:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

عرض مثال

كائن DirectionsResult

عند إرسال طلب للحصول على اتجاهات إلى DirectionsService، تتلقّى ردًا يتألف من رمز حالة ونتيجة، وهي عبارة عن عنصر DirectionsResult. ‫DirectionsResult هو كائن حرفي يتضمّن الحقول التالية:

يحتوي geocoded_waypoints[] على مصفوفة من عناصر DirectionsGeocodedWaypoint، يحتوي كل عنصر منها على تفاصيل حول الترميز الجغرافي للمصدر والوجهة ونقاط التوقف.
يحتوي routes[] على مصفوفة من عناصر DirectionsRoute. يشير كل مسار إلى طريقة للانتقال من نقطة الانطلاق إلى الوجهة المحدّدة في DirectionsRequest. بشكل عام، يتم عرض مسار واحد فقط لأي طلب، ما لم يتم ضبط الحقل provideRouteAlternatives في الطلب على true، وفي هذه الحالة، قد يتم عرض مسارات متعددة.

ملاحظة: تم إيقاف السمة via_waypoint نهائيًا في المسارات البديلة. الإصدار 3.27 هو آخر إصدار من واجهة برمجة التطبيقات يضيف نقاط طريق إضافية في الطرق البديلة. في الإصدارات 3.28 والإصدارات الأحدث من واجهة برمجة التطبيقات، يمكنك مواصلة تنفيذ الاتجاهات القابلة للسحب باستخدام خدمة Directions من خلال إيقاف إمكانية سحب المسارات البديلة. يجب أن يكون المسار الرئيسي فقط قابلاً للسحب. يمكن للمستخدمين سحب المسار الرئيسي إلى أن يتطابق مع مسار بديل.

نقاط الطريق المرمّزة جغرافيًا للاتجاهات

يحتوي DirectionsGeocodedWaypoint على تفاصيل حول الترميز الجغرافي للمصدر والوجهة ونقاط المرور.

‫DirectionsGeocodedWaypoint هو عنصر حرفي يتضمّن الحقول التالية:

يشير geocoder_status إلى رمز الحالة الناتج من عملية الترميز الجغرافي. قد يحتوي هذا الحقل على القيم التالية.
- تشير "OK" إلى عدم حدوث أي أخطاء، وإلى أنّه تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل.
- يشير الرمز "ZERO_RESULTS" إلى أنّه تمّت عملية الترميز الجغرافي بنجاح ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير address غير موجود إلى أداة الترميز الجغرافي.
يشير الرمز partial_match إلى أنّ أداة الترميز الجغرافي لم تعرض تطابقًا تامًا مع الطلب الأصلي، ولكنّها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بمراجعة الطلب الأصلي للتأكّد من عدم وجود أخطاء إملائية و/أو عنوان غير مكتمل.

تحدث التطابقات الجزئية في أغلب الأحيان لعناوين الشوارع غير المتوفّرة في المنطقة المحلية التي يتم إرسالها في الطلب. قد يتم أيضًا عرض نتائج مطابقة جزئية عندما يتطابق طلب البحث مع موقعَين جغرافيَين أو أكثر في المنطقة نفسها. على سبيل المثال، سيؤدي البحث عن "شارع هيلبار، بريستول، المملكة المتحدة" إلى عرض تطابق جزئي لكل من شارع هنري وشارع هنريتا. يُرجى العِلم أنّه إذا تضمّن الطلب جزءًا من العنوان مكتوبًا بشكل خاطئ، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تصنيف الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها تطابق جزئي.
place_idهو معرّف فريد لمكان معيّن، ويمكن استخدامه مع واجهات برمجة تطبيقات أخرى من Google. على سبيل المثال، يمكنك استخدام place_id مع مكتبة Google Places API للحصول على تفاصيل حول نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة على معرّف المكان.
‫types[] هي مصفوفة تشير إلى نوع النتيجة التي تم إرجاعها. تحتوي هذه المصفوفة على مجموعة من صفر أو أكثر من العلامات التي تحدد نوع الميزة التي تم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي الخاص بـ "القاهرة" "locality"، ما يشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا "political"، ما يشير إلى أنّها كيان سياسي.

مسارات الاتجاهات

ملاحظة: تمت إعادة تسمية العنصر القديم DirectionsTrip إلى DirectionsRoute. يُرجى العِلم أنّ المسار يشير الآن إلى الرحلة الكاملة من البداية إلى النهاية، وليس إلى جزء من رحلة رئيسية.

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

‫DirectionsRoute هو كائن حرفي يتضمّن الحقول التالية:

يحتوي legs[] على مصفوفة من عناصر DirectionsLeg، يحتوي كل منها على معلومات حول جزء من المسار، من موقعَين جغرافيَين ضمن المسار المحدّد. سيتم عرض جزء منفصل لكل نقطة توقّف أو وجهة محددة. (سيتضمّن المسار الذي لا يحتوي على نقاط طريق DirectionsLeg واحدًا بالضبط). يتألف كل جزء من سلسلة من DirectionStep.
تحتوي waypoint_order على مصفوفة تشير إلى ترتيب أي نقاط طريق في المسار المحسوب. قد تحتوي هذه المصفوفة على ترتيب معدَّل إذا تم تمرير DirectionsRequest optimizeWaypoints: true.
تحتوي السمة overview_path على مصفوفة من عناصر LatLng التي تمثّل مسارًا تقريبيًا (معدَّلاً) للاتجاهات الناتجة.
يحتوي overview_polyline على عنصر points واحد يتضمّن تمثيلاً لخط متعدد الأضلاع مرمّز للمسار. هذا الخط المتعدد هو مسار تقريبي (تم تنعيمه) للاتجاهات الناتجة.
تحتوي bounds على LatLngBounds تشير إلى حدود الخط المتعدد الأضلاع على طول هذا المسار المحدّد.
يحتوي copyrights على نص حقوق الطبع والنشر الذي سيتم عرضه لهذه الطريق.
ملاحظة: إذا لم تستخدِم عنصر DirectionsRenderer المقدَّم، عليك معالجة هذه المعلومات وعرضها بنفسك.
تحتوي warnings[] على مصفوفة من التحذيرات التي سيتم عرضها عند إظهار هذه الاتجاهات. في حال عدم استخدام عنصر DirectionsRenderer المقدَّم، عليك التعامل مع هذه التحذيرات وعرضها بنفسك.
يحتوي fare على إجمالي الأجرة (أي إجمالي تكاليف التذكرة) على هذا المسار. لا يتم عرض هذه السمة إلا لطلبات النقل العام، وفقط للمسارات التي تتوفّر فيها معلومات الأسعار لجميع مراحل النقل العام. تشمل المعلومات ما يلي:
- currency: رمز عملة بتنسيق ISO 4217 يشير إلى العملة التي يتم التعبير عن المبلغ بها.
- ‫value: يمثّل هذا الحقل إجمالي مبلغ الأجرة بالعملة المحدّدة أعلاه.

Directions Legs

ملاحظة: تمت إعادة تسمية العنصر القديم DirectionsRoute إلى DirectionsLeg.

يمثّل DirectionsLeg جزءًا واحدًا من رحلة من نقطة الانطلاق إلى الوجهة في المسار المحسوب. بالنسبة إلى المسارات التي لا تحتوي على نقاط توقّف، سيتألف المسار من "مرحلة" واحدة، ولكن بالنسبة إلى المسارات التي تحدّد نقطة توقّف واحدة أو أكثر، سيتألف المسار من مرحلة واحدة أو أكثر، بما يتوافق مع المراحل المحدّدة للرحلة.

‫DirectionsLeg هو كائن حرفي يتضمّن الحقول التالية:

يحتوي steps[] على مصفوفة من عناصر DirectionsStep تشير إلى معلومات حول كل خطوة منفصلة من رحلة السفر.
يشير distance إلى إجمالي المسافة المقطوعة في هذا الجزء من الرحلة، وذلك كعنصر Distance بالشكل التالي:
- تشير value إلى المسافة بالأمتار
- يحتوي text على تمثيل سلسلة للمسافة، ويتم عرضها تلقائيًا بالوحدات المستخدمة في المصدر. (على سبيل المثال، سيتم استخدام الأميال لأي وجهة انطلاق داخل الولايات المتحدة). يمكنك إلغاء نظام الوحدات هذا من خلال تحديد UnitSystem في طلب البحث الأصلي. يُرجى العِلم أنّه بغض النظر عن نظام الوحدات الذي تستخدمه، يحتوي الحقل distance.value دائمًا على قيمة معبَّر عنها بالمتر.
قد تكون هذه الحقول غير محدّدة إذا كانت المسافة غير معروفة.
يشير duration إلى المدة الإجمالية لهذا الجزء من الرحلة، وذلك كعنصر Duration بالشكل التالي:
- تشير value إلى المدة بالثواني.
- يحتوي text على تمثيل سلسلة لمدة العرض.
قد تكون هذه الحقول غير محدّدة إذا كانت المدة غير معروفة.
تشير duration_in_traffic إلى المدة الإجمالية لهذه المرحلة، مع الأخذ في الاعتبار أحوال حركة المرور الحالية. يتم عرض duration_in_traffic فقط إذا كانت جميع الشروط التالية صحيحة:
- لا يتضمّن الطلب نقاط توقّف مؤقت. أي أنّه لا يشمل نقاط المرور التي تكون فيها قيمة stopover هي true.
- الطلب مخصّص للحصول على اتجاهات القيادة، أي أنّ قيمة mode هي driving.
- يتم تضمين departureTime كجزء من الحقل drivingOptions في الطلب.
- تتوفّر معلومات عن حركة المرور للمسار المطلوب.
يتضمّن duration_in_traffic الحقول التالية:
- تشير value إلى المدة بالثواني.
- يحتوي text على تمثيل يمكن لشخص عادي قراءته للمدة.
تحتوي السمة arrival_time على الوقت المقدَّر للوصول لهذه الرحلة. لا يتم عرض هذه السمة إلا لتعليمات النقل العام. يتم عرض النتيجة كعنصر Time يتضمّن ثلاث سمات:
- value الوقت المحدّد ككائن JavaScript Date
- text الوقت المحدّد كسلسلة يُعرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.
- يحتوي time_zone على المنطقة الزمنية لهذه المحطة. القيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية التابعة لهيئة IANA، مثل "America/New_York".
يتضمّن departure_time الوقت المقدَّر للمغادرة في هذه الرحلة، ويتم تحديده كعنصر Time. لا تتوفّر departure_time إلا لاتجاهات النقل العام.
تحتوي السمة start_location على LatLng مصدر هذا الجزء من الرحلة. بما أنّ خدمة الويب الخاصة بـ "الاتجاهات" تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب وسيلة نقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد تكون قيمة start_location مختلفة عن نقطة الأصل المقدَّمة لهذه الرحلة، مثلاً إذا لم يكن هناك طريق بالقرب من نقطة الأصل.
تحتوي السمة end_location على LatLng الخاصة بوجهة هذه المرحلة. بما أنّ DirectionsService يحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب وسيلة نقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد يختلف end_location عن الوجهة المقدَّمة لهذه المرحلة، مثلاً إذا لم يكن هناك طريق بالقرب من الوجهة.
تحتوي السمة start_address على العنوان الذي يمكن لشخص عادي قراءته (عادةً عنوان شارع) لبداية هذا الجزء من الرحلة.

يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليله آليًا.
تحتوي السمة end_address على العنوان الذي يمكن قراءته (عادةً عنوان شارع) لنهاية هذا الجزء من الرحلة.

يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليله آليًا.

خطوات الاتجاهات

DirectionsStep هي أصغر وحدة في مسار الاتجاهات، وهي تتضمّن خطوة واحدة تصف تعليمات معيّنة واحدة بشأن الرحلة. على سبيل المثال، "اتّجه يسارًا عند شارع W". 4th St." لا تصف الخطوة التعليمات فحسب، بل تحتوي أيضًا على معلومات حول المسافة والمدة المتعلّقة بكيفية ارتباط هذه الخطوة بالخطوة التالية. على سبيل المثال، قد تتضمّن خطوة مثل "الانتقال إلى الطريق السريع I-80 غربًا" مدة "37 ميلاً" و "40 دقيقة"، ما يشير إلى أنّ الخطوة التالية تبعد 37 ميلاً أو 40 دقيقة عن هذه الخطوة.

عند استخدام خدمة "الاتجاهات" للبحث عن اتجاهات النقل العام، ستتضمّن مصفوفة الخطوات معلومات إضافية خاصة بالنقل العام في شكل كائن transit. إذا كانت الاتجاهات تتضمّن وسائل نقل متعدّدة، سيتم تقديم اتجاهات مفصّلة لخطوات المشي أو القيادة في مصفوفة steps[]. على سبيل المثال، ستتضمّن خطوة المشي اتجاهات من الموقع الجغرافي لبداية الرحلة ونهايتها: "المشي إلى شارع إينز وشارع فيتش". ستتضمّن هذه الخطوة تعليمات مفصّلة حول التنقّل مشيًا لهذا المسار في مصفوفة steps[]، مثل "اتّجه شمال غرب" و"انعطف يسارًا إلى شارع Arelious Walker" و"انعطف يسارًا إلى شارع Innes".

‫DirectionsStep هو عنصر حرفي يتضمّن الحقول التالية:

تحتوي السمة instructions على تعليمات لهذه الخطوة ضمن سلسلة نصية.
تحتوي distance على المسافة التي قطعتها هذه الخطوة حتى الخطوة التالية، وذلك ككائن Distance. (راجِع الوصف في DirectionsLeg أعلاه). قد يكون هذا الحقل غير محدّد إذا كانت المسافة غير معروفة.
يحتوي duration على تقدير للوقت المطلوب لتنفيذ الخطوة، حتى الخطوة التالية، كعنصر Duration. (يُرجى الاطّلاع على الوصف في DirectionsLeg أعلاه). قد يكون هذا الحقل غير محدّد إذا كانت المدة غير معروفة.
يمثّل start_location الموقع الجغرافي المرمّز LatLng لنقطة بداية هذه الخطوة.
يحتوي end_location على LatLng الخاصة بنقطة نهاية هذه الخطوة.
يحتوي polyline على كائن points واحد يتضمّن تمثيلاً لخط متعدد الأضلاع مرمّز للخطوة. هذا الخط المتعدد الأضلاع هو مسار تقريبي (تم تنعيمه) للخطوة.
steps[] تمثّل هذه السمة DirectionsStep عنصرًا حرفيًا يحتوي على توجيهات تفصيلية بشأن خطوات التنقّل مشيًا أو بالسيارة في توجيهات النقل العام. لا تتوفّر الخطوات الفرعية إلا لتعليمات النقل العام.
يحتوي travel_mode على TravelMode المستخدَم في هذه الخطوة. قد تتضمّن اتجاهات وسائل النقل العام مزيجًا من اتجاهات المشي واتجاهات وسائل النقل العام.
تحتوي السمة path على مصفوفة من LatLngs تصف مسار هذه الخطوة.
يحتوي transit على معلومات خاصة بالنقل العام، مثل أوقات الوصول والمغادرة واسم خط النقل العام.

المعلومات المتعلّقة بوسائل النقل العام

تعرض اتجاهات النقل العام معلومات إضافية غير ذات صلة بوسائل النقل الأخرى. يتم عرض هذه السمات الإضافية من خلال عنصر TransitDetails، ويتم عرضها كسمة من سمات DirectionsStep. من عنصر TransitDetails، يمكنك الوصول إلى معلومات إضافية عن عناصر TransitStop وTransitLine وTransitAgency وVehicleType كما هو موضّح أدناه.

تفاصيل النقل العام

يعرض العنصر TransitDetails السمات التالية:

تحتوي السمة arrival_stop على كائن TransitStop يمثّل محطة الوصول أو موقف الوصول ويتضمّن السمات التالية:
- name اسم محطة النقل العام مثال: "Union Square"
- location موقع محطة النقل العام أو موقف النقل العام، ممثَّلًا بـ LatLng
يحتوي departure_stop على عنصر TransitStop يمثّل محطة/موقف المغادرة.
تحتوي arrival_time على وقت الوصول المحدّد، ويتم تحديده كعنصر Time يتضمّن ثلاث سمات:
- value الوقت المحدّد ككائن JavaScript Date
- text الوقت المحدّد كسلسلة يُعرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.
- يحتوي time_zone على المنطقة الزمنية لهذه المحطة. القيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية التابعة لهيئة IANA، مثل "America/New_York".
تحتوي departure_time على وقت المغادرة، ويتم تحديده كعنصر Time.
تحدّد السمة headsign اتجاه التنقّل على هذا الخط، كما هو موضّح على المركبة أو في محطة المغادرة. ستكون هذه المحطة غالبًا هي المحطة النهائية.
تمثّل هذه السمة headway، إذا كانت متوفرة، عدد الثواني المتوقّع بين مواعيد المغادرة من المحطة نفسها في هذا الوقت. على سبيل المثال، إذا كانت قيمة headway هي 600، من المتوقّع أن تنتظر لمدة 10 دقائق في حال تأخّرت عن موعد الحافلة.
يحتوي line على TransitLine حرفي كائن يتضمّن معلومات حول خط النقل المستخدَم في هذه الخطوة. تقدّم السمة TransitLine اسم الخط ومشغّله، بالإضافة إلى سمات أخرى موضّحة في مستندات مرجع TransitLine.
يحتوي num_stops على عدد المحطات في هذه الخطوة. يشمل محطة الوصول، ولكن لا يشمل محطة المغادرة. على سبيل المثال، إذا كانت الاتجاهات تتضمّن المغادرة من المحطة A، والمرور بالمحطتين B وC، والوصول إلى المحطة D، ستعرض num_stops الرقم 3.

خط النقل العام

يعرض العنصر TransitLine السمات التالية:

name يحتوي على الاسم الكامل لخط النقل العام هذا، مثلاً: "7 Avenue Express" أو "14th St Crosstown".
يحتوي short_name على الاسم المختصر لخط النقل العام هذا. سيكون هذا عادةً رقم خط، مثل "2" أو "M14".
‫agencies هي مصفوفة تحتوي على عنصر TransitAgency واحد. يوفّر الكائن TransitAgency معلومات حول مشغّل هذا الخط، بما في ذلك السمات التالية:
- name يحتوي على اسم مؤسسة النقل العام.
- يحتوي phone على رقم هاتف وكالة النقل العام.
- يحتوي url على عنوان URL الخاص بمؤسسة النقل العام.
ملاحظة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام العنصر DirectionsRenderer، عليك عرض أسماء وكالات النقل العام التي تقدّم خدمات الرحلة وعناوين URL الخاصة بها في نتائج الرحلة.
تحتوي url على عنوان URL لخط النقل العام هذا كما تقدّمه هيئة النقل العام.
تحتوي السمة icon على عنوان URL للرمز المرتبط بهذا السطر. ستستخدم معظم المدن رموزًا عامة تختلف حسب نوع المركبة. تتضمّن بعض خطوط النقل العام، مثل نظام مترو الأنفاق في نيويورك، رموزًا خاصة بهذا الخط.
يمثّل color اللون المستخدَم عادةً في اللوحات الإرشادية الخاصة بوسيلة النقل هذه. سيتم تحديد اللون كسلسلة سداسية عشرية مثل: ‎#FF0033.
تحتوي السمة text_color على لون النص المستخدَم عادةً في اللافتات الخاصة بهذا الخط. سيتم تحديد اللون كسلسلة سداسية عشرية.
يحتوي vehicle على كائن Vehicle يتضمّن السمات التالية:
- يحتوي name على اسم المركبة في هذا السطر. مثال: "مترو الأنفاق"
- يحتوي type على نوع المركبة المستخدَمة في هذا الخط. راجِع مستندات نوع المركبة للحصول على قائمة كاملة بالقيم المسموح بها.
- تحتوي icon على عنوان URL للرمز المرتبط عادةً بنوع المركبة هذا.
- يحتوي local_icon على عنوان URL للرمز المرتبط بنوع المركبة هذا، استنادًا إلى لوحات الإشارات الخاصة بوسائل النقل المحلية.

نوع المركبة

يعرض العنصر VehicleType السمات التالية:

القيمة	التعريف
`VehicleType.RAIL`	السكك الحديدية
`VehicleType.METRO_RAIL`	نظام النقل بالقطارات الخفيفة
`VehicleType.SUBWAY`	قطار خفيف تحت الأرض
`VehicleType.TRAM`	قطار خفيف فوق الأرض
`VehicleType.MONORAIL`	قطار بخط حديدي واحد
`VehicleType.HEAVY_RAIL`	السكك الحديدية الثقيلة
`VehicleType.COMMUTER_TRAIN`	قطارات سريعة
`VehicleType.HIGH_SPEED_TRAIN`	قطار عالي السرعة
`VehicleType.BUS`	حافلة
`VehicleType.INTERCITY_BUS`	حافلة بين المدن
`VehicleType.TROLLEYBUS`	ترولي باص
`VehicleType.SHARE_TAXI`	سيارة الأجرة المشتركة هي نوع من الحافلات يمكنها إقلال الركاب وتوصيلهم في أي مكان على مسارها.
`VehicleType.FERRY`	عبّارة
`VehicleType.CABLE_CAR`	مركبة تعمل على كابل، وعادةً ما تكون على الأرض قد تكون عربات التلفريك المعلقة من النوع `VehicleType.GONDOLA_LIFT`.
`VehicleType.GONDOLA_LIFT`	عربة تلفريك معلّقة
`VehicleType.FUNICULAR`	مركبة يتم سحبها إلى أعلى منحدر شديد بواسطة كابل يتألف القطار المعلق عادةً من عربتَين، وتعمل كل عربة كوزن موازن للأخرى.
`VehicleType.OTHER`	ستعرض جميع المركبات الأخرى هذا النوع.

Inspecting DirectionsResults

يمكن فحص مكوّنات DirectionsResults، أي DirectionsRoute وDirectionsLeg وDirectionsStep وTransitDetails، واستخدامها عند تحليل أي ردّ على طلب اتجاهات.

ملاحظة مهمة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام العنصر DirectionsRenderer، عليك عرض أسماء وكالات النقل العام وعناوين URL الخاصة بها التي تقدّم خدماتها في نتائج الرحلات.

يعرض المثال التالي مسارًا للمشي إلى بعض مناطق الجذب السياحي في مدينة نيويورك. نتفحّص مسار الرحلة DirectionsStep لإضافة علامات لكل خطوة، ونرفق معلومات بعنصر InfoWindow يتضمّن نصًا إرشاديًا لتلك الخطوة.

ملاحظة: بما أنّنا نحسب اتجاهات المشي، نعرض أيضًا أي تحذيرات للمستخدم في لوحة <div> منفصلة.

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

في نص HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

عرض مثال

استخدام نقاط المرور في "الطرق"

كما هو موضّح في DirectionsRequest، يمكنك أيضًا تحديد نقاط المرور (من النوع DirectionsWaypoint) عند احتساب المسارات باستخدام خدمة "الاتجاهات" للحصول على اتجاهات المشي أو ركوب الدراجات أو القيادة. لا تتوفّر نقاط على المسار لاتجاهات النقل العام. تتيح لك نقاط المرور احتساب المسارات عبر مواقع جغرافية إضافية، وفي هذه الحالة، يمر المسار الذي يتم عرضه بنقاط المرور المحدّدة.

يتألف waypoint من الحقول التالية:

يمثّل location (مطلوب) عنوان نقطة الطريق.
يشير stopover (اختياري) إلى ما إذا كانت نقطة الطريق هذه هي محطة توقّف فعلية على المسار (true) أو مجرد تفضيل للمرور عبر الموقع الجغرافي المحدّد (false). تكون محطات التوقّف true تلقائيًا.

تنبيه: سيؤدي ضبط stopover على false لتجنُّب نقاط التوقف إلى ظهور اتجاهات صارمة جدًا في تفسيرها لنقطة الطريق. وقد يؤدي ذلك إلى حدوث انحرافات كبيرة في المسار أو ظهور الخطأ ZERO_RESULTS في رمز حالة الاستجابة إذا تعذّر على خدمة "خرائط Google" إنشاء اتجاهات مرور عبر تلك النقطة.

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

إذا طلبت من خدمة "الاتجاهات" تحسين ترتيب نقاط الطريق، سيتم عرض ترتيبها في الحقل waypoint_order ضمن العنصر DirectionsResult.

يحسب المثال التالي مسارات بين بلدان مختلفة في الولايات المتحدة باستخدام مجموعة متنوعة من نقاط البداية ونقاط النهاية ونقاط المرور. (لتحديد نقاط طريق متعددة، اضغط على Ctrl-Click عند اختيار عناصر ضمن القائمة). يُرجى العِلم أنّنا نفحص routes.start_address وroutes.end_address لتزويدنا بنص نقطة البداية ونقطة النهاية لكل مسار.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;index.js

الحدود والقيود المفروضة على نقاط المرور

تنطبق حدود الاستخدام والقيود التالية:

الحد الأقصى لعدد نقاط المرور المسموح بها عند استخدام خدمة "الاتجاهات" في Maps JavaScript API هو 25 نقطة، بالإضافة إلى نقطة البداية والوجهة. تكون الحدود هي نفسها بالنسبة إلى خدمة الويب Directions API (الإصدار القديم).
بالنسبة إلى الخدمة المستندة إلى الويب لواجهة Directions API (الإصدار القديم)، يُسمح للعملاء باستخدام 25 نقطة طريق، بالإضافة إلى نقطة البداية ونقطة النهاية.
يُسمح لعملاء "الخطة المميزة" في "منصة خرائط Google" باستخدام 25 نقطة طريق، بالإضافة إلى نقطة البداية ونقطة النهاية.
لا تتوفّر نقاط على المسار لاتجاهات النقل العام.

الاتجاهات القابلة للسحب

يمكن للمستخدمين تعديل اتجاهات القيادة أو المشي أو ركوب الدراجات المعروضة باستخدام DirectionsRenderer بشكل ديناميكي إذا كانت قابلة للسحب، ما يتيح للمستخدم اختيار المسارات وتغييرها من خلال النقر على المسارات الناتجة وسحبها على الخريطة. يمكنك تحديد ما إذا كان عرض أداة العرض يتيح سحب الاتجاهات من خلال ضبط قيمة السمة draggable على true. لا يمكن جعل اتجاهات النقل العام قابلة للسحب.

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

بما أنّ الاتجاهات القابلة للسحب يتم تعديلها وعرضها من جهة العميل، قد تحتاج إلى تتبُّع حدث directions_changed والتعامل معه في DirectionsRenderer ليتم إعلامك عندما يعدّل المستخدم الاتجاهات المعروضة.

يوضّح الرمز التالي رحلة من بيرث على الساحل الغربي لأستراليا إلى سيدني على الساحل الشرقي. يراقب الرمز الحدث directions_changed لتعديل إجمالي المسافة المقطوعة في جميع مراحل الرحلة.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;index.js

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

خدمة الاتجاهات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة

الخطوات الأولى

الأسعار والسياسات

الأسعار

السياسات

طلبات الحصول على الاتجاهات

وسائل النقل

خيارات النقل العام

خيارات القيادة

أنظمة الوحدات

تحديد المنطقة المفضّلة للاتجاهات

عرض الاتجاهات

حالة طلب البحث عن الاتجاهات

عرض DirectionsResult

كائن DirectionsResult

نقاط الطريق المرمّزة جغرافيًا للاتجاهات

مسارات الاتجاهات

Directions Legs

خطوات الاتجاهات

المعلومات المتعلّقة بوسائل النقل العام

تفاصيل النقل العام

خط النقل العام

نوع المركبة

Inspecting DirectionsResults

استخدام نقاط المرور في "الطرق"

TypeScript

JavaScript

الحدود والقيود المفروضة على نقاط المرور

الاتجاهات القابلة للسحب

TypeScript

JavaScript

تجربة عيّنة

خدمة الاتجاهات