نظرة عامة
يمكنك حساب الاتجاهات (باستخدام مجموعة متنوعة من طرق النقل) باستخدام الكائن DirectionsService
. يتواصل هذا الكائن مع خدمة اتجاهات واجهة برمجة التطبيقات لخرائط Google التي تتلقى طلبات الاتجاهات وتعرض مسارًا فعالاً.
يُعدّ وقت السفر العامل الأساسي الذي تم تحسينه، ولكن قد يتم أخذ عوامل أخرى
في الاعتبار، مثل المسافة وعدد المنعطفات وغيرها من العوامل في الاعتبار.
ويمكنك التعامل مع نتائج هذه الاتجاهات بنفسك أو استخدام الكائن DirectionsRenderer
لعرض هذه النتائج.
عند تحديد الأصل أو الوجهة في طلب الاتجاهات، يمكنك تحديد سلسلة طلب بحث (على سبيل المثال، "شيكاغو، إلينوي" أو "داروين، نيوساوث ويلز، أستراليا")، أو قيمة LatLng
، أو كائن المكان.
يمكن لخدمة الاتجاهات عرض الاتجاهات متعددة الأجزاء باستخدام سلسلة من نقاط الطرق. يتم عرض الاتجاهات على شكل رسم متعدد الخطوط لرسم المسار على الخريطة، أو كسلسلة من الوصف النصي داخل عنصر <div>
(على سبيل المثال، "الانعطاف مباشرة إلى منحدر جسر ويليامزبورغ").
البدء
قبل استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة برمجة تطبيقات الاتجاهات في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات التي تم تمكينها:
- انتقِل إلى Google Cloud Console.
- انقر على زر اختيار مشروع، ثم حدد المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات جافا سكريبت للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الاتجاهات.
- إذا كنت ترى واجهة برمجة التطبيقات في القائمة، فأنت على أتم استعداد. في حال عدم إدراج واجهة برمجة التطبيقات،
يمكنك تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة من القائمة الجانبية اليمنى.
- ابحث عن واجهة برمجة التطبيقات للاتجاهات، ثم حددها من قائمة النتائج.
- اختَر تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات الاتجاهات في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
التسعير والسياسات
التسعير
اعتبارًا من 16 تموز (يوليو) 2018، تم تفعيل خطة تسعير جديدة للدفع حسب الاستخدام للخرائط والمسارات والأماكن. للتعرف على مزيد من المعلومات حول الأسعار وحدود الاستخدام الجديدة لاستخدام خدمة الاتجاهات في جافا سكريبت، راجع الاستخدام والفوترة لواجهة برمجة تطبيقات الاتجاهات.
السياسات
يجب أن يتوافق استخدام خدمة الاتجاهات مع السياسات الموضحة لواجهة برمجة تطبيقات الاتجاهات.
طلبات الاتجاهات
إن الدخول إلى خدمة الاتجاهات غير متزامن، نظرًا لأن واجهة برمجة التطبيقات لخرائط Google تحتاج إلى إجراء استدعاء لخادم خارجي. لهذا السبب، يجب تمرير طريقة معاودة الاتصال
عند اكتمال الطلب. من المفترض أن تعالج طريقة رد الاتصال هذه النتيجة(النتائج). يرجى ملاحظة أن خدمة الاتجاهات قد تعرض أكثر من برنامج رحلة واحد محتمل كمصفوفة من 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
أو كعنصر مكان. إذا كنت تستخدم كائن 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' } }
أنظمة الوحدات
بشكل افتراضي، يتم حساب الاتجاهات وعرضها باستخدام
نظام الوحدة لبلد أو منطقة الأصل.
(ملاحظة: إنّ المصادر التي يتم التعبير عنها باستخدام إحداثيات خطوط العرض/خطوط الطول بدلاً من العناوين تُستخدم تلقائيًا دائمًا في الوحدات المترية). فعلى سبيل المثال، يؤدي المسار من "شيكاغو، إلينوي" إلى "تورونتو، أونتاريو" إلى عرض النتائج بالأميال، بينما يعرض المسار العكسي النتائج بالكيلومترات. يمكنك
إلغاء نظام الوحدة هذا من خلال إعداد نظام بشكل صريح ضمن
الطلب باستخدام إحدى قيم UnitSystem
التالية:
- تحدّد السمة
UnitSystem.METRIC
استخدام النظام المتري. يتم عرض المسافات باستخدام الكيلومترات. - يحدّد
UnitSystem.IMPERIAL
استخدام النظام الإمبراطوري (باللغة الإنجليزية). يتم عرض المسافات باستخدام الأميال.
ملاحظة: يؤثر إعداد نظام الوحدة هذا فقط في النص المعروض للمستخدم. تحتوي نتيجة الاتجاهات أيضًا على قيم المسافة، والتي لا تظهر للمستخدم، ويتم التعبير عنها دائمًا بالأمتار.
انحياز المنطقة للاتجاهات
تعرض خدمة اتجاهات واجهة برمجة التطبيقات لخرائط Google نتائج العناوين التي تأثرت بالنطاق (المنطقة أو البلد) الذي حمّلت منه مجموعة برامج تشغيل جافا سكريبت. (نظرًا لأن معظم المستخدمين يحمّلون https://maps.googleapis.com/
،
يؤدي ذلك إلى تعيين نطاق ضمني إلى الولايات المتحدة.) إذا حمّلت التشغيل المبدئي من نطاق متوافق مختلف، ستحصل على نتائج متأثرة بذلك النطاق. على سبيل المثال، قد تعرض عمليات البحث عن "سان فرانسيسكو" نتائج مختلفة عن التطبيقات التي تُحمِّل https://maps.googleapis.com/
(الولايات المتحدة) بدلاً من نتائج البحث التي يتم تحميلها من http://maps.google.es/
(إسبانيا).
يمكنك أيضًا ضبط خدمة الاتجاهات لإرجاع النتائج المتحيزة إلى
منطقة معينة باستخدام المعلمة region
. تأخذ هذه المعلّمة رمز منطقة، محدّدًا كعلامة فرعية لمنطقة Unicode مكوّنة من حرفين (غير رقمي). في معظم الحالات، يتم تعيين هذه العلامات مباشرة إلى قيم من حرفين (ccTLD) ("نطاق المستوى الأعلى") مثل "uk" في "co.uk". في بعض الحالات، تتوافق العلامة region
أيضًا مع رموز ISO-3166-1، التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (cc) (مثل "بريطانيا العظمى" مثلاً).
عند استخدام المَعلمة region
:
- يُرجى تحديد بلد واحد أو منطقة واحدة فقط. ويتم تجاهل القيم المتعددة، وقد يؤدي ذلك إلى تعذُّر تنفيذ الطلب.
- استخدِم فقط العلامات الفرعية للمنطقة المؤلفة من حرفين (تنسيق CLDR لـ Unicode). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.
لا يتم دعم انحياز المنطقة إلا للبلدان والمناطق التي تتيح الاتجاهات. راجِع تفاصيل التغطية في "منصة خرائط Google" للاطّلاع على التغطية الدولية لواجهة برمجة التطبيقات للاتجاهات.
عرض الاتجاهات
يتطلّب بدء طلب الحصول على اتجاهات إلى
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 للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.- السمة
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
الوقت المحدّد ككائن JavaScriptDate
.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 الغرب"
مدة "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
الوقت المحدّد ككائن JavaScriptDate
.text
الوقت المحدد كسلسلة. يتم عرض الوقت في المنطقة الزمنية لمحطة النقل العام.- يحتوي
time_zone
على المنطقة الزمنية لهذه المحطة. وتكون القيمة عبارة عن اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية (IANA)، مثل "America/New_York".
- يحتوي
departure_time
على وقت المغادرة المحدّد كعنصرTime
. - يحدّد
headsign
اتجاه السير على هذا الخط، حيث يتم تحديده على المركبة أو في محطة المغادرة. ستكون هذه غالبًا محطة المحطة. headway
عند توفّرها، يحدّد هذا المقياس عدد الثواني المتوقّع بين أوقات المغادرة من محطّة التوقّف نفسها في الوقت الحالي. على سبيل المثال، عندما تكون قيمةheadway
600، قد تتوقّع الانتظار لمدة عشر دقائق إذا فاتتك الحافلة.- يحتوي
line
على قيمة حرفية لكائنTransitLine
تحتوي على معلومات حول خط النقل العام المستخدَم في هذه الخطوة. توفّر السمةTransitLine
اسم الخط ومُعامله، بالإضافة إلى الخصائص الأخرى الموضّحة في المستند المرجعيTransitLine
. - يحتوي
num_stops
على عدد محطات التوقف في هذه الخطوة. تتضمن محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا كانت اتجاهاتك تكمن في المغادرة من محطّة "أ" مرورًا بالمرور من محطتَي "ب" و"ج" والوصول إلى محطّتَي "د"، فإنnum_stops
ستعرض 3.
خط رحلة
يعرض الكائن TransitLine
الخصائص التالية:
- يحتوي
name
على الاسم الكامل لخط النقل العام هذا. على سبيل المثال "7 Avenue Express" أو "14th St Crosstown". - يحتوي
short_name
على الاسم المختصر لخط النقل العام هذا. سيكون هذا عادةً رقم سطر، مثل "2" أو "M14". agencies
عبارة عن مصفوفة تحتوي على كائنTransitAgency
واحد. يقدّم الكائنTransitAgency
معلومات حول عامل تشغيل هذا السطر، بما في ذلك الخصائص التالية:- يحتوي
name
على اسم مؤسسة النقل العام. - يحتوي
phone
على رقم هاتف مؤسسة النقل العام. - يحتوي
url
على عنوان URL الخاص بمؤسسة النقل العام.
ملاحظة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام الكائن
DirectionsRenderer
، يجب عرض الأسماء وعناوين URL لمؤسسات النقل العام التي تقدم نتائج الرحلة.- يحتوي
- يحتوي
url
على عنوان URL لخط النقل العام هذا على النحو الذي تقدّمه مؤسسة النقل العام. - يحتوي
icon
على عنوان URL للرمز المرتبط بهذا السطر. تستخدم معظم المدن رموزًا عامة تختلف حسب نوع المركبة. تتضمن بعض خطوط النقل العام، مثل نظام المترو في نيويورك، رموزًا خاصة بهذا الخط. - يتضمّن
color
اللون الشائع استخدامه في اللافتات الخاصة بعملية النقل هذه. سيتم تحديد اللون كسلسلة سداسية عشرية مثل: #FF0033. - يحتوي
text_color
على لون النص المستخدم عادةً للافتات من هذا السطر. سيتم تحديد اللون كسلسلة سداسية عشرية. - يحتوي
vehicle
على كائنVehicle
يتضمن الخصائص التالية:- يحتوي
name
على اسم المركبة على هذا الخط. مثال: "Subway." - يحتوي
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>
استخدام نقاط الطرق في المسارات
وكما هو مذكور في طلب الاتجاهات،
يمكنك أيضًا تحديد نقاط الطرق
(من النوع 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، يُسمح للعملاء بالحصول على 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;