نظرة عامة
يمكنك حساب الاتجاهات (باستخدام طرق متنوعة
من وسائل النقل) باستخدام DirectionsService
الخاص بك. يتصل هذا الكائن بالاتجاهات في Google Maps API
الخدمة التي تتلقى طلبات الاتجاهات وتعرض مسارًا فعالاً.
إنّ وقت السفر هو العامل الأساسي الذي يتم تحسينه، ولكن هناك عوامل أخرى.
قد نأخذ في الاعتبار المسافة وعدد الدورات وغير ذلك الكثير.
يمكنك إما التعامل مع نتائج هذه الاتجاهات بنفسك أو استخدام
عنصر DirectionsRenderer
لعرض هذه العناصر
نتائجك.
عند تحديد نقطة الانطلاق أو الوجهة في طلب الاتجاهات،
يمكنك تحديد سلسلة استعلام (على سبيل المثال، "شيكاغو، إلينوي" أو
"داروين، نيوساوث ويلز، أستراليا")، قيمة LatLng
، أو
العنصر Place.
يمكن لخدمة "الاتجاهات" عرض الاتجاهات متعددة الأجزاء باستخدام سلسلة.
نقاط الطريق. يتم عرض الاتجاهات كرسم متعدّد الخطوط.
المسار على الخريطة، أو بالإضافة إلى ذلك كسلسلة من النصوص
وصف ضمن عنصر <div>
(على سبيل المثال،
"الانعطاف لليمين إلى منحدر جسر ويليامزبيرج").
الخطوات الأولى
قبل استخدام خدمة "الاتجاهات" في Maps JavaScript API، عليك أولاً تفعيل واجهة برمجة التطبيقات Directions API في Google Cloud Console الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة واجهات برمجة التطبيقات المفعّلة:
- الانتقال إلى قسم Google Cloud Console:
- انقر على الزر اختيار مشروع. ثم اختيار نفس المشروع الذي أعددته Maps JavaScript API وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة التطبيقات للاتجاهات:
- إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، هذا يعني أنّك جاهز للعمل. إذا لم يتم إدراج واجهة برمجة التطبيقات،
تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة بدلاً من ذلك، من القائمة الجانبية اليمنى، انقر على المكتبة.
- ابحث عن Directions API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Directions API في قائمة واجهات برمجة التطبيقات على لوحة البيانات:
الأسعار والسياسات
التسعير
اعتبارًا من 16 تموز (يوليو) 2018، تم اعتماد خطة تسعير جديدة لنظام "الدفع حسب الاستخدام". التأثير على الخرائط والمسارات والأماكن. مزيد من المعلومات عن الأسعار الجديدة وحدود الاستخدام لاستخدام خدمة "اتجاهات JavaScript"، راجِع الاستخدام والفوترة لواجهة برمجة تطبيقات الاتجاهات.
السياسات
يجب أن يتوافق استخدام خدمة "الاتجاهات" مع السياسات الموضّحة في Directions API
طلبات الاتجاهات
الوصول إلى خدمة الاتجاهات غير متزامن، نظرًا
تحتاج واجهة برمجة التطبيقات لخرائط 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. إذا كنت تستخدم 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
.(للمزيد من لمزيد من المعلومات، راجع استخدام نقاط الطرق في المسارات. below.)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
. يجب أن تكون القيمة إلى الوقت الحالي أو بعض الوقت في المستقبل. لا يمكن أن تكون في في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المنسّق (UTC) لضمان معالجة متسقة عبر المناطق الزمنية). بالنسبة إلى عملاء الخطة المميّزة في "منصة خرائط Google"، إذا كنت ضمِّنdepartureTime
في الطلب، فستعرض واجهة برمجة التطبيقات أفضل مسار بالنظر إلى ظروف حركة المرور المتوقعة في ذلك الوقت، يشمل الوقت المتوقع لحركة المرور (duration_in_traffic
) في الرد. وفي حال عدم تحديد وقت للمغادرة (أي إذا كان الطلب لا يتضمنdrivingOptions
)، المسار الذي تم إرجاعه مسارًا جيدًا بشكل عام دون مراعاة أحوال حركة المرور.trafficModel
(اختياري) يحدد الافتراضات بشأن ستستخدمه عند حساب الوقت في حركة المرور. يؤثر هذا الإعداد في القيمة التي تم إرجاعها في الحقلduration_in_traffic
في الرد، الذي يحتوي على الوقت المتوقع لحركة المرور استنادًا إلى المتوسطات السابقة. وتكون القيمة التلقائية هيbestguess
. القيم التالية مسموح بها:- تشير قيمة الحقل "
bestguess
" (الخيار التلقائي) إلى أنّ القيم التي تم إرجاعها يجب أن يكونduration_in_traffic
هو أفضل تقدير للسفر بناءً على ما هو معروف عن كل من ظروف حركة المرور السابقة حركة المرور المباشرة. تصبح حركة المرور المباشرة أكثر أهمية كلما اقتربتdepartureTime
حتى الآن. - تشير السمة
pessimistic
إلى أنّ القيمة التي تم إرجاعها يجب أن تكون مدة الرحلةduration_in_traffic
أطول من المسافة الفعلية. الوقت في معظم الأيام، ومع ذلك في بعض الأيام ذات الزيارات السيئة التي يمكن أن تتجاوز هذه القيمة. - تشير السمة
optimistic
إلى أنّ القيمة التي تم إرجاعها يجب أن تكون قيمة الحقل "duration_in_traffic
" أقصر من القيمة الفعلية. ووقت السفر في معظم الأيام، على الرغم من أن الأيام من حين لآخر تكون جيدة قد تكون أحوال حركة المرور أسرع من هذه القيمة.
- تشير قيمة الحقل "
وفي ما يلي نموذج DirectionsRequest
لاتجاهات القيادة:
{ origin: 'Chicago, IL', destination: 'Los Angeles, CA', travelMode: 'DRIVING', drivingOptions: { departureTime: new Date(Date.now() + N), // for the time N milliseconds from now. trafficModel: 'optimistic' } }
أنظمة الوحدات
بشكل افتراضي، يتم حساب الاتجاهات وعرضها باستخدام
نظام الوحدة لبلد أو منطقة المنشأ
(ملاحظة: المصادر التي تم التعبير عنها باستخدام
إحداثيات خط العرض/خط الطول بدلاً من العناوين الافتراضية دائمًا
إلى الوحدات المترية). على سبيل المثال، مسار من
"شيكاغو، إلينوي" إلى "تورونتو، ONT" ستعرض النتائج بالميل، بينما
فسيتم عرض النتائج بالكيلومترات. إِنْتَ
إلغاء نظام الوحدة هذا عن طريق تعيين واحدٍ بشكلٍ صريح داخل
طلب باستخدام أحد UnitSystem
التالية
القيم التالية:
- يحدد
UnitSystem.METRIC
استخدام النظام المتري. يتم عرض المسافات باستخدام الكيلومترات. - يحدد
UnitSystem.IMPERIAL
استخدام الحروف الإنجليزية (باللغة الإنجليزية). يتم عرض المسافات باستخدام الأميال.
ملاحظة: إعداد نظام الوحدة هذا فقط يؤثر في النص المعروض للمستخدم. تظهر نتيجة الاتجاهات أيضًا يحتوي على قيم المسافة، ولا يتم عرضها للمستخدم، والتي تكون دائمًا ويتم التعبير عنه بالمتر.
انحياز المنطقة للاتجاهات
تعرض خدمة الاتجاهات في واجهة برمجة تطبيقات Google Maps نتائج العناوين المتأثرة.
حسب النطاق (المنطقة أو البلد) الذي حمَّلت منه JavaScript
هيكل خارجي. (نظرًا لأن معظم المستخدمين يحمّلون https://maps.googleapis.com/
يؤدي ذلك إلى تعيين نطاق ضمني للولايات المتحدة.) إذا قمت بتحميل
برنامج التشغيل من نطاق متوافق مختلف، ستحصل على نتائج
المتأثر بهذا المجال. على سبيل المثال، تبحث عمليات البحث عن "سان فرانسيسكو" قد
عرض نتائج مختلفة من التطبيقات التي يتم تحميلها
https://maps.googleapis.com/
(الولايات المتحدة) من واحد
جارٍ تحميل http://maps.google.es/
(إسبانيا).
يمكنك أيضًا تعيين خدمة الاتجاهات لإرجاع النتائج المتحيزة إلى
منطقة معينة باستخدام المعلمة region
. هذه المعلمة
يأخذ رمز منطقة، محدد في شكل يونيكود من حرفين (غير رقمي)
المنطقة الفرعية. وفي معظم الحالات، يتم ربط هذه العلامات مباشرةً بنطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("المستوى الأعلى).
مجال") قيم من حرفين مثل "uk" في co.uk على سبيل المثال. في بعض
الحالات، فإن العلامة region
تتوافق أيضًا مع رموز ISO-3166-1 التي
تختلف أحيانًا عن قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) (على سبيل المثال: "بريطانيا العظمى").
عند استخدام مَعلمة region
:
- حدِّد بلدًا واحدًا أو منطقة واحدة فقط. يتم تجاهل القيم المتعددة، إلى فشل الطلب.
- استخدِم فقط علامات فرعية للمنطقة من حرفين (تنسيق Unicode CLDR). كل ما غير ذلك المدخلات إلى حدوث أخطاء.
لا يتم توفير انحياز المنطقة إلا للبلدان والمناطق التي تدعم الاتجاهات. الرجوع إلى تفاصيل تغطية منصة "خرائط Google" للاطّلاع على التغطية الدولية لواجهة برمجة التطبيقات Directions API.
اتجاهات العرض
إن بدء طلب الاتجاهات إلى
DirectionsService
باستخدام الطريقة route()
يتطلب تمرير استدعاء يتم تنفيذه عند اكتمال
طلب الخدمة. ستعرض معاودة الاتصال هذه رسالة
DirectionsResult
وDirectionsStatus
الرمز في الرد.
حالة طلب البحث عن الاتجاهات
قد تعرض DirectionsStatus
القيم التالية:
- يشير
OK
إلى أنّ الردّ يحتوي على صالحة فيDirectionsResult
. - تشير السمة
NOT_FOUND
إلى سمة واحدة على الأقل من المواقع المحددة في مصدر الطلب أو وجهته أو تعذر ترميز نقاط الطريق جغرافيًا. ZERO_RESULTS
يشير إلى تعذُّر العثور على مسار بين نقطة الانطلاق والوجهة.- يشير
MAX_WAYPOINTS_EXCEEDED
إلى ذلك أيضًا تم توفير العديد من حقولDirectionsWaypoint
فيDirectionsRequest
. انظر القسم أدناه حول حدود نقاط الطرق. - يشير
MAX_ROUTE_LENGTH_EXCEEDED
إلى المسار المطلوب النص طويل جدًا ولا يمكن معالجته. يحدث هذا الخطأ عندما تكون العمليات الأكثر تعقيدًا والاتجاهات. حاول تقليل عدد نقاط الطريق والمنعطفات أو التعليمات. - تشير السمة
INVALID_REQUEST
إلى أنّ الذي تم تقديمDirectionsRequest
فيه غير صالح. الأكثر شيوعًا فإن أسباب رمز الخطأ هذا هي الطلبات المفقودة نقطة الانطلاق أو الوجهة، أو طلب نقل يتضمن نقاطًا على المسار. - تشير القيمة
OVER_QUERY_LIMIT
إلى أنّ صفحة الويب تحتوي على أرسلت عددًا كبيرًا جدًا من الطلبات خلال الفترة الزمنية المسموح بها. - تشير القيمة
REQUEST_DENIED
إلى أنّ صفحة الويب غير مسموح له باستخدام خدمة الاتجاهات. - تشير السمة
UNKNOWN_ERROR
إلى طلب اتجاهات. تعذرت معالجة بسبب خطأ في الخادم. قد يبدأ الطلب وتنجح إذا حاولت مرة أخرى.
يجب عليك التأكد من عرض استعلام الاتجاهات صالحًا النتائج بالتحقق من هذه القيمة قبل معالجة النتيجة.
عرض نتيجة الاتجاهات
يحتوي DirectionsResult
على نتيجة
استعلام الاتجاهات، والذي يمكنك إما التعامل معه بنفسك، أو تمرير
إلى كائن DirectionsRenderer
، والذي يمكنه
تتولى تلقائيًا عرض النتيجة على الخريطة.
لعرض DirectionsResult
باستخدام
DirectionsRenderer
، عليك تنفيذ
التالي:
- أنشئ عنصر
DirectionsRenderer
. - طلب
setMap()
على العارض للربط إلى الخريطة التي تم تمريرها. - عليك طلب الرقم
setDirections()
على العارض، وتمريرDirectionsResult
كما هو موضح أعلاه. ولأنّ برنامج العرض هوMVCObject
، سيتم تلقائيًا اكتشاف أي تغييرات تطرأ على خصائصه وتحديث الخريطة عندما تظهر الاتجاهات المرتبطة بها بتغييره.
يحسب المثال التالي الاتجاهات بين
موقعين على الطريق 66، حيث تقع نقطة الانطلاق والوجهة
يتم ضبطها من خلال السمتَين "start"
و"end"
المحدَّدتَين
القيم في القوائم المنسدلة. DirectionsRenderer
التعامل مع عرض الخطوط المتعددة بين
والمواقع وموضع العلامات في الأصل،
والوجهة وأي نقاط طريق، إن أمكن.
function initMap() { var directionsService = new google.maps.DirectionsService(); var directionsRenderer = new google.maps.DirectionsRenderer(); var chicago = new google.maps.LatLng(41.850033, -87.6500523); var mapOptions = { zoom:7, center: chicago } var map = new google.maps.Map(document.getElementById('map'), mapOptions); directionsRenderer.setMap(map); } function calcRoute() { var start = document.getElementById('start').value; var end = document.getElementById('end').value; var request = { origin: start, destination: end, travelMode: 'DRIVING' }; directionsService.route(request, function(result, status) { if (status == 'OK') { directionsRenderer.setDirections(result); } }); }
في نص HTML:
<div> <strong>Start: </strong> <select id="start" onchange="calcRoute();"> <option value="chicago, il">Chicago</option> <option value="st louis, mo">St Louis</option> <option value="joplin, mo">Joplin, MO</option> <option value="oklahoma city, ok">Oklahoma City</option> <option value="amarillo, tx">Amarillo</option> <option value="gallup, nm">Gallup, NM</option> <option value="flagstaff, az">Flagstaff, AZ</option> <option value="winona, az">Winona</option> <option value="kingman, az">Kingman</option> <option value="barstow, ca">Barstow</option> <option value="san bernardino, ca">San Bernardino</option> <option value="los angeles, ca">Los Angeles</option> </select> <strong>End: </strong> <select id="end" onchange="calcRoute();"> <option value="chicago, il">Chicago</option> <option value="st louis, mo">St Louis</option> <option value="joplin, mo">Joplin, MO</option> <option value="oklahoma city, ok">Oklahoma City</option> <option value="amarillo, tx">Amarillo</option> <option value="gallup, nm">Gallup, NM</option> <option value="flagstaff, az">Flagstaff, AZ</option> <option value="winona, az">Winona</option> <option value="kingman, az">Kingman</option> <option value="barstow, ca">Barstow</option> <option value="san bernardino, ca">San Bernardino</option> <option value="los angeles, ca">Los Angeles</option> </select> </div>
يوضح المثال التالي الاتجاهات باستخدام أنواع وسائل النقل بين هايت-آشبوري وأوشن بيتش سان فرانسيسكو، كاليفورنيا:
function initMap() { var directionsService = new google.maps.DirectionsService(); var directionsRenderer = new google.maps.DirectionsRenderer(); var haight = new google.maps.LatLng(37.7699298, -122.4469157); var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205); var mapOptions = { zoom: 14, center: haight } var map = new google.maps.Map(document.getElementById('map'), mapOptions); directionsRenderer.setMap(map); } function calcRoute() { var selectedMode = document.getElementById('mode').value; var request = { origin: haight, destination: oceanBeach, // Note that JavaScript allows us to access the constant // using square brackets and a string value as its // "property." travelMode: google.maps.TravelMode[selectedMode] }; directionsService.route(request, function(response, status) { if (status == 'OK') { directionsRenderer.setDirections(response); } }); }
في نص HTML:
<div> <strong>Mode of Travel: </strong> <select id="mode" onchange="calcRoute();"> <option value="DRIVING">Driving</option> <option value="WALKING">Walking</option> <option value="BICYCLING">Bicycling</option> <option value="TRANSIT">Transit</option> </select> </div>
لا يعالج DirectionsRenderer
الشاشة فقط
الخطوط المتعددة وأي علامات مرتبطة بها، ولكن يمكنها أيضًا التعامل
العرض النصي للتوجيهات كسلسلة من الخطوات. للقيام بذلك،
لذا، يُرجى الاتصال بـ "setPanel()
" على
DirectionsRenderer
، تمريره
<div>
حيث يتم عرض هذه المعلومات.
وسيؤدي ذلك أيضًا إلى ضمان عرض حقوق الطبع والنشر المناسبة
والمعلومات وأي تحذيرات قد تكون مرتبطة
نتيجته.
سيتم توفير الاتجاهات النصية باستخدام لغة المتصفح
إعداد اللغة المفضلة أو اللغة المحددة عند
تحميل JavaScript لواجهة برمجة التطبيقات باستخدام language
. (لمزيد من المعلومات، راجع
الأقلمة.) في حالة اتجاهات النقل العام، سيتم
المعروضة في المنطقة الزمنية في محطة النقل العام تلك.
يتطابق المثال التالي مع المثال الموضَّح أعلاه،
ولكنه يتضمن لوحة <div>
حيث
عرض الاتجاهات:
function initMap() { var directionsService = new google.maps.DirectionsService(); var directionsRenderer = new google.maps.DirectionsRenderer(); var chicago = new google.maps.LatLng(41.850033, -87.6500523); var mapOptions = { zoom:7, center: chicago } var map = new google.maps.Map(document.getElementById('map'), mapOptions); directionsRenderer.setMap(map); directionsRenderer.setPanel(document.getElementById('directionsPanel')); } function calcRoute() { var start = document.getElementById('start').value; var end = document.getElementById('end').value; var request = { origin:start, destination:end, travelMode: 'DRIVING' }; directionsService.route(request, function(response, status) { if (status == 'OK') { directionsRenderer.setDirections(response); } }); }
في نص HTML:
<div id="map" style="float:left;width:70%;height:100%"></div> <div id="directionsPanel" style="float:right;width:30%;height:100%"></div>
كائن DirectionsResult
عند إرسال طلب اتجاهات إلى
DirectionsService
، يصلك ردّ يتكون من
ورمز الحالة، والنتيجة هي DirectionsResult
الخاص بك. السمة DirectionsResult
هي قيمة حرفية لكائن.
مع الحقول التالية:
- يحتوي
geocoded_waypoints[]
على صفيف منDirectionsGeocodedWaypoint
عنصرًا، يحتوي كل منها على تفاصيل حول الترميز الجغرافي للمصدر والوجهة ونقاط الطريق. - يحتوي
routes[]
على صفيف منDirectionsRoute
عناصر يشير كل مسار إلى طريقة من نقطة الانطلاق إلى الوجهة المحددة فيDirectionsRequest
بشكل عام، هناك مسار واحد فقط لأي طلب معين، ما لم تكن تم ضبط حقلprovideRouteAlternatives
علىtrue
، وفيه قد يتم إرجاع مسارات متعددة.
ملاحظة: تم إيقاف السمة via_waypoint
نهائيًا.
في مسارات بديلة. الإصدار 3.27 هو الإصدار الأخير من واجهة برمجة التطبيقات الذي يضيف المزيد من خلال نقاط الطرق
في مسارات بديلة. بالنسبة إلى الإصدار 3.28 والإصدارات الأحدث من واجهة برمجة التطبيقات، يمكنك مواصلة تنفيذ
الاتجاهات القابلة للسحب باستخدام خدمة الاتجاهات من خلال تعطيل سحب المسارات البديلة.
يجب أن يكون المسار الرئيسي فقط قابلاً للسحب. يمكن للمستخدمين سحب المسار الرئيسي حتى يطابق
مسار بديل.
نقاط الطرق التي تم ترميزها جغرافيًا للاتجاهات
تحتوي السمة DirectionsGeocodedWaypoint
على تفاصيل حول الترميز الجغرافي
نقطة الانطلاق والوجهة ونقاط الطريق.
السمة DirectionsGeocodedWaypoint
هي كائن حرفي مع
الحقول التالية:
- تشير القيمة
geocoder_status
إلى رمز الحالة الناتج من عملية الترميز الجغرافي. قد يحتوي هذا الحقل على القيم التالية:- وتشير السمة
"OK"
إلى عدم حدوث أي أخطاء. تم تحليل العنوان بنجاح وفي وتم عرض رمز جغرافي واحد على الأقل. - تشير القيمة
"ZERO_RESULTS"
إلى أن الترميز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث ذلك إذا تم تمرير برنامج الترميز الجغرافي إلى علامةaddress
غير موجودة.
- وتشير السمة
-
تشير القيمة
partial_match
إلى أن أداة الترميز الجغرافي لم يتم عرضها مطابقة تامة للطلب الأصلي، على الرغم من قدرته على مطابقة جزء من العنوان المطلوب. يمكنك مراجعة الطلب الأصلي بحثًا عن أخطاء إملائية و/أو أو عنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع غير الموجودة داخل المنطقة المحلية التي تم تمريرها في الطلب وقد تكون المطابقات الجزئية أيضًا يتم عرضها عندما يتطابق طلب مع موقعين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، "هيلبار سانت، بريستول، المملكة المتحدة" سيؤدي إلى عرض تطابق جزئي لكليهما "شارع هنري" و"شارع هنريتا". لاحظ أنه إذا تضمن الطلب به خطأ إملائي في مكون العنوان، فقد تقترح خدمة الترميز الجغرافي حلاً بديلاً الخاص بك. سيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة باعتبارها جزئية تطابق.
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
الوقت المحدد كملف JavaScript كائنDate
.text
هو الوقت المحدد كسلسلة. الوقت هو في المنطقة الزمنية لمحطة النقل العام.- يحتوي
time_zone
على المنطقة الزمنية لهذه المحطة. تشير رسالة الأشكال البيانية هي اسم المنطقة الزمنية كما هو موضح في المنطقة الزمنية IANA قاعدة البيانات، على سبيل المثال. "أمريكا/نيويورك".
- يحتوي
departure_time
على الوقت المقدّر للمغادرة هذه الساق، المحددة كجسمTime
. تشير رسالة الأشكال البيانيةdeparture_time
متاح لاتجاهات النقل العام فقط. - يحتوي
start_location
علىLatLng
من أصل هذه الساق. نظرًا لأن تحتسب خدمة الويب الاتجاهات الاتجاهات بين المواقع الجغرافية. باستخدام أقرب خيار نقل (عادةً ما يكون طريقًا) في نقطتَي البداية والنهاية، قد يكونstart_location
عن المصدر المقدم لهذه المرحلة، إذا كان على سبيل المثال، الطريق ليست بالقرب من الأصل. end_location
يحتوي علىLatLng
من وجهة هذه الساق. نظرًا لأن يتم احتساب الاتجاهات بين المواقع الجغرافية من خلالDirectionsService
. باستخدام أقرب خيار نقل (عادةً ما تكون طريقًا) في نقاط البداية والنهاية، فقد يكونend_location
عن الوجهة المقدمة لهذه المرحلة إذا، على سبيل المثال، الطريق ليست قريبة من الوجهة.- يحتوي
start_address
على عنوان يمكن لشخص عادي قراءته (عنوان شارع عادةً) ببداية هذه المرحلة.
من المفترض أن تتم قراءة هذا المحتوى كما هو. لا تقم بالتحليل برمجيًا عنوان منسق. - يحتوي
end_address
على عنوان يمكن لشخص عادي قراءته (عنوان شارع عادةً) في نهاية هذه المرحلة.
من المفترض أن تتم قراءة هذا المحتوى كما هو. لا تقم بالتحليل برمجيًا عنوان منسق.
خطوات الاتجاهات
DirectionsStep
هي أكثر وحدة ذرية في
مسارًا محددًا، ويحتوي على خطوة واحدة تصف مسارًا محددًا
التعليمات حول الرحلة. مثلاً: "انعطاف يسارًا عند W. 4th St. " لم
يصف التعليمات فقط ولكن يحتوي أيضًا على المسافة والمدة
المعلومات المتعلقة بكيفية ارتباط هذه الخطوة بالخطوة التالية.
فعلى سبيل المثال، الخطوة التي يشار إليها بالاختصار "Merge to I-80 West" قد تحتوي على
بمدة "37 ميلاً" و"40 دقيقة" مما يشير إلى أن الخطوة التالية
وهو 37 ميلاً/40 دقيقة من هذه الخطوة.
عند استخدام خدمة الاتجاهات للبحث عن اتجاهات النقل العام،
ستتضمن مصفوفة الخطوات نقل عام
معلومات محدّدة في شكل عنصر transit
في حال حذف
تشتمل الاتجاهات على وسائل نقل متعددة واتجاهات تفصيلية
سيتم توفيره لخطوات المشي أو القيادة في مصفوفة steps[]
.
على سبيل المثال، ستتضمّن خطوة المشي الاتجاهات من البداية والنهاية
المواقع: "المشي إلى جادة إيناس "فيتش سانت". ستشمل هذه الخطوة
اتجاهات المشي التفصيلية لهذا المسار في steps[]
مصفوفة، مثل: "الاتجاه إلى الشمال الغربي" و"الاتجاه يسارًا إلى جبل النيل" و
"الاتجاه يسارًا إلى شارع التحرير".
السمة DirectionsStep
هي كائن حرفي مع
الحقول التالية:
- يحتوي
instructions
على تعليمات لهذه الخطوة. داخل سلسلة نصية. - يحتوي
distance
على المسافة التي تغطيها هذه حتى الخطوة التالية، باعتباره كائنDistance
. (الاطّلاع على الوصف فيDirectionsLeg
أعلاه). قد يكون هذا الحقل غير معروف إذا كانت المسافة غير معروفة. - يحتوي
duration
على تقدير للوقت المطلوب أو تنفيذ الخطوة، حتى الخطوة التالية، كائنDuration
. (يمكنك الاطلاع على الوصف فيDirectionsLeg
above.) قد يكون هذا الحقل غير معروف إذا كانت المدة غير معروفة. - يحتوي
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
الوقت المحدد كملف JavaScript كائنDate
.text
هو الوقت المحدد كسلسلة. الوقت هو في المنطقة الزمنية لمحطة النقل العام.- يحتوي
time_zone
على المنطقة الزمنية لهذه المحطة. تشير رسالة الأشكال البيانية هي اسم المنطقة الزمنية كما هو موضح في المنطقة الزمنية IANA قاعدة البيانات، على سبيل المثال. "أمريكا/نيويورك".
- يحتوي
departure_time
على وقت المغادرة، الذي تم تحديده على أنه كائنTime
. - تحدد السمة
headsign
الاتجاه الذي يجب الانتقال إليه هذا الخط، كما هو موضح على المركبة أو في محطة المغادرة. غالبًا ما تكون هذه هي المحطة النهائية. headway
، عند توفّره، يحدد العدد المتوقع عدد الثواني بين أوقات المغادرة من المحطة نفسها في هذا الوقت. بالنسبة على سبيل المثال، إذا كانت القيمةheadway
تساوي 600، يمكنك توقع عشرة دقيقة من الانتظار إذا كان يجب أن يفوتك الحافلة.- يحتوي
line
علىTransitLine
كائن حرفي يحتوي على معلومات حول خط النقل المستخدم في هذه الخطوة. توفّرTransitLine
اسم وعامل التشغيل الخط، مع الخصائص الأخرى الموضحة فيTransitLine
الوثائق المرجعية. - يحتوي
num_stops
على عدد محطات التوقف في هذه الخطوة. يشمل ذلك محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا تتضمن اتجاهاتك المغادرة من المحطة أ، والمرور بالمحطات ب C، وعند الوصول إلى المحطة D، سيعرضnum_stops
الرقم 3.
خط النقل العام
يعرض الكائن TransitLine
السمات التالية:
- يحتوي
name
على الاسم الكامل لخط النقل العام هذا. مثلاً: " 7 Avenue Express" أو "14th St Crosstown". - يحتوي
short_name
على الاسم المختصر لعملية النقل هذه. الخط. سيكون عادةً رقم سطر، مثل "2" أو "M14". agencies
عبارة عن مصفوفة تحتوي على كائنTransitAgency
. الكائنTransitAgency
إلى معلومات حول مشغل هذا الخط، بما في ذلك السمات التالية:- يحتوي
name
على اسم مؤسسة النقل العام. - يحتوي
phone
على رقم هاتف النقل العام الوكالة. url
يحتوي على عنوان URL التابع لمؤسسة النقل العام.
ملاحظة: في حال عرض اتجاهات النقل العام يدويًا بدلاً من استخدام الكائن
DirectionsRenderer
، يجب عرض أسماء شركات النقل العام التي تقدّم خدمات الرحلة وعناوين URL الخاصة بها نتائجك.- يحتوي
- يحتوي
url
على عنوان URL لخط النقل العام هذا على النحو الذي تم تقديمه بواسطة مؤسسة النقل العام. - يحتوي
icon
على عنوان URL للرمز المرتبط بهذا السطر. ستستخدم معظم المدن رموزًا عامة تختلف حسب نوع المركبة. بعض الإشعارات خطوط النقل العام، مثل نظام مترو الأنفاق في نيويورك، لها أيقونات خاصة هذا الخط. - يحتوي
color
على اللون الشائع استخدامه في اللافتات لهذا الغرض. النقل العام. سيتم تحديد اللون كسلسلة سداسية عشرية، مثل: #FF0033. text_color
يحتوي على لون النص الذي يشيع استخدامه الخاصة بهذا الخط. سيتم تحديد اللون كسلسلة سداسية عشرية.- يحتوي
vehicle
على كائنVehicle
السمات التالية:- يحتوي الحقل "
name
" على اسم المركبة على هذا الخط. مثال: "مترو الأنفاق". - يحتوي
type
على نوع المركبة المستخدمة في هذا الخط. راجِع مستندات نوع المركبة للحصول على القائمة الكاملة للقيم المسموح بها. icon
يحتوي على عنوان URL للرمز المرتبط بشكل شائع مع هذا النوع من المركبات.- يحتوي
local_icon
على عنوان URL للرمز المرتبط مع هذا النوع من المركبات، بناءً على لافتات النقل المحلي.
- يحتوي الحقل "
نوع المركبة
يعرض الكائن VehicleType
ما يلي:
المواقع:
القيمة | التعريف |
---|---|
VehicleType.RAIL |
السكك الحديدية. |
VehicleType.METRO_RAIL |
النقل العام بالقطار الخفيف |
VehicleType.SUBWAY |
قطار خفيف تحت الأرض |
VehicleType.TRAM |
صورة فوق سكة حديدية خفيفة |
VehicleType.MONORAIL |
قطار بخط حديدي واحد |
VehicleType.HEAVY_RAIL |
قطار ثقيل. |
VehicleType.COMMUTER_TRAIN |
قطار سريع. |
VehicleType.HIGH_SPEED_TRAIN |
قطار شديد السرعة |
VehicleType.BUS |
حافلة |
VehicleType.INTERCITY_BUS |
حافلة بين المدن |
VehicleType.TROLLEYBUS |
حافلة ترولي. |
VehicleType.SHARE_TAXI |
سيارة الأجرة المشتركة هي نوع من الحافلات التي تتميز بإمكانية النزول واختيار الركاب في أي مكان على مسارها. |
VehicleType.FERRY |
العبّارة. |
VehicleType.CABLE_CAR |
مركبة تعمل على كابل، عادةً على الأرض كابل جوي
قد تكون السيارات من النوع VehicleType.GONDOLA_LIFT . |
VehicleType.GONDOLA_LIFT |
تلفريك جوي |
VehicleType.FUNICULAR |
مركبة ينحدر لأعلى باستخدام كابل قطار معلّق عادةً ما تتكون من سيارتين، حيث تعمل كل سيارة كوزن عكسي للآخر. |
VehicleType.OTHER |
ستعرض جميع المركبات الأخرى هذا النوع. |
فحص نتائج الاتجاهات
مكوّنات DirectionsResults
—
DirectionsRoute
، DirectionsLeg
،
DirectionsStep
وTransitDetails
— قد يكون
فحصها واستخدامها عند تحليل أي استجابة للاتجاهات.
ملاحظة مهمة: في حال عرض صور النقل العام
الاتجاهات يدويًا بدلاً من استخدام DirectionsRenderer
يجب عرض أسماء مؤسسات النقل العام وعناوين URL الخاصة بها.
لخدمة نتائج الرحلة.
يوضح المثال التالي اتجاهات المشي لسائح معين
المعالم السياحية في مدينة نيويورك. نقوم بفحص إطارات الطريق
DirectionsStep
لإضافة علامات لكل خطوة
إرفاق معلومات بـ InfoWindow
مع تعليمات
ونص هذه الخطوة.
ملاحظة: بما أننا نحسب اتجاهات المشي، سنعرض أيضًا
أي تحذيرات موجَّهة إلى المستخدم في لوحة <div>
منفصلة.
var map; var directionsRenderer; var directionsService; var stepDisplay; var markerArray = []; function initMap() { // Instantiate a directions service. directionsService = new google.maps.DirectionsService(); // Create a map and center it on Manhattan. var manhattan = new google.maps.LatLng(40.7711329, -73.9741874); var mapOptions = { zoom: 13, center: manhattan } map = new google.maps.Map(document.getElementById('map'), mapOptions); // Create a renderer for directions and bind it to the map. var rendererOptions = { map: map } directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions) // Instantiate an info window to hold step text. stepDisplay = new google.maps.InfoWindow(); } function calcRoute() { // First, clear out any existing markerArray // from previous calculations. for (i = 0; i < markerArray.length; i++) { markerArray[i].setMap(null); } // Retrieve the start and end locations and create // a DirectionsRequest using WALKING directions. var start = document.getElementById('start').value; var end = document.getElementById('end').value; var request = { origin: start, destination: end, travelMode: 'WALKING' }; // Route the directions and pass the response to a // function to create markers for each step. directionsService.route(request, function(response, status) { if (status == "OK") { var warnings = document.getElementById("warnings_panel"); warnings.innerHTML = "" + response.routes[0].warnings + ""; directionsRenderer.setDirections(response); showSteps(response); } }); } function showSteps(directionResult) { // For each step, place a marker, and add the text to the marker's // info window. Also attach the marker to an array so we // can keep track of it and remove it when calculating new // routes. var myRoute = directionResult.routes[0].legs[0]; for (var i = 0; i < myRoute.steps.length; i++) { var marker = new google.maps.Marker({ position: myRoute.steps[i].start_point, map: map }); attachInstructionText(marker, myRoute.steps[i].instructions); markerArray[i] = marker; } } function attachInstructionText(marker, text) { google.maps.event.addListener(marker, 'click', function() { stepDisplay.setContent(text); stepDisplay.open(map, marker); }); }
في نص HTML:
<div> <strong>Start: </strong> <select id="start"> <option value="penn station, new york, ny">Penn Station</option> <option value="grand central station, new york, ny">Grand Central Station</option> <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option> <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option> <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option> </select> <strong>End: </strong> <select id="end" onchange="calcRoute();"> <option value="260 Broadway New York NY 10007">City Hall</option> <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option> <option value="moma, New York, NY">MOMA</option> <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option> <option value="253 West 125th Street, New York, NY">Apollo Theatre</option> <option value="1 Wall St, New York, NY">Wall St</option> </select> <div>
استخدام نقاط الطرق في المسارات
كما هو موضّح في DirectionsRequest،
يمكنك أيضًا تحديد نقاط الطريق
(من النوع DirectionsWaypoint
) عند حساب
المسارات التي تستخدم خدمة الاتجاهات للمشي أو ركوب الدراجات أو القيادة
الاتجاهات. لا تتوفّر نقاط الطرق لاتجاهات النقل العام.
تتيح لك نقاط الطرق حساب المسارات عبر مواقع إضافية، في
وهي الحالة التي يمر بها المسار العائد من خلال نقاط الطريق المحددة.
تتألّف waypoint
من الحقول التالية:
location
(مطلوب) يحدد العنوان من النقطة الوسيطة.- وتحدّد السمة
stopover
(اختيارية) ما إذا كان هذا نقطة الطريق هي محطة فعلية على المسار (true
) أو بدلاً من ذلك تفضيل فقط للتوجيه عبر ما هو مُشار إليه الموقع (false
). أوقات التوقف هيtrue
بشكل افتراضي.
بشكل افتراضي، تحتسب خدمة الاتجاهات مسارًا عبر
نقاط الطريق المقدمة بترتيب معين. اختياريًا،
يجوز أن تجتاز optimizeWaypoints: true
في
DirectionsRequest
للسماح لخدمة الاتجاهات
تحسين المسار المقدم عن طريق إعادة ترتيب نقاط الطريق في
طلب أكثر كفاءة. (يعد هذا التحسين تطبيقًا من
مشكلة مندوب مبيعات مسافر). إن وقت السفر هو العامل الأساسي الذي
ولكن تم تحسينه، ولكن تم تحسين عوامل أخرى مثل المسافة وعدد الانعطاف وغير ذلك الكثير
في الاعتبار عند تحديد المسار الأكثر كفاءة. الكل
نقاط التوقف هي نقاط توقف في خدمة الاتجاهات لتحسين
المسار الصحيح.
إذا طلبت من خدمة الاتجاهات تحسين ترتيب
نقاط طريقه، فسيتم إعادة ترتيبه
waypoint_order
داخل العمود
كائن DirectionsResult
.
يحسب المثال التالي المسارات عبر البلاد عبر
الولايات المتحدة باستخدام مجموعة متنوعة من نقاط البداية ونقاط النهاية
ونقاط الطريق. (لتحديد نقاط طريق متعددة، اضغط على
اضغط على Ctrl عند تحديد عناصر داخل القائمة).
يُرجى العلم أنّنا نفحص routes.start_address
.
وroutes.end_address
لتقديم
لنا بالنص الخاص بنقطة بداية ونهاية كل مسار.
TypeScript
function initMap(): void { const directionsService = new google.maps.DirectionsService(); const directionsRenderer = new google.maps.DirectionsRenderer(); const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 6, center: { lat: 41.85, lng: -87.65 }, } ); directionsRenderer.setMap(map); (document.getElementById("submit") as HTMLElement).addEventListener( "click", () => { calculateAndDisplayRoute(directionsService, directionsRenderer); } ); } function calculateAndDisplayRoute( directionsService: google.maps.DirectionsService, directionsRenderer: google.maps.DirectionsRenderer ) { const waypts: google.maps.DirectionsWaypoint[] = []; const checkboxArray = document.getElementById( "waypoints" ) as HTMLSelectElement; for (let i = 0; i < checkboxArray.length; i++) { if (checkboxArray.options[i].selected) { waypts.push({ location: (checkboxArray[i] as HTMLOptionElement).value, stopover: true, }); } } directionsService .route({ origin: (document.getElementById("start") as HTMLInputElement).value, destination: (document.getElementById("end") as HTMLInputElement).value, waypoints: waypts, optimizeWaypoints: true, travelMode: google.maps.TravelMode.DRIVING, }) .then((response) => { directionsRenderer.setDirections(response); const route = response.routes[0]; const summaryPanel = document.getElementById( "directions-panel" ) as HTMLElement; summaryPanel.innerHTML = ""; // For each route, display summary information. for (let i = 0; i < route.legs.length; i++) { const routeSegment = i + 1; summaryPanel.innerHTML += "<b>Route Segment: " + routeSegment + "</b><br>"; summaryPanel.innerHTML += route.legs[i].start_address + " to "; summaryPanel.innerHTML += route.legs[i].end_address + "<br>"; summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>"; } }) .catch((e) => window.alert("Directions request failed due to " + status)); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const directionsService = new google.maps.DirectionsService(); const directionsRenderer = new google.maps.DirectionsRenderer(); const map = new google.maps.Map(document.getElementById("map"), { zoom: 6, center: { lat: 41.85, lng: -87.65 }, }); directionsRenderer.setMap(map); document.getElementById("submit").addEventListener("click", () => { calculateAndDisplayRoute(directionsService, directionsRenderer); }); } function calculateAndDisplayRoute(directionsService, directionsRenderer) { const waypts = []; const checkboxArray = document.getElementById("waypoints"); for (let i = 0; i < checkboxArray.length; i++) { if (checkboxArray.options[i].selected) { waypts.push({ location: checkboxArray[i].value, stopover: true, }); } } directionsService .route({ origin: document.getElementById("start").value, destination: document.getElementById("end").value, waypoints: waypts, optimizeWaypoints: true, travelMode: google.maps.TravelMode.DRIVING, }) .then((response) => { directionsRenderer.setDirections(response); const route = response.routes[0]; const summaryPanel = document.getElementById("directions-panel"); summaryPanel.innerHTML = ""; // For each route, display summary information. for (let i = 0; i < route.legs.length; i++) { const routeSegment = i + 1; summaryPanel.innerHTML += "<b>Route Segment: " + routeSegment + "</b><br>"; summaryPanel.innerHTML += route.legs[i].start_address + " to "; summaryPanel.innerHTML += route.legs[i].end_address + "<br>"; summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>"; } }) .catch((e) => window.alert("Directions request failed due to " + status)); } window.initMap = initMap;
الحدود والقيود المفروضة على نقاط الطرق
تنطبق حدود وقيود الاستخدام التالية:
- الحد الأقصى لعدد نقاط الطريق المسموح بها عند استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط هو 25، بالإضافة إلى المنشأ والوجهة. الحدود هي نفسها واجهة برمجة التطبيقات للاتجاهات خدمة الويب.
- بالنسبة إلى خدمة ويب الاتجاهات، يُسمح للعملاء ونقاط الطريق، بالإضافة إلى الأصل والوجهة.
- يُسمح لعملاء الخطة المميزة في Google Maps Platform بعدد 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;