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

نظرة عامة

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

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

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

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

قبل استخدام خدمة "الاتجاهات" في Maps JavaScript API، عليك أولاً تفعيل واجهة برمجة التطبيقات Directions API في Google Cloud Console الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.

لعرض قائمة بواجهات برمجة التطبيقات المفعّلة:

  1. الانتقال إلى قسم Google Cloud Console:
  2. انقر على الزر اختيار مشروع. ثم اختيار نفس المشروع الذي أعددته Maps JavaScript API وانقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة التطبيقات للاتجاهات:
  4. إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، هذا يعني أنّك جاهز للعمل. إذا لم يتم إدراج واجهة برمجة التطبيقات، تفعيلها:
    1. في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة بدلاً من ذلك، من القائمة الجانبية اليمنى، انقر على المكتبة.
    2. ابحث عن Directions API، ثم اختَرها من قائمة النتائج.
    3. انقر على تفعيل. عند انتهاء العملية، تظهر 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، عليك تنفيذ التالي:

  1. أنشئ عنصر DirectionsRenderer.
  2. طلب setMap() على العارض للربط إلى الخريطة التي تم تمريرها.
  3. عليك طلب الرقم 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;
index.ts

JavaScript

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

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

window.initMap = initMap;
index.js

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

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

  • الحد الأقصى لعدد نقاط الطريق المسموح بها عند استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات 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;
index.ts

JavaScript

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

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

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

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

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

  if (!myroute) {
    return;
  }

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

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

window.initMap = initMap;
index.js
الاطّلاع على مثال

تجربة "عيّنة"