نظرة عامة
يمكنك احتساب الاتجاهات (باستخدام مجموعة متنوعة من وسائل النقل) باستخدام العنصر DirectionsService
. يتواصل هذا العنصر مع خدمة اتجاهات خرائط Google
التي تتلقى طلبات الاتجاهات وتعرض مسارًا فعّالاً.
ويُعدّ وقت التنقّل العامل الأساسي الذي تم تحسينه، لكن قد يتم أخذ عوامل أخرى في الاعتبار، مثل المسافة وعدد المنعطفات وغيرها من العوامل.
يمكنك معالجة نتائج هذه الاتجاهات بنفسك أو استخدام الكائن DirectionsRenderer
لعرض هذه النتائج.
عند تحديد نقطة الانطلاق أو الوجهة في طلب اتجاهات، يمكنك تحديد سلسلة طلب البحث (على سبيل المثال، "شيكاغو، إسرائيل" أو "داروين، نيوساوث ويلز، أستراليا")، أو قيمة LatLng
، أو عنصر مكان.
يمكن أن تعرض خدمة "الاتجاهات" اتجاهات متعددة الأجزاء باستخدام سلسلة
من نقاط الطريق. يتم عرض الاتجاهات كخط خطي
على المسار على الخريطة، أو كسلسلة من الوصف النصي داخل عنصر <div>
(على سبيل المثال، "الانعطاف مباشرةً إلى منحدر جسر ويليامزبورغ").
البدء
قبل استخدام خدمة "الاتجاهات" في واجهة برمجة تطبيقات JavaScript لـ "خرائط Google"، تأكّد أولاً من تفعيل "واجهة برمجة تطبيقات الاتجاهات" في Google Cloud Console، وذلك في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات المفعّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript لتطبيق "خرائط Google" وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Directions API.
- إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، هذا يعني أنك جاهز للبدء. إذا لم يتم إدراج واجهة برمجة التطبيقات، عليك تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة في القائمة اليمنى.
- ابحث عن Directions API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات الاتجاهات في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
الأسعار والسياسات
التسعير
اعتبارًا من 16 تموز (يوليو) 2018، تم تطبيق خطة جديدة للدفع حسب الاستخدام في "خرائط Google" و"المسارات" و"الأماكن". ولمزيد من المعلومات حول الأسعار الجديدة وحدود الاستخدام لاستخدام خدمة JavaScript Directions، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة برمجة تطبيقات الاتجاهات.
السياسات
يجب أن يتوافق استخدام خدمة "الاتجاهات" مع السياسات الموضّحة لواجهة برمجة التطبيقات الاتجاهات.
طلبات الحصول على الاتجاهات
إنّ الوصول إلى خدمة الاتجاهات غير متزامن، لأنّ
Google Maps API تحتاج إلى إجراء استدعاء لخادم
خارجي. لهذا السبب، عليك تمرير طريقة ردّ الاتصال لتنفيذها بعد اكتمال الطلب. ومن المفترض أن تعالج طريقة معاودة الاتصال هذه النتائج. تجدر الإشارة إلى أن
خدمة الاتجاهات قد تعرض أكثر من برنامج رحلة واحد
على شكل مصفوفة من routes[]
منفصلة.
لاستخدام الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط، أنشِئ عنصرًا من النوع 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
أو ككائن مكان. إذا كنت تستخدم كائن، يمكنك تحديد رقم تعريف المكان أو سلسلة طلب بحث أو موقع جغرافي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' } }
أنظمة الوحدات
وفقًا للإعدادات التلقائية، يتم احتساب الاتجاهات وعرضها باستخدام
نظام الوحدة لبلد أو منطقة المنشأ.
(ملاحظة: يتم التعبير عن المصادر باستخدام إحداثيات خطوط العرض وخطوط الطول بدلاً من العناوين التلقائية دائمًا
إلى الوحدات المترية.) على سبيل المثال، يعرض المسار من
"شيكاغو، إسرائيل" إلى "تورونتو، أونتاريو"، النتائج بالأميال،
بينما يعرض المسار العكسي النتائج بالكيلومتر. يمكنك
إلغاء نظام الوحدة هذا من خلال ضبط أحدها صراحةً في
الطلب باستخدام إحدى قيم UnitSystem
التالية:
- تحدّد السمة
UnitSystem.METRIC
استخدام نظام المقاييس. يتم عرض المسافات باستخدام الكيلومترات. - تحدّد السمة
UnitSystem.IMPERIAL
استخدام النظام الإمبراطوري (الإنجليزية). يتم عرض المسافات باستخدام الأميال.
ملاحظة: لا يؤثر إعداد نظام الوحدة هذا إلا في النص الذي يظهر للمستخدم. تتضمّن نتيجة الاتجاهات أيضًا قيم المسافة، لا تظهر للمستخدم، ويتم التعبير عنها دائمًا بالأمتار.
انحياز المنطقة للحصول على الاتجاهات
تعرض خدمة الاتجاهات في "خرائط Google" نتائج العناوين المتأثّرة
بالنطاق (المنطقة أو البلد) التي حمّلت فيها مجموعة شرائح
JavaScript. (بما أنّ معظم المستخدمين يحمّلون https://maps.googleapis.com/
، يؤدي هذا الإجراء إلى ضبط نطاق ضمني على الولايات المتحدة.) إذا حمّلت
شريط التشغيل من نطاق متوافق مختلف، ستحصل على نتائج
متأثرة بهذا النطاق. على سبيل المثال، قد تؤدي عمليات البحث عن "سان فرانسيسكو" إلى عرض نتائج مختلفة من التطبيقات التي تحمّل https://maps.googleapis.com/
(الولايات المتحدة) بدلاً من نتائج واحدة يتم تحميلها من http://maps.google.es/
(إسبانيا).
يمكنك أيضًا ضبط خدمة "الاتجاهات" لعرض النتائج المتحيّزة
لمنطقة معيّنة باستخدام المعلَمة region
. تأخذ هذه المَعلمة رمز المنطقة المحدَّد على شكل علامة فرعية للرمز يونيكود
مكوّنة من حرفَين (غير رقمية). في معظم الحالات، يتم ربط هذه العلامات مباشرةً بنطاقات ccTLD ("نطاق المستوى الأعلى") مثل "uk" في "co.uk". وفي بعض
الحالات، تتوافق العلامة region
أيضًا مع رموز ISO-3166-1 التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) على سبيل المثال "GB" على سبيل المثال.
عند استخدام المَعلمة region
:
- يُرجى تحديد بلد واحد أو منطقة واحدة فقط. ويتم تجاهل القيم المتعدّدة، وقد يؤدي ذلك إلى تعذُّر تنفيذ الطلب.
- استخدِم العلامات الفرعية للمنطقة المكوّنة من حرفين فقط (بتنسيق Unicode CLDR). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.
لا يتوفّر انحياز المنطقة إلا للبلدان والمناطق التي تتيح الاتجاهات. راجِع تفاصيل تغطية "منصة خرائط Google" للاطّلاع على التغطية الدولية لواجهة برمجة التطبيقات Directions.
عرض الاتجاهات
إنّ بدء طلب اتجاهات إلى 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 API الأخرى. على سبيل المثال، يمكنك استخدامplace_id
مع مكتبة واجهة برمجة تطبيقات أماكن Google للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.- تمثّل السمة
types[]
مصفوفة تشير إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من الصفر أو أكثر من العلامات التي تحدّد نوع الميزة المعروضة في النتيجة. على سبيل المثال، يعرض رمز الموقع الجغرافي "شيكاغو" المنطقة المحلية التي تشير إلى أن "شيكاغو" مدينة، وتعرض أيضًا "سياسة" للإشارة إلى أنها كيان سياسي.
مسارات الاتجاهات
ملاحظة: تمت إعادة تسمية العنصر DirectionsTrip
القديم DirectionsRoute
. يُرجى العلم بأنّ المسار
يشير الآن إلى الرحلة الكاملة لنهاية الرحلة بدلاً من
الذهاب في رحلة على صعيد رحلة أحد الوالدَين.
تحتوي السمة DirectionsRoute
على نتيجة واحدة من
المصدر والوجهة المحدّدَين. وقد يتألف هذا المسار من
ساق واحدة أو أكثر (من النوع DirectionsLeg
)
استنادًا إلى ما إذا تم تحديد أي نقاط على الطريق. بالإضافة إلى ذلك، يحتوي المسار أيضًا على معلومات عن حقوق الطبع والنشر والتحذير التي يجب عرضها للمستخدم بالإضافة إلى معلومات التوجيه.
تمثّل السمة DirectionsRoute
حرفًا حرفيًا في الحقول التالية:
- تحتوي السمة
legs[]
على مصفوفة منDirectionsLeg
كُلّ، ويحتوي كل منها على معلومات عن ساق المسار من موقعَين ضمن المسار المحدّد. ستظهر ساق منفصلة لكل نقطة أو وجهة محدّدة. (سيحتوي المسار الذي لا يحتوي على نقاط طريق علىDirectionsLeg
واحدة فقط. يتكون كل ساق من سلسلة منDirectionStep
.) - تحتوي السمة
waypoint_order
على مصفوفة تشير إلى ترتيب أي نقاط على المسار في المسار المحسوب. قد تحتوي هذه المصفوفة على ترتيب معدَّل إذا تم تمريرDirectionsRequest
optimizeWaypoints: true
. - تحتوي السمة
overview_path
على صفيف منLatLng
يمثّل مسارًا تقريبيًا (ناعمًا) للاتجاهات الناتجة. overview_polyline
يحتوي علىpoints
كائن واحد يحمل مضمّن polyline مشفّر. هذا الخط الخطي هو مسار تقريبي (ناعم) للاتجاهات الناتجة.- يحتوي
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)، مثل "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. "القديس الرابع" لا تتضمّن هذه الخطوة
التعليمات فقط، ولكنّها تتضمّن أيضًا معلومات المسافة والمدة المتعلّقة بمدى ارتباط هذه الخطوة بالخطوة التالية.
على سبيل المثال، الخطوة التي يُشار إليها بعبارة "دمج في I-80 West" قد تتضمن مدة "37 ميلاً" و "40 دقيقة"، ما يشير إلى أن الخطوة التالية
هي 37 ميلاً/40 دقيقة من هذه الخطوة.
عند استخدام خدمة الاتجاهات للبحث عن اتجاهات النقل العام،
ستتضمن مصفوفة الخطوات معلومات
النقل العام الإضافية في شكل عنصر transit
. إذا كانت الاتجاهات تتضمن وسائل نقل متعددة، سيتم تقديم اتجاهات مفصّلة للمشي أو القيادة في مصفوفة steps[]
.
على سبيل المثال، ستشمل خطوة المشي اتجاهات من مواقع البدء والانتهاء: "الذهاب إلى حلبة إنس آند فيتش". ستشمل هذه الخطوة
اتجاهات مفصّلة للمشي لهذا المسار في مصفوفة steps[]
، مثل: "الاتجاه إلى الشمال الغربي" أو "الانعطاف يسارًا إلى حي السلطان"، و
الانعطاف يسارًا إلى جادة الإسكندرية.
تمثّل السمة 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)، مثل "America/New_York".
- يتضمّن السمة
departure_time
وقت المغادرة، المحدّد كعنصرTime
. - تحدّد السمة
headsign
الاتجاه الذي تنتقل إليه على هذا الخط، لأنّها محدّدة على المركبة أو عند محطة المغادرة. وغالبًا ما تكون هذه هي محطة القطار. headway
، عندما يكون ذلك متاحًا، يحدّد عدد الثواني المتوقّع بين رحلات المغادرة من المحطة نفسها في الوقت الحالي. على سبيل المثال، إذا كانت القيمةheadway
هي 600، يمكن أن تتوقّع الانتظار لمدة 10 دقائق في حال تفويت الحافلة.- تحتوي السمة
line
على عنصرTransitLine
حرفي يحتوي على معلومات عن خط النقل العام المستخدَم في هذه الخطوة. توفّر السمةTransitLine
اسم السطر ومشغِّله، بالإضافة إلى السمات الأخرى الموضَّحة في المواد المرجعيةTransitLine
. - يحتوي
num_stops
على عدد المحطات في هذه الخطوة. تشمل محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا كانت الاتجاهات تتضمن المغادرة من المحطة "أ" والمرور بها من خلال محطتَي "ب" و"ج"، والوصول إلى المحطة "د"، ستعرضnum_stops
.
خط رحلة
يعرض الكائن TransitLine
السمات التالية:
- يحتوي
name
على الاسم الكامل لخط النقل العام هذا. مثل "7 Street Express" أو "14 سانت كروستاون". short_name
يحتوي على الاسم المختصر لخط النقل العام هذا. ويكون هذا الرقم في العادة رقم سطر، مثل "2" أو "M14".agencies
هي مصفوفة تحتوي على عنصرTransitAgency
واحد. يقدّم العنصرTransitAgency
معلومات حول عامل تشغيل هذا السطر، بما في ذلك السمات التالية:- يحتوي
name
على اسم مؤسسة النقل العام. - تتضمّن السمة
phone
رقم هاتف مؤسسة النقل العام. - يحتوي
url
على عنوان URL لمؤسسة النقل العام.
ملاحظة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام الكائن
DirectionsRenderer
، يجب عرض أسماء وعناوين النقل الخاصة بوكالات النقل العام التي تقدّم خدمات الرحلات.- يحتوي
- تتضمّن السمة
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-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;
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، بالإضافة إلى المصدر والوجهة. ويُرجى العِلم بأنّ هذه الحدود هي نفسها لخدمة الويب الخاصة بالاتجاهات في واجهة برمجة التطبيقات.
- بالنسبة إلى خدمة الويب لواجهة برمجة التطبيقات الاتجاهات، يُسمح للعملاء باستخدام 25 نقطة طريق، بالإضافة إلى نقطة الانطلاق والوجهة.
- يُسمح لعملاء خطة Premium في "منصة خرائط 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;