نظرة عامة
يمكنك حساب الاتجاهات (باستخدام طُرق نقل مختلفة) باستخدام الكائن DirectionsService
. يتواصل هذا الكائن مع خدمة الاتجاهات في واجهة برمجة تطبيقات خرائط Google، والتي تتلقى طلبات الاتجاهات وتعرض مسارًا فعالاً.
إنّ مدة الرحلة هي العامل الأساسي الذي يتم تحسينه، ولكن قد يتم أخذ عوامل أخرى في الاعتبار،
مثل المسافة وعدد الدورات وغير ذلك.
يمكنك معالجة نتائج الاتجاهات هذه بنفسك أو استخدام
الكائن DirectionsRenderer
لعرض هذه
النتائج.
عند تحديد المصدر أو الوجهة في طلب الاتجاهات،
يمكنك تحديد سلسلة طلب بحث (على سبيل المثال، "شيكاغو، إلينوي" أو
"القاهرة، جنوب سيناء"، أو قيمة LatLng
، أو عنصر
Place.
يمكن لخدمة "الاتجاهات" عرض اتجاهات متعددة الأجزاء باستخدام سلسلة
من نقاط الطريق. يتم عرض الاتجاهات على شكل خطوط متعدّدة ترسم
المسار على خريطة، أو أيضًا كسلسلة من الأوصاف
النصية ضمن العنصر <div>
(على سبيل المثال،
"الاتجاه يمينًا إلى منحدر جسر ويليامزبورغ").
البدء
قبل استخدام خدمة "الاتجاهات" في واجهة برمجة تطبيقات JavaScript للخرائط، تأكَّد أولاً من تفعيل واجهة برمجة التطبيقات Directions API في Google Cloud Console ضمن المشروع نفسه الذي أعددته لـ Maps JavaScript API.
للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Directions API.
- إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة،
يمكنك تفعيلها:
- في أعلى الصفحة، انقر على ENABLE API لعرض علامة تبويب المكتبة. ويمكنك بدلاً من ذلك اختيار المكتبة من القائمة الجانبية اليمنى.
- ابحث عن Directions API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Directions API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
الأسعار والسياسات
السعر
اعتبارًا من 16 تموز (يوليو) 2018، دخلت خطة التسعير الجديدة "الدفع حسب الاستخدام" حيز التنفيذ في "خرائط Google" و"المسارات" و"الأماكن". للحصول على مزيد من المعلومات حول الأسعار الجديدة وحدود الاستخدام لاستخدام خدمة JavaScript Directions، يمكنك الاطّلاع على الاستخدام والفوترة لواجهة برمجة تطبيقات Directions.
السياسات
ويجب أن يتوافق استخدام خدمة Directions مع السياسات الموضّحة في Directions API.
طلبات الاتجاهات
يعتبر الوصول إلى خدمة الاتجاهات غير متزامن، نظرًا لأن واجهة برمجة التطبيقات لخرائط Google تحتاج إلى إجراء اتصال بخادم خارجي. لهذا السبب، يجب ضبط طريقة معاودة الاتصال
ليتم تنفيذها عند اكتمال الطلب. من المفترض أن تعالج طريقة معاودة الاتصال هذه النتائج. يُرجى العِلم بأنّ خدمة الاتجاهات قد تعرض أكثر من برنامج رحلة واحد محتمل على شكل مصفوفة 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
(على سبيل المثال، "Chicago, IL") أو على أنّها قيمةLatLng
أو كعنصر Place. إذا كنت تستخدم كائن Place، يمكنك تحديد رقم تعريف مكان أو سلسلة طلب بحث أو موقع جغرافيLatLng
. يمكنك استرداد أرقام تعريف الأماكن من خدمات "الترميز الجغرافي" و"بحث عن الأماكن" و"الإكمال التلقائي عن الأماكن" في واجهة برمجة تطبيقات JavaScript للخرائط. للحصول على مثال لاستخدام أرقام تعريف الأماكن من ميزة "الإكمال التلقائي" الخاصة بالأماكن، يُرجى الاطّلاع على الإكمال التلقائي عن المكان والاتجاهات.destination
(مطلوبة) تحدّد موقع النهاية الذي يجب حساب الاتجاهات إليه. تتطابق الخيارات مع الحقلorigin
الموضّح أعلاه.travelMode
(مطلوبة) تحدّد وسيلة النقل التي يجب استخدامها عند احتساب الاتجاهات. ويتم تحديد القيم الصالحة في أوضاع السفر أدناه.- تحدّد السمة
transitOptions
(اختيارية) قيمًا تنطبق فقط على الطلبات التي تكونtravelMode
فيها قيمةTRANSIT
. ويمكن الاطّلاع على القيم الصالحة في قسم خيارات النقل العام أدناه. - تحدّد السمة
drivingOptions
(اختيارية) قيمًا تنطبق فقط على الطلبات التي تكونtravelMode
فيها قيمةDRIVING
. ويتم توضيح القيم الصالحة في خيارات القيادة أدناه. unitSystem
(اختيارية) تحدّد نظام الوحدات المطلوب استخدامه عند عرض النتائج. تم تحديد القيم الصالحة في Unit Systems أدناه.تحدّد
waypoints[]
(اختيارية) مصفوفة منDirectionsWaypoint
. وتعدّل نقاط الطريق المسار من خلال توجيهها عبر المواقع الجغرافية المحدّدة. ويتم تحديد نقطة الطريق ككائن حرفي مع الحقول الموضّحة أدناه:- تحدّد السمة
location
موقع النقطة الوسيطة، على أنّهاLatLng
، على أنّها كائن مكان، أو كعنصرString
سيتم ترميزه جغرافيًا. stopover
هي قيمة منطقية تشير إلى أنّ نقطة الطريق هي محطة على المسار، ما يؤثر في تقسيم المسار إلى مسارَين.
(لمزيد من المعلومات حول نقاط الطريق، راجع استخدام نقاط الطرق في المسارات أدناه).
- تحدّد السمة
optimizeWaypoints
(اختيارية) تحدّد أنّه يمكن تحسين المسار الذي يستخدمwaypoints
من خلال إعادة ترتيب نقاط الطريق بترتيب أكثر فعالية. إذا كانtrue
، ستعرض خدمة "الاتجاهات"waypoints
التي تمت إعادة ترتيبها في الحقلwaypoint_order
.(لمزيد من المعلومات، يُرجى الاطّلاع على استخدام نقاط الطرق في المسارات أدناه).- وتشير السمة
provideRouteAlternatives
(اختيارية) عند ضبطها علىtrue
إلى أنّ خدمة الاتجاهات قد توفّر أكثر من مسار بديل واحد في الاستجابة. ويُرجى العِلم بأنّ توفير بدائل للمسارات قد يزيد من وقت الاستجابة من الخادم. لا يتوفر هذا إلا للطلبات التي لا تحتوي على نقاط وسيطة. - تشير السمة
avoidFerries
(اختيارية) عند ضبطها علىtrue
إلى أنّه يجب على المسارات المحسوبة تجنُّب العبّارات، إن أمكن. - إنّ
avoidHighways
(اختيارية) عند الضبط علىtrue
تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب الطرق السريعة الرئيسية، إن أمكن. - تشير السمة
avoidTolls
(اختيارية) عند ضبطها علىtrue
إلى أنّه يجب تجنّب الطرق التي يتم احتسابها برسوم عبور، إن أمكن. region
(اختيارية) تحدّد رمز المنطقة، الذي يتم تحديده كقيمة مكوّنة من حرفَين ("نطاق المستوى الأعلى") الذي يتم ترميزه حسب البلد (ccTLD). (لمزيد من المعلومات، راجع انحياز المنطقة أدناه).
في ما يلي نموذج عن 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
(اختيارية) تحدّد الإعدادات المفضّلة لمسارات النقل العام. وباستخدام هذا الخيار، يمكنك الانحياز للخيارات المعروضة، بدلاً من قبول أفضل مسار تلقائي يتم اختياره من خلال واجهة برمجة التطبيقات. لا يمكن تحديد هذا الحقل إلّا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. يُسمح باستخدام القيم التالية:- وتشير السمة
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
. يجب ضبط القيمة على الوقت الحالي أو على وقت ما في المستقبل. لا يمكن أن تكون في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المتفق عليه لضمان معالجة متّسقة عبر المناطق الزمنية). بالنسبة إلى عملاء الخطة المميّزة في "منصة خرائط Google"، إذا ضمّنتdepartureTime
في الطلب، تعرض واجهة برمجة التطبيقات أفضل مسار وفقًا لظروف حركة المرور المتوقّعة في ذلك الوقت، وستضمِّن الوقت المتوقّع في حركة المرور (duration_in_traffic
) في الاستجابة. وإذا لم تحدّد وقت المغادرة (أي إذا لم يتضمّن الطلبdrivingOptions
)، يكون مسار الإرجاع مسارًا جيدًا بشكل عام بدون مراعاة أحوال حركة المرور. - تحدّد السمة
trafficModel
(اختيارية) الافتراضات المطلوب استخدامها عند احتساب الوقت في الزيارات. يؤثّر هذا الإعداد في القيمة المعروضة في الحقلduration_in_traffic
ضمن الردّ، والتي تتضمّن الوقت المتوقّع في عدد الزيارات استنادًا إلى المتوسّطات السابقة. يكون الإعداد التلقائي هوbestguess
. يُسمح باستخدام القيم التالية:- وتشير القيمة
bestguess
(الخيار التلقائي) إلى أنّduration_in_traffic
التي تم إرجاعها يجب أن تكون أفضل تقدير لوقت السفر بالنظر إلى المعلومات المعروفة عن كل من أحوال حركة المرور السابقة والزيارات المباشرة. تصبح حركة المرور المباشرة أكثر أهمية كلما اقتربdepartureTime
من الآن. - وتشير السمة
pessimistic
إلى أنّ السمةduration_in_traffic
التي تم إرجاعها يجب أن تكون أطول من مدة الرحلة الفعلية في معظم الأيام، علمًا أنّ هذه القيمة قد تتجاوز هذه القيمة في الأيام التي تكون فيها أحوال حركة المرور سيئة بشكل خاص. - وتشير السمة
optimistic
إلى أنّ السمةduration_in_traffic
التي تم إرجاعها يجب أن تكون أقصر من وقت السفر الفعلي في معظم الأيام، إلا أنّ الأيام التي تكون فيها أحوال حركة المرور جيدة بشكل خاص قد تكون أسرع من هذه القيمة.
- وتشير القيمة
في ما يلي نموذج من 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' } }
أنظمة الوحدات
يتم تلقائيًا احتساب الاتجاهات وعرضها باستخدام
نظام الوحدات الخاص ببلد أو منطقة المنشأ.
(ملاحظة: يتم التعبير عن المصادر باستخدام
إحداثيات خطوط الطول/العرض بدلاً من العناوين التلقائية دائمًا
بالوحدات المترية.) على سبيل المثال، إذا كان الطريق من
"شيكاغو، إلينوي" إلى "تورونتو، ONT" يعرض النتائج بالأميال،
وسيعرض المسار العكسي النتائج بالكيلومترات. يمكنك
إلغاء نظام الوحدات هذا من خلال ضبط قيمة بشكل صريح داخل
الطلب باستخدام إحدى قيم UnitSystem
التالية:
- تحدّد السمة
UnitSystem.METRIC
استخدام النظام المتري. وتظهر المسافات باستخدام الكيلومترات. - تحدّد السمة
UnitSystem.IMPERIAL
استخدام النظام الإمبراطوري (الإنجليزية). يتم عرض المسافات باستخدام الأميال.
ملاحظة: يؤثر إعداد نظام الوحدات هذا فقط على النص المعروض للمستخدم. تتضمّن نتيجة الاتجاهات أيضًا قيم المسافة، لا تظهر للمستخدم، والتي يتم التعبير عنها دائمًا بالمتر.
انحياز المنطقة للاتّجاهات
تعرض خدمة اتجاهات واجهة برمجة التطبيقات لخرائط Google نتائج العناوين المتأثرة
بالنطاق (المنطقة أو البلد) الذي حمَّلت منه
برنامج بدء تشغيل JavaScript. (بما أنّ معظم المستخدمين يحمّلون https://maps.googleapis.com/
يؤدي ذلك إلى ضبط نطاق ضمني على الولايات المتحدة). وفي حال تحميل
مسار التشغيل من نطاق متوافق آخر، ستظهر لك نتائج
تتأثر بهذا النطاق. على سبيل المثال، قد تعرض عمليات البحث عن "سان فرانسيسكو" نتائج مختلفة من التطبيقات التي تُحمِّل https://maps.googleapis.com/
(الولايات المتحدة) مقارنةً بنتائج بحث واحدة يتم تحميلها في http://maps.google.es/
(إسبانيا).
يمكنك أيضًا ضبط خدمة "الاتجاهات" لعرض النتائج المتحيزة لمنطقة معيّنة باستخدام المعلَمة region
. ويتم استخدام هذه المَعلمة
كرمز منطقة، يتم تحديده كعلامة فرعية لمنطقة Unicode (غير رقمية)
مكوَّنة من حرفَين. في معظم الحالات، يتم ربط هذه العلامات مباشرةً بقيم من حرفَين ضمن نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD)، مثل uk في co.uk على سبيل المثال. في بعض
الحالات، تتوافق العلامة region
أيضًا مع رموز ISO-3166-1 التي
تختلف أحيانًا عن قيم ccTLD (مثلاً "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
على نتيجة طلب البحث عن الاتجاهات، ويمكنك إما معالجة هذه النتائج بنفسك أو نقلها إلى عنصر 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>
يوضِّح المثال التالي الاتجاهات باستخدام أوضاع التنقّل المختلفة بين مدينة "هايت آشبوري" و"أوشن بيتش" في سان فرانسيسكو، كاليفورنيا:
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 والإصدارات الأحدث من واجهة برمجة التطبيقات، يمكنك مواصلة تنفيذ
الاتجاهات القابلة للسحب باستخدام خدمة "الاتجاهات"، وذلك من خلال إيقاف سحب المسارات البديلة.
يجب أن يكون المسار الرئيسي فقط قابلاً للسحب. ويمكن للمستخدمين سحب المسار الرئيسي إلى أن يتطابق مع
مسار بديل.
نقاط الطرق المُرمَّزة جغرافيًا للاتّجاهات
يحتوي DirectionsGeocodedWaypoint
على تفاصيل حول الترميز الجغرافي
للمصدر والوجهة ونقاط الطريق.
DirectionsGeocodedWaypoint
هو عنصر حرفي يتضمّن الحقول التالية:
- تشير السمة
geocoder_status
إلى رمز الحالة الناتج عن عملية الترميز الجغرافي. قد يحتوي هذا الحقل على القيم التالية.- يشير
"OK"
إلى عدم حدوث أي أخطاء، حيث تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل. - يشير
"ZERO_RESULTS"
إلى أن الرمز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث هذا إذا تم تمرير رمز الموقع الجغرافي إلىaddress
غير موجود.
- يشير
-
يشير
partial_match
إلى أن أداة الترميز الجغرافي لم تعرض تطابقًا تامًا للطلب الأصلي، على الرغم من تمكّنها من مطابقة جزء من العنوان المطلوب. ننصحك بفحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو إذا كان العنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد ضمن المنطقة المحلية التي يتم تمريرها في الطلب. ويمكن أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعَين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستعرض نتائج البحث "Hillpar St, Bristol, UK" مطابقة جزئية لكل من شارع "هنري ستريت" و"شارع هنرييتا". لاحظ أنه إذا اشتمل الطلب على عنصر عنوان به خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تمييز الاقتراحات التي يتم تنفيذها بهذه الطريقة على أنّها مطابقة جزئية.
place_id
هو معرّف فريد للمكان، ويمكن استخدامه مع واجهات Google APIs الأخرى. على سبيل المثال، يمكنك استخدامplace_id
مع مكتبة Google Places API للحصول على تفاصيل حول نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على معرّف المكان.types[]
هي مصفوفة تشير إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة تضم صفر أو أكثر من العلامات التي تحدّد نوع الميزة المعروضة في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لكلمة "شيكاغو" كلمة "المنطقة المحلية" التي تشير إلى أنّ "شيكاغو" مدينة، ويعرض أيضًا كلمة "سياسي" للإشارة إلى أنّها كيان سياسي.
مسارات الاتجاهات
ملاحظة: تمت إعادة تسمية عنصر DirectionsTrip
القديم إلى DirectionsRoute
. وتجدر الإشارة إلى أنّ المسار
يشير الآن إلى بداية الرحلة إلى نهايتها، وليس مجرد
جزء من رحلة رئيسية.
يحتوي حقل DirectionsRoute
على نتيجة واحدة من المصدر والوجهة المحدّدين. قد يتألف هذا المسار من
قاعدة واحدة أو أكثر (من النوع DirectionsLeg
)
استنادًا إلى ما إذا تم تحديد أي نقاط طريق. ويحتوي المسار أيضًا على معلومات حول حقوق الطبع والنشر والتحذيرات التي يجب عرضها للمستخدم بالإضافة إلى معلومات التوجيه.
DirectionsRoute
هو عنصر حرفي يتضمّن الحقول التالية:
- يحتوي
legs[]
على مصفوفة من كائناتDirectionsLeg
، يحتوي كل منها على معلومات عن جزء من المسار من موقعَين ضمن المسار المحدّد. سيتم توفير مرحلة منفصلة لكل نقطة طريق أو وجهة محددة. (سيحتوي المسار بدون نقاط للطريق على علامةDirectionsLeg
واحدة فقط.) وتتكوّن كل مرحلة من سلسلة منDirectionStep
ثوانٍ. - يحتوي
waypoint_order
على مصفوفة تشير إلى ترتيب أي نقاط طريق في المسار المحسوب. قد تحتوي هذه المصفوفة على ترتيب معدّل في حال تم تمريرDirectionsRequest
إلىoptimizeWaypoints: true
. - تحتوي السمة
overview_path
على مصفوفة منLatLng
تمثّل مسارًا تقريبيًا (متجانس) للاتجاهات الناتجة. - يحتوي
overview_polyline
على عنصرpoints
واحد يتضمّن تمثيلاً لخطوط متعدّدة مرمّزة للمسار. هذا الخط المتعدد هو مسار تقريبي (متجانس) للاتّجاهات الناتجة. - يحتوي
bounds
علىLatLngBounds
يشير إلى حدود الخطوط المتعددة على طول هذا المسار المحدد. - يحتوي
copyrights
على نص حقوق الطبع والنشر المعروض لهذا المسار. - يحتوي
warnings[]
على مجموعة من التحذيرات التي سيتم عرضها عند عرض هذه الاتجاهات. في حال عدم استخدام الكائنDirectionsRenderer
المقدَّم، عليك التعامل مع هذه التحذيرات وعرضها بنفسك. - يتضمّن
fare
السعر الإجمالي (أي إجمالي تكاليف التذاكر) لهذا المسار. يتم عرض هذه السمة فقط لطلبات النقل العام وللمسارات التي تتوفّر فيها معلومات حول أسعار التذاكر لكل مراحل النقل العام. وتشمل المعلومات ما يلي:currency
: رمز عملة ISO 4217 يشير إلى العملة المستخدَمة للتعبير عن المبلغ.value
: إجمالي مبلغ السعر بالعملة المحدّدة أعلاه
أرجل الاتجاهات
ملاحظة: تمت إعادة تسمية عنصر 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
الوقت المحدّد ككائنDate
في JavaScript.text
الوقت المحدّد كسلسلة. ويتم عرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.- تتضمن
time_zone
المنطقة الزمنية لهذه المحطة. والقيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية الصادرة عن هيئة أرقام الإنترنت المخصصة (IANA)، مثل "أمريكا/نيويورك".
- يتضمّن
departure_time
وقت المغادرة المقدَّر لهذه المرحلة، والذي تم تحديده كعنصرTime
. لا يتوفّرdeparture_time
إلا لاتجاهات النقل العام. - تحتوي السمة
start_location
علىLatLng
لمصدر هذه الساق. بما أنّ خدمة ويب الاتجاهات تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار من وسائل النقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد يكونstart_location
مختلفًا عن نقطة الانطلاق المحدّدة لهذه المحطة إذا كانت الطريق مثلاً ليست بالقرب من نقطة الانطلاق. - تحتوي
end_location
علىLatLng
لوجهة هذه المحطة. بما أنّDirectionsService
تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار لوسائل النقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد تكون السمةend_location
مختلفة عن الوجهة المقدَّمة في هذه المرحلة، إذا كانت الطريق مثلاً ليست بالقرب من الوجهة. - يتضمّن
start_address
العنوان الذي يمكن لشخص عادي قراءته (عادةً ما يكون عنوان الشارع) لبداية هذه المرحلة.
يتم قراءة هذا المحتوى كما هو، لذا لا تحلّل العنوان المنسَّق بشكل آلي. - يتضمّن
end_address
العنوان الذي يمكن لشخص عادي قراءته (عادةً عنوان الشارع) لنهاية هذه المحطة.
يتم قراءة هذا المحتوى كما هو، لذا لا تحلّل العنوان المنسَّق بشكل آلي.
خطوات الحصول على الاتجاهات
السمة DirectionsStep
هي الوحدة الذرّية في مسار
الاتجاه، وتحتوي على خطوة واحدة تصف تعليمات محدّدة وواحدة حول الرحلة. مثال: "الاتجاه يسارًا عند الغرب الشارع الرابع" لا تصف الخطوة
التعليمات فقط، بل تحتوي أيضًا على معلومات
حول المسافة والمدة
تتعلّق بكيفية ارتباط هذه الخطوة بالخطوة التالية.
على سبيل المثال، قد تتضمّن الخطوة التي يتم الإشارة إليها باسم "الدمج في I-80 West" مدة "37 ميلاً" و "40 دقيقة"، ما يشير إلى أنّ الخطوة التالية هي
37 ميلاً/40 دقيقة من هذه الخطوة.
عند استخدام خدمة "الاتجاهات" للبحث عن اتجاهات النقل العام، ستتضمّن
مصفوفة الخطوات معلومات إضافية
خاصة بالنقل العام على شكل عنصر transit
. إذا
كانت الاتجاهات تشمل وسائل نقل متعددة، سيتم تقديم اتجاهات مفصّلة
للمشي أو القيادة في مصفوفة steps[]
.
على سبيل المثال، ستتضمن خطوة المشي الاتجاهات من موقعي البداية والنهاية: "المشي إلى شارع السلام". وستتضمّن هذه الخطوة
اتجاهات المشي التفصيلية لهذا المسار في مجموعة
steps[]
، مثل: "الاتجاه إلى الشمال الغربي" و"الانعطاف لليسار"
و"الاتجاه يسارًا إلى جادة Innes Ave".
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
اسم محطة/محطة النقل العام مثال: "ساحة الاتحاد".location
موقع محطة/محطة النقل العام، ويتم تمثيلها على أنّهاLatLng
.
- يحتوي
departure_stop
على عنصرTransitStop
يمثّل محطة المغادرة. - يحتوي السمة
arrival_time
على وقت الوصول المحدد كعنصرTime
مع ثلاث سمات:value
الوقت المحدّد ككائنDate
في JavaScript.text
الوقت المحدّد كسلسلة. ويتم عرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.- تتضمن
time_zone
المنطقة الزمنية لهذه المحطة. والقيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية الصادرة عن هيئة أرقام الإنترنت المخصصة (IANA)، مثل "أمريكا/نيويورك".
- يحتوي
departure_time
على وقت المغادرة المحدد ككائنTime
. - تحدّد السمة
headsign
الاتجاه الذي يجب السير فيه على هذا الخط، حيث يتم وضع علامة عليه على المركبة أو عند محطة المغادرة. ستكون هذه غالبًا محطة النهاية. - تحدّد هذه السمة
headway
، عند توفّرها، عدد الثواني المتوقّعة بين أوقات المغادرة من المحطة نفسها في الوقت الحالي. على سبيل المثال، إذا كانت قيمةheadway
هي 600، يمكنك الانتظار لمدة عشر دقائق إذا فاتتك الحافلة. - يحتوي
line
على العنصر الحرفيTransitLine
يحتوي على معلومات حول خط النقل العام المستخدَم في هذه الخطوة. توفّر السمةTransitLine
اسم السطر وعامل تشغيله، إلى جانب سمات أخرى موضّحة في المستندات المرجعيةTransitLine
. - يتضمّن
num_stops
عدد محطات التوقف في هذه الخطوة. تشمل هذه الفئة محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا كانت اتجاهاتك تتضمّن المغادرة من المحطة "أ" والمرور بالمحطتَين "ب" و"ج" والوصول إلى المحطة "د"، سيعرضnum_stops
الرقم 3.
خط رحلة
يعرض الكائن TransitLine
السمات التالية:
- يحتوي
name
على الاسم الكامل لخط النقل العام هذا. على سبيل المثال: "شارع 7 إكسبرس" أو "شارع عباس العقاد" - يحتوي
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 |
ستعرض جميع المركبات الأخرى هذا النوع. |
فحص نتائج الاتجاهات
يمكن فحص مكوّنات 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
بشكل تلقائي.
تحسب خدمة الاتجاهات تلقائيًا مسارًا عبر نقاط الطريق المتوفّرة بترتيبها المحدّد. اختياريًا، يمكنك تمرير optimizeWaypoints: true
داخل
DirectionsRequest
للسماح لخدمة "الاتجاهات"
بتحسين المسار المقدّم من خلال إعادة ترتيب نقاط الطريق
بترتيب أكثر فعالية. (يهدف هذا التحسين إلى حلّ
مشكلة مندوب المبيعات المتنقلين). إنّ مدة الرحلة هي العامل الأساسي
الذي يتم تحسينه، ولكن قد يتم أخذ عوامل أخرى في الاعتبار عند تحديد المسار الأكثر كفاءة، مثل المسافة وعدد الدورات وغير ذلك. يجب أن تكون جميع نقاط الطرق محطات توقف لخدمة "الاتجاهات" لتحسين مسارها.
إذا طلبت من خدمة الاتجاهات تحسين ترتيب نقاط الطريق، سيتم عرض ترتيبها في الحقل waypoint_order
ضمن الكائن DirectionsResult
.
يحتسب المثال التالي المسارات عبر البلدان في الولايات المتحدة باستخدام مجموعة متنوعة من نقاط البداية ونقاط النهاية ونقاط الطرق. (لتحديد نقاط طريق متعددة، اضغط على
Ctrl مع النقر عند اختيار عناصر ضمن القائمة).
يُرجى العِلم أنّنا نفحص 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;
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;
الحدود والقيود المفروضة على نقاط الطرق
تنطبق حدود الاستخدام وحدود الاستخدام التالية:
- الحد الأقصى لعدد نقاط الطريق المسموح بها عند استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط هو 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;
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;