ترقية تطبيق JavaScript API لـ "خرائط Google" من الإصدار 2 إلى الإصدار 3

لم يعُد الإصدار الثاني من "واجهة برمجة تطبيقات JavaScript للخرائط" متاحًا اعتبارًا من 26 أيار (مايو) 2021. ونتيجةً لذلك، ستتوقف خرائط الإصدار 2 على موقعك عن العمل وستعرض أخطاء JavaScript. لمتابعة استخدام الخرائط على موقعك، يجب الانتقال إلى الإصدار الثالث من واجهة برمجة تطبيقات JavaScript للخرائط. سيساعدك هذا الدليل خلال هذه العملية.

نظرة عامة

وستختلف عملية نقل البيانات قليلاً لكل طلب، ولكن هناك بعض الخطوات الشائعة في جميع المشاريع:

1. احصل على مفتاح جديد. تستخدم واجهة برمجة تطبيقات JavaScript للخرائط الآن Google Cloud Console لإدارة المفاتيح. إذا كنت لا تزال تستخدم الإصدار 2، احرص على الحصول على مفتاح واجهة برمجة التطبيقات الجديد قبل بدء عملية نقل البيانات.
2. تعديل نوع بدء تشغيل واجهة برمجة التطبيقات: ستحمّل معظم التطبيقات الإصدار 3 من Maps JavaScript API بالرمز التالي:
   

   <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
   

3. عدِّل الرمز. وسيعتمد حجم التغيير المطلوب بشكل كبير على طلبك. وتشمل التغييرات الشائعة ما يلي:
   • أشِر دائمًا إلى مساحة الاسم في google.maps. وفي الإصدار الثالث، يتم تخزين جميع رموز واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" في مساحة الاسم google.maps.* بدلاً من مساحة الاسم العامة. تمت أيضًا إعادة تسمية معظم العناصر كجزء من هذه العملية. على سبيل المثال، بدلاً من GMap2، ستُحمِّل google.maps.Map الآن.
   • أزِل أي إشارات إلى طرق قديمة. تمت إزالة عدد من طرق الخدمات العامة، مثل GDownloadURL وGLog. يمكنك إمّا استبدال هذه الوظيفة بمكتبات أدوات خارجية أو إزالة هذه المراجع من الرمز.
   • (اختياري) أضِف مكتبات إلى الرمز البرمجي الخاص بك. وقد تم نقل العديد من الميزات إلى مكتبات أدوات مساعدة، وبالتالي لن يحتاج كل تطبيق إلا إلى تحميل أجزاء واجهة برمجة التطبيقات التي سيتم استخدامها.
   • (اختياري) اضبط مشروعك لاستخدام الإعدادات الخارجية للإصدار 3. يمكن استخدام التطبيقات الخارجية المستنِدة إلى إصدار v3 للمساعدة في التحقّق من صحة الرمز باستخدام أداة تجميع بيانات الإغلاق أو لتفعيل ميزة الإكمال التلقائي في بيئة التطوير المتكاملة (IDE). يمكنك الاطّلاع على مزيد من المعلومات حول التجميع المتقدم والإعدادات الخارجية.
4. الاختبار والتكرار: في هذه المرحلة، لا يزال أمامك بعض العمل، ولكن الخبر السار هو أنك ستكون في طريقك نحو تطبيق الخرائط الجديد v3.

تغييرات في الإصدار 3 من Maps JavaScript API

قبل التخطيط لنقل البيانات، من المفترض أن تخصّص بعض الوقت لفهم الاختلافات بين الإصدار 2 من Maps JavaScript API والإصدار 3 من Maps JavaScript API. تمت صياغة أحدث إصدار من Maps JavaScript API من البداية، مع التركيز على أساليب برمجة JavaScript الحديثة وزيادة استخدام المكتبات وواجهة برمجة تطبيقات مبسّطة. تمت إضافة العديد من الميزات الجديدة إلى واجهة برمجة التطبيقات، وقد تم تغيير العديد من الميزات المألوفة أو حتى إزالة هذه الميزات. يسلّط هذا القسم الضوء على بعض الاختلافات الرئيسية بين الإصدارَين.

تتضمن بعض التغييرات في v3 API ما يلي:

• مكتبة أساسية انسيابية. وقد تم نقل العديد من الدوال التكميلية إلى المكتبات، ما يساعد على تقليل أوقات التحميل والتحليل لواجهة برمجة التطبيقات الأساسية، ما يتيح تحميل الخريطة بسرعة على أي جهاز.
• تم تحسين أداء العديد من الميزات، مثل عرض المضلّع وموضع العلامة.
• أسلوب جديد لحدود الاستخدام من جهة العميل لاستيعاب العناوين المشتركة التي تستخدمها الخوادم الوكيلة للأجهزة الجوّالة وجدران الحماية التابعة للشركات بشكل أفضل.
• تمت إضافة دعم للعديد من المتصفحات الحديثة والمتصفحات المتوافقة مع الأجهزة الجوّالة. تم إلغاء إمكانية استخدام Internet Explorer 6.
• تمت إزالة العديد من فئات المساعدة للأغراض العامة ( GLog أو GDownloadUrl). في الوقت الحالي، تتوفر العديد من مكتبات JavaScript الممتازة التي توفر وظائف مشابهة، مثل الإغلاق أو jQuery.
• تطبيق محتوى "التجوّل الافتراضي" بتنسيق HTML5 الذي سيتم تحميله على أي جهاز جوّال
• صور بانورامية مخصّصة لميزة "التجوّل الافتراضي" مع صورك الخاصة، ما يتيح لك مشاركة الصور البانورامية على منحدرات التزلج أو المنازل المعروضة للبيع أو غيرها من الأماكن المثيرة للاهتمام.
• عمليات تخصيص خرائط ذات نمط تتيح لك تغيير طريقة عرض العناصر على الخريطة الأساسية لتتوافق مع نمطك المرئي الفريد.
• إتاحة العديد من الخدمات الجديدة، مثل ElevationService ومصفوفة المسافة:
• من خلال خدمات الاتجاهات المحسّنة، تتوفّر مسارات بديلة وتحسين المسارات (حلول تقريبية لمشكلة مندوب مبيعات مسافر) واتجاهات ركوب الدراجات (مع طبقة ركوب الدراجات) واتجاهات النقل العام و الاتجاهات القابلة للسحب.
• هو تنسيق معدَّل للترميز الجغرافي يوفّر معلومات عن type أكثر دقة من القيمة accuracy التي يوفّرها الإصدار 2 من Geocoding API.
• دعم عدة نوافذ معلومات على خريطة واحدة

ترقية التطبيق

مفتاحك الجديد

يستخدم الإصدار 3 من Maps JavaScript API نظامًا جديدًا للمفاتيح من الإصدار 2. من المحتمل أنّك تستخدم مفتاح الإصدار 3 مع تطبيقك، وفي هذه الحالة لا يلزم إجراء أي تغيير. للتحقّق من ذلك، تحقَّق من عنوان URL الذي ستحمِّل منه واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" للمَعلمة key. إذا كانت قيمة المفتاح تبدأ بـ "ABQIAA"، يعني ذلك أنّك تستخدم مفتاح الإصدار 2. إذا كان لديك مفتاح الإصدار 2، يجب الترقية إلى مفتاح الإصدار 3 كجزء من عملية نقل البيانات، وسيؤدي هذا الإجراء إلى:

• السماح لك بمراقبة استخدام واجهة برمجة التطبيقات في Google Cloud Console
• تسمح لك بشراء حصة إضافية عند الحاجة.
• امنح Google طريقة للتواصل معك بشأن طلبك.

يتم تمرير المفتاح عند تحميل الإصدار 3 من Maps JavaScript API. تعرَّف على المزيد من المعلومات حول إنشاء مفاتيح واجهة برمجة التطبيقات.

تجدر الإشارة إلى أنّك إذا كنت أحد عملاء واجهات برمجة التطبيقات Google Maps API for Work، قد يعني ذلك أنّك تستخدم معرِّف عميل مع المعلَمة client بدلاً من استخدام المعلَمة key. لا تزال معرّفات العملاء متاحة في الإصدار 3 من Maps JavaScript API ولا تحتاج إلى إجراء عملية ترقية المفتاح.

تحميل واجهة برمجة التطبيقات

يتضمّن التعديل الأول الذي عليك إجراؤه على الرمز طريقة تحميل واجهة برمجة التطبيقات. في الإصدار الثاني، يتم تحميل Maps JavaScript API من خلال طلب إلى http://maps.google.com/maps. في حال تحميل الإصدار 3 من Maps JavaScript API، عليك إجراء التغييرات التالية:

1. تحميل واجهة برمجة التطبيقات من //maps.googleapis.com/maps/api/js
2. أزِل المَعلمة file.
3. عدِّل المَعلمة key باستخدام مفتاح الإصدار 3 الجديد. يجب على عملاء واجهات برمجة التطبيقات Google Maps API for Work استخدام معلَمة client.
4. (الخطة المميّزة في "منصة خرائط Google" فقط) تأكَّد من تقديم المَعلمة client كما هو موضّح في دليل مطوّري الخطة المميّزة في "منصة خرائط Google".
5. أزِل المعلَمة v لطلب أحدث إصدار تم طرحه أو غيِّر قيمتها وفقًا لمخطط تحديد الإصدارات v3.
6. (اختياري) استبدِل المَعلمة hl بالسمة language مع الاحتفاظ بقيمتها.
7. (اختياري) أضِف مَعلمة libraries لتحميل مكتبات اختيارية.

في أبسط الحالات، سيحدّد التمهيد v3 معلمة مفتاح واجهة برمجة التطبيقات فقط:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

يطلب المثال التالي أحدث إصدار من Maps JavaScript API، الإصدار 2 باللغة الألمانية:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

المثال أدناه هو طلب مكافئ للإصدار 3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

إضافة مساحة الاسم google.maps

إنّ التغيير الأبرز على الأرجح في الإصدار الثالث من واجهة برمجة تطبيقات JavaScript للخرائط هو إطلاق مساحة الاسم google.maps. تضع واجهة برمجة التطبيقات v2 جميع العناصر في مساحة الاسم العالمية تلقائيًا، ما قد يؤدي إلى تضارب في التسمية. وفي الإصدار 3، تتوفّر جميع العناصر ضمن مساحة الاسم google.maps.

عند نقل تطبيقك إلى الإصدار 3، يجب تغيير الرمز للاستفادة من مساحة الاسم الجديدة. ولسوء الحظ، لن ينجح البحث عن "G" واستبداله بـ "google.maps."، ولكنّها قاعدة مجربة جيّدة يجب تطبيقها عند مراجعة الرمز البرمجي. في ما يلي بعض الأمثلة على الفئات المكافئة في الإصدارين 2 و3.

v2	v3
GMap2	google.maps.Map
GLatLng	google.maps.LatLng
GInfoWindow	google.maps.InfoWindow
GMapOptions	google.map.MapOptions
G_API_VERSION	google.maps.version
GPolyStyleOptions	google.maps.PolygonOptions or google.maps.PolylineOptions

إزالة الرمز القديم

يتضمّن الإصدار الثالث من "واجهة برمجة تطبيقات JavaScript للخرائط" أوجه تشابه مع معظم الوظائف المتوفّرة في الإصدار 2، إلا أنّ هناك بعض الفئات التي لم تعُد متوافقة. كجزء من عملية نقل البيانات، يجب استبدال هذه الفئات بمكتبات أدوات مساعدة تابعة لجهات خارجية أو إزالة هذه المراجع من الرمز. تتوفر العديد من مكتبات JavaScript الممتازة التي توفّر وظائف مشابهة، مثل الإغلاق أو jQuery.

الفئات التالية ليس لها أي توازي في الإصدار 3 من Maps JavaScript API:

GBounds	GLanguage
GBrowserIsCompatible	GLayer
GControl	GLog
GControlAnchor	GMercatorProjection
GControlImpl	GNavLabelControl
GControlPosition	GObliqueMercator
GCopyright	GOverlay
GCopyrightCollection	GPhotoSpec
GDownloadUrl	GPolyEditingOptions
GDraggableObject	GScreenOverlay
GDraggableObjectOptions	GStreetviewFeatures
GFactualGeocodeCache	GStreetviewLocation
GGeoAddressAccuracy	GStreetviewOverlay
GGeocodeCache	GStreetviewUserPhotosOptions
GGoogleBar	GTileLayerOptions
GGoogleBarAdsOptions	GTileLayerOverlayOptions
GGoogleBarLinkTarget	GTrafficOverlayOptions
GGoogleBarListingTypes	GUnload
GGoogleBarOptions	GXml
GGoogleBarResultList	GXmlHttp
GInfoWindowTab	GXslt
GKeyboardHandler

رمز المقارنة

لنقارن بين تطبيقَين بسيطَين إلى حد ما من التطبيقات التي تمّت كتابتها باستخدام الإصدارَين 2 و3 من واجهات برمجة التطبيقات.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

كما ترى، هناك عدة اختلافات بين التطبيقَين. تشمل التغييرات البارزة ما يلي:

• تم تغيير العنوان الذي تم تحميل واجهة برمجة التطبيقات منه.
• لم تعُد الطريقتان GBrowserIsCompatible() وGUnload() مطلوبتَين في الإصدار 3، وتمت إزالتهما من واجهة برمجة التطبيقات.
• يتم استبدال الكائن GMap2 بـ google.maps.Map باعتباره الكائن المركزي في واجهة برمجة التطبيقات.
• يتم الآن تحميل المواقع من خلال فئات "الخيارات". في المثال أعلاه، نضبط السمات الثلاث المطلوبة لتحميل خريطة، وهي center وzoom وmapTypeId، عبر كائن MapOptions مضمّن.
• يتم تشغيل واجهة المستخدم الافتراضية افتراضيًا في الإصدار 3. يمكنك إيقاف هذه الميزة عن طريق ضبط السمة disableDefaultUI على "صحيح" في الكائن MapOptions.

ملخّص

في هذه المرحلة، تعرّفت على بعض النقاط الرئيسية التي تتعلّق بعملية نقل البيانات من الإصدار 2 إلى الإصدار 3 من Maps JavaScript API. هناك المزيد من المعلومات التي قد تحتاج إلى معرفتها، ولكن ذلك يعتمد على طلبك. وقد أدرجنا في الأقسام التالية تعليمات حول نقل البيانات للحالات المحددة التي قد تواجهها. بالإضافة إلى ذلك، هناك العديد من المراجع التي قد تكون مفيدة لك خلال عملية الترقية.

• إنّ الإصدار الثالث من "واجهة برمجة تطبيقات JavaScript للخرائط" هو مستندات المطوّرين الأفضل لمعرفة المزيد من المعلومات عن واجهة برمجة التطبيقات وآلية عملها.
• سيساعدك مرجع واجهة برمجة تطبيقات JavaScript للخرائط على معرفة المزيد من المعلومات حول الفئات والطرق الجديدة في v3 API.
• يُعد منتدى Stack Overflow مكانًا رائعًا لطرح الأسئلة المتعلقة بالتعليمات البرمجية. على الموقع الإلكتروني، تستخدم الأسئلة والإجابات المتعلقة بـ Maps JavaScript API علامات google-maps أو google-maps-api-3.
• ننصح عملاء الخطة المميّزة في "منصة خرائط Google" بالاطّلاع على مستندات الخطة المميّزة في "منصة خرائط Google".
• تشكّل مدوّنة مطوّري Google Geo Developers طريقة رائعة للتعرّف على آخر التغييرات التي طرأت على واجهة برمجة التطبيقات.

إذا كانت لديك أي مشاكل أو أسئلة حول هذه المقالة، يُرجى استخدام الرابط إرسال ملاحظات في أعلى هذه الصفحة.

مرجع تفصيلي

يقدّم هذا القسم مقارنة مفصّلة بين الميزات الأكثر شيوعًا لكلٍّ من الإصدارَين 2 و3 من Maps JavaScript API. تم تصميم كل قسم من المرجع بحيث تتم قراءته على حدة. ننصحك بعدم قراءة هذا المرجع كاملاً، بل استخدام هذه المواد للمساعدة في نقل البيانات على أساس كل حالة على حدة.

• الأحداث - تسجيل الأحداث ومعالجتها
• عناصر التحكم - التلاعب بعناصر التحكم في التنقل التي تظهر على الخريطة.
• تراكبات - إضافة عناصر وتعديلها على الخريطة.
• أنواع الخرائط - الفئات التي تشكل الخريطة الأساسية.
• الطبقات: إضافة المحتوى وتعديله كمجموعة، مثل KML أو طبقات حركة المرور
• الخدمات: العمل مع خدمات "التجوّل الافتراضي" أو ميزة الترميز الجغرافي أو الاتجاهات أو خدمات "التجوّل الافتراضي" من Google

فعاليات

يتشابه نموذج الأحداث في الإصدار 3 من Maps JavaScript API مع النموذج المستخدَم في الإصدار 2، على الرغم من أنّ الكثير من التغييرات قد تغيّرت.

حدث جديد لدعم العملاء الأكثر قيمة

تُضيف واجهة برمجة التطبيقات v3 API نوعًا جديدًا من الأحداث لإظهار تغييرات حالة MVC. يتوفّر الآن نوعان من الفعاليات:

• يتم نشر أحداث المستخدمين (مثل أحداث الماوس "النقر") من DOM إلى Maps JavaScript API. وتكون هذه الأحداث منفصلة ومختلفة عن أحداث DOM العادية.
• تعكس إشعارات تغيير حالة MVC التغييرات في عناصر واجهة برمجة التطبيقات Maps API، وتتم تسميتها باستخدام اصطلاح property_changed.

يصدِّر كل عنصر في Maps API عددًا من الأحداث المسماة. وعلى التطبيقات المهتمة بفعاليات معيّنة أن تسجّل أدوات معالجة الأحداث لتلك الفعاليات وتنفّذ رموزًا برمجية عند تلقّيها. وهذه الآلية المستندة إلى الحدث هي نفسها في كل من الإصدار 2 و3 من Maps JavaScript API، باستثناء تغيير مساحة الاسم من GEvent إلى google.maps.event:

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

إزالة أدوات معالجة الأحداث

لأسباب تتعلّق بالأداء، من الأفضل إزالة أداة معالجة الحدث عندما لا تكون هناك حاجة إليه. تؤدي إزالة أداة معالجة الأحداث بالطريقة نفسها في الإصدارَين 2 و3:

1. عند إنشاء أداة معالجة أحداث، يتم عرض كائن مبهم (GEventListener في الإصدار 2، وMapsEventListener في v3).
2. عندما تريد إزالة أداة معالجة الحدث، مرِّر هذا العنصر إلى طريقة removeListener() (GEvent.removeListener() في الإصدار 2 أو google.maps.event.removeListener() في الإصدار 3) لإزالة أداة معالجة الحدث.

الاستماع إلى أحداث DOM

إذا كنت تريد تسجيل أحداث DOM (نموذج كائن المستند) والاستجابة لها، يوفّر الإصدار 3 طريقة google.maps.event.addDomListener() الثابتة، ما يعادل طريقة GEvent.addDomListener() في الإصدار 2.

استخدام الوسيطات التي تم اجتيازها في الأحداث

تمرر أحداث واجهة المستخدم غالبًا وسيطة الحدث التي يمكن الوصول إليها بعد ذلك بواسطة أداة معالجة الحدث. تم تبسيط معظم وسيطات الأحداث في الإصدار 3 لتكون أكثر اتساقًا على العناصر في واجهة برمجة التطبيقات. (راجِع مرجع الإصدار 3 للحصول على التفاصيل).

ما مِن وسيطة overlay متاحة في أدوات معالجة الأحداث في الإصدار 3. في حال سجّلت حدث click على خريطة الإصدار 3، لن يتم معاودة الاتصال إلا عندما ينقر المستخدم على الخريطة الأساسية. يمكنك تسجيل عمليات معاودة الاتصال في العناصر المركّبة القابلة للنقر إذا كنت بحاجة إلى التفاعل مع هذه النقرات.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

عناصر التحكّم

تعرض واجهة برمجة تطبيقات JavaScript للخرائط عناصر تحكم في واجهة المستخدم تسمح للمستخدمين بالتفاعل مع خريطتك. يمكنك استخدام واجهة برمجة التطبيقات لتخصيص طريقة ظهور عناصر التحكّم هذه.

التغييرات في أنواع التحكّم

تم إجراء بعض التغييرات على أنواع control من خلال واجهة برمجة التطبيقات v3 API.

1. تتيح واجهة برمجة التطبيقات v3 API إضافة المزيد من أنواع الخرائط، بما في ذلك خرائط التضاريس وإمكانية إضافة أنواع خرائط مخصّصة.
2. لم يعُد الإصدار الثاني من التحكّم الهرمي GHierarchicalMapTypeControl متاحًا. يمكنك تحقيق تأثير مشابه باستخدام عنصر التحكّم google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. لا يتوفّر التنسيق الأفقي المقدَّم من GMapTypeControl في الإصدار 2 في الإصدار 3.

إضافة عناصر تحكُّم إلى الخريطة

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

• أزرار تتيح للمستخدم التبديل بين أنواع الخرائط المتاحة
• مقياس خريطة

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

عناصر التحكم في تحديد الموضع على الخريطة

طرأ تغيير كبير على عناصر التحكم في تحديد الموضع في الإصدار 3. في الإصدار 2، تستخدم الطريقة addControl() معلَمة ثانية اختيارية تتيح لك تحديد موضع عنصر التحكّم بالنسبة إلى زوايا الخريطة.

في الإصدار 3، يمكنك تحديد موضع عنصر تحكّم من خلال السمة position في خيارات عنصر التحكّم. وتجدر الإشارة إلى أنّ تحديد موضع عناصر التحكّم هذه ليس أمرًا مطلقًا، وبدلاً من ذلك، ستعمل واجهة برمجة التطبيقات على تنسيق عناصر التحكّم بشكل ذكي من خلال "تدفقها" حول عناصر الخريطة الحالية ضمن حدود معيّنة (مثل حجم الخريطة). يضمن ذلك توافق عناصر التحكّم التلقائية مع عناصر التحكّم. راجع التحكّم في تحديد الموضع في الإصدار 3 للحصول على مزيد من المعلومات.

تعمل التعليمة البرمجية التالية على تغيير موضع عناصر التحكم من النماذج أعلاه:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

عناصر التحكّم المخصَّصة

تتيح لك واجهة برمجة تطبيقات JavaScript للخرائط إنشاء عناصر تحكم مخصصة في التنقل. لتخصيص عناصر التحكّم باستخدام واجهة برمجة التطبيقات v2، يمكنك إنشاء فئة فرعية للفئة GControl وتحديد معالِجات للطريقتَين initialize() وgetDefaultPosition(). لا يتوفّر أي ما يعادله للفئة GControl في الإصدار 3. بدلاً من ذلك، يتم تمثيل عناصر التحكّم على أنّها عناصر DOM. لإضافة عنصر تحكّم مخصّص باستخدام واجهة برمجة التطبيقات v3 API، أنشِئ بنية DOM لعنصر التحكّم في أداة الإنشاء في صورة عنصر ثانوي لـ Node (مثل عنصر <div>) وأضِف أدوات معالجة الأحداث لمعالجة أي أحداث DOM. ادفَع Node إلى مصفوفة controls[position] الخاصة بالخرائط لإضافة مثيل من عنصر التحكّم المخصّص إلى خريطتك.

بما أنّ عملية تنفيذ فئة HomeControl تتقيّد بمتطلبات الواجهة المذكورة أعلاه (راجِع مستند عناصر التحكّم المخصّصة لمعرفة التفاصيل)، تعرض نماذج الرموز التالية كيفية إضافة عنصر تحكّم مخصّص إلى خريطة.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

تراكبات

تعكس التراكبات الكائنات التي "تضيفها" إلى الخريطة لتحديد النقاط أو الخطوط أو المناطق أو مجموعات العناصر.

إضافة الطبقات وإزالتها

وتُعدّ أنواع العناصر التي يمثّلها "تراكب" هي نفسها أنواع العناصر في الإصدارَين 2 و3، ولكن يتم التعامل معها بشكل مختلف.

تمت إضافة تراكبات إلى الخريطة، الإصدار 2، وإزالتها من الخريطة باستخدام طريقتَي addOverlay() وremoveOverlay() للكائن GMap2. في الإصدار 3، يمكنك تحديد خريطة لتراكب باستخدام السمة map لفئة خيارات التراكب المرتبطة. يمكنك أيضًا إضافة متراكب أو إزالته مباشرةً من خلال استدعاء طريقة setMap() لكائن التراكب، وتحديد الخريطة المطلوبة. يؤدي ضبط خاصية الخريطة على null إلى إزالة التراكب.

لا تتوفّر طريقة clearOverlays() في الإصدار 3. إذا كنت تريد إدارة مجموعة من التراكبات، عليك إنشاء مصفوفة للاحتفاظ بها. باستخدام هذه المصفوفة، يمكنك بعد ذلك استدعاء دالة setMap() على كل تراكب في المصفوفة (مع ضبط null إذا كنت بحاجة إلى إزالتها).

علامات قابلة للسحب

بشكل تلقائي، تكون العلامات قابلة للنقر، ولكن لا يمكن سحبها. تضيف النموذجان التاليان علامة قابلة للسحب:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

الرموز

يمكنك تحديد رمز مخصص لعرضه بدلاً من المحدد الافتراضي. لاستخدام صورة مخصّصة في الإصدار 2، يمكنك إنشاء مثيل GIcon من G_DEFAULT_ICON type وتعديله. إذا كانت صورتك أكبر أو أصغر من الرمز التلقائي، يجب تحديدها باستخدام مثيل GSize. تبسّط واجهة برمجة التطبيقات v3 هذه العملية بعض الشيء. ما عليك سوى ضبط السمة icon للعلامة على عنوان URL للصورة المخصّصة، وستتولى واجهة برمجة التطبيقات تحديد حجم الرمز تلقائيًا.

توفر واجهة برمجة تطبيقات JavaScript للخرائط دعمًا للرموز المعقدة. قد يشتمل الرمز المعقد على عدة مربّعات أو أشكال معقدة أو يحدد "ترتيب التكدس" لكيفية عرض الصور بالنسبة إلى العناصر المركّبة الأخرى. لإضافة شكل إلى علامة في الإصدار 2، عليك تحديد سمة إضافية في كل مثيل GIcon وتمريرها كخيار إلى الدالة الإنشائية GMarker. في الإصدار 3، يجب أن تضبط الرموز المحدّدة بهذه الطريقة سمات icon الخاصة بها على كائن من النوع Icon. لا يمكن استخدام ظلال العلامات في الإصدار 3.

تعرض الأمثلة التالية علم شاطئ على شاطئ "بوندي" في أستراليا، مع الجزء الشفاف من الرمز غير قابل للنقر عليه:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

var map = new google.maps.Map(
  document.getElementById('map'), {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

الخطوط المتعددة

يتألف الخط المتعدد من مصفوفة من LatLng، بالإضافة إلى سلسلة من مقاطع الخطوط التي تربط تلك المواقع الجغرافية بتسلسل مرتّب. إنّ إنشاء عنصر Polyline وعرضه في الإصدار 3 مماثل لاستخدام كائن GPolyline في الإصدار 2. ترسم النماذج التالية خطوطًا جيوديسية شبه شفافة، بعرض 3 بكسل، من زيورخ إلى سيدني عبر سنغافورة:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

الخطوط المتعددة المشفّرة

لا يتوفر دعم في الإصدار 3 لإنشاء عناصر Polyline مباشرةً من الخطوط المتعددة المرمّزة. بدلاً من ذلك، توفّر مكتبة Geometry Library طرقًا لترميز الخطوط المتعددة وفك ترميزها. اطّلع على المكتبات في الإصدار الثالث من واجهة برمجة التطبيقات Maps API للحصول على مزيد من المعلومات حول كيفية تحميل هذه المكتبة.

ترسم الأمثلة أدناه سلسلة الخطوط المتعددة المرمّزة نفسها، ويستخدم رمز الإصدار 3 طريقة decodePath() من مساحة الاسم google.maps.geometry.encoding.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

مضلعات

يحدد المضلّع المنطقة داخل حلقة مغلقة. على غرار الكائن Polyline، تتكوّن كائنات Polygon من سلسلة من النقاط بتسلسل مرتّب. تتطابق فئة Polygon المستنِدة إلى إصدار v3 إلى حدّ كبير مع الفئة GPolygon من النوع v2، باستثناء الفئة الرئيسية، وهي أنّه لم تعُد مضطرًا لتكرار رأس البداية في نهاية المسار لإغلاق حلقة التكرار. وستغلق واجهة برمجة التطبيقات v3 أي مضلّعات تلقائيًا من خلال رسم خط يربط آخر إحداثي بالإحداثي الأول. وتُنشئ مقتطفات الرمز التالية مضلّعًا يمثّل مثلث برمودا:

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

أشكال قابلة للتعديل بواسطة المستخدم

يمكن جعل الخطوط المتعددة والمضلعات قابلة للتعديل من خلال المستخدم. مقتطفات الرمز البرمجي التالية مكافئة:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

للحصول على إمكانيات رسم أكثر تقدمًا، يمكنك الاطّلاع على مكتبة الرسومات في مستندات الإصدار 3.

نوافذ المعلومات

يعرض عنصر InfoWindow المحتوى في نافذة عائمة أعلى الخريطة. هناك بعض الاختلافات الرئيسية بين الإصدارَين 2 و3 من نافذتَي المعلومات:

• تتيح واجهة برمجة التطبيقات v2 API استخدام GInfoWindow لكل خريطة، في حين تتوافق واجهة برمجة التطبيقات v3 مع عدة رموز InfoWindow متزامنة على كل خريطة.
• سيظل الإصدار 3 InfoWindow مفتوحًا عند النقر على الخريطة. يتم إغلاق الإصدار 2 GInfoWindow تلقائيًا عند النقر على الخريطة. يمكنك محاكاة سلوك الإصدار 2 من خلال إضافة أداة معالجة click على الكائن Map.
• لا توفّر واجهة برمجة التطبيقات v3 توافقًا أصليًا مع InfoWindow المبوَّب.

تراكبات الأرض

لوضع صورة على الخريطة، يجب استخدام الكائن GroundOverlay. بنية GroundOverlay هي نفسها في الأساس في الإصدارَين 2 و3، إذ تحدّد عنوان URL للصورة وحدود الصورة كمعلَمات.

يظهر في المثال التالي خريطة قديمة لمدينة نيوآرك بولاية نيو جيرسي على الخريطة على شكل طبقة:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

أنواع الخرائط

تختلف أنواع الخرائط المتوفرة في الإصدارين 2 و3 قليلاً، لكن جميع أنواع الخرائط الأساسية متوفرة في كلا الإصدارين من واجهة برمجة التطبيقات. بشكل افتراضي، يستخدم الإصدار 2 مربعات خرائط الطريق القياسية "المرسومة". ومع ذلك، يتطلب الإصدار 3 تحديد نوع خريطة معين عند إنشاء كائن google.maps.Map.

أنواع الخرائط الشائعة

تتوفر أنواع الخرائط الأربعة الأساسية في كل من الإصدارين 2 و3:

• تعرض دالة MapTypeId.ROADMAP (تحل محل G_NORMAL_MAP) عرض خريطة الطريق.
• تعرض ميزة MapTypeId.SATELLITE (تحل محل G_SATELLITE_MAP) صور القمر الصناعي على Google Earth.
• تعرض ميزة MapTypeId.HYBRID (تحل محل G_HYBRID_MAP) مزيجًا من طرق العرض العادية وعروض القمر الصناعي.
• تعرض دالة MapTypeId.TERRAIN (تحل محل G_PHYSICAL_MAP) خريطة مادية استنادًا إلى معلومات التضاريس.

وفي ما يلي مثال على إعداد الإصدارين 2 و3 للخريطة لعرض التضاريس:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

أجرى الإصدار 3 من Maps JavaScript API بعض التغييرات على أنواع الخرائط الأقل شيوعًا أيضًا:

• لا تتوفّر مربّعات الخرائط للأجسام السماوية بخلاف الأرض كأنواع خرائط في الإصدار 3 API، ولكن يمكن الوصول إليها كأنواع خرائط مخصّصة كما هو موضّح في هذا المثال.
• ما مِن نوع خريطة خاص في الإصدار 3 يحلّ محلّ النوع G_SATELLITE_3D_MAP من الإصدار 2. يمكنك بدلاً من ذلك دمج مكوّن Google Earth الإضافي في خرائط الإصدار 3 باستخدام هذه المكتبة.

الحد الأقصى من صور التكبير أو التصغير

لا تتوفر صور القمر الصناعي دائمًا بمستويات تكبير/تصغير عالية. إذا كنت تريد معرفة أعلى مستوى متوفّر للتكبير/التصغير قبل ضبط مستوى التكبير/التصغير، استخدِم الفئة google.maps.MaxZoomService. وتحلّ هذه الفئة محلّ طريقة GMapType.getMaxZoomAtLatLng() من الإصدار 2.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

صور جوّية

عند تفعيل الصور الجوية في الإصدار 3، تكون عناصر التحكّم مشابهة لعنصر التحكّم في الإصدار 2 من GLargeZoomControl3D، مع عنصر تحكّم بيني إضافي في "التدوير" للتدوير حسب الاتجاهات المتوافقة.

يمكنك تتبّع المدن التي تتوفّر فيها حاليًا صور بزاوية 45 درجة على هذه الخريطة. عند توفّر صور بزاوية 45 درجة، تتم إضافة خيار قائمة فرعية إلى زر القمر الصناعي في واجهة برمجة تطبيقات الخرائط.

الطبقات

الطبقات هي كائنات على الخريطة تتكوّن من طبق واحد أو أكثر. ويمكن معالجتها باعتبارها وحدة واحدة وتعكس بشكل عام مجموعات من العناصر.

الطبقات المتوافقة

تتيح واجهة برمجة التطبيقات v3 API إمكانية الوصول إلى عدة طبقات مختلفة. تتداخل هذه الطبقات مع فئة GLayer من الإصدار 2 في المناطق التالية:

• يعرض الكائن KmlLayer عناصر KML وGeoRSS في طبقات الإصدار 3، ما يعادل طبقة الإصدار v2 GeoXml.
• يعرض الكائن TrafficLayer طبقة تصوّر أحوال حركة المرور، تشبه تراكب GTrafficOverlay من الإصدار 2.

تختلف هذه الطبقات عن الإصدار 2. وقد تم توضيح الاختلافات في ما يلي. يمكن إضافة هذه العناصر إلى خريطة من خلال استدعاء السمة setMap()، من خلال تمريرها بالكائن Map الذي سيتم عرض الطبقة عليه.

يتوفّر مزيد من المعلومات حول الطبقات المتوافقة في مستندات الطبقات.

طبقات KML وGeoRSS

تتوافق واجهة برمجة تطبيقات JavaScript للخرائط مع تنسيقات البيانات KML وGeoRSS لعرض المعلومات الجغرافية. ويجب أن تكون ملفات KML أو GeoRSS متاحة للجميع إذا أردت تضمينها في خريطة. وفي الإصدار الثالث، يتم عرض تنسيقات البيانات هذه باستخدام مثيل KmlLayer الذي يحلّ محلّ الكائن GGeoXml من الإصدار 2.

تتميّز واجهة برمجة التطبيقات v3 API بمرونة أكبر عند عرض ملف KML، ما يتيح لك إيقاف InfoWindows وتعديل استجابة النقر. يمكنك الاطّلاع على مستندات الإصدار الثالث من طبقات KML وGeoRSS للحصول على المزيد من التفاصيل.

عند عرض KmlLayer، يتم تطبيق قيود على الحجم والتعقيد. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات KmlLayer.

تقارن النماذج التالية طريقة تحميل ملف KML.

geoXml = new GGeoXml(
  'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml');

map.addOverlay(geoXml);

var layer = new google.maps.KmlLayer(
  'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml', {
    preserveViewport: true
});
layer.setMap(map);

طبقة حركة المرور

يتيح لك الإصدار v3 إضافة معلومات عن حركة المرور في الوقت الفعلي (عند توفّرها) إلى خرائطك باستخدام الكائن TrafficLayer. يتم توفير معلومات حركة المرور في وقت تقديم الطلب. تعرض هذه الأمثلة معلومات حركة المرور في مدينة لوس أنجلوس:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(34.0492459, -118.241043), 13);
map.setUIToDefault();

var trafficOptions = {incidents:false};
trafficInfo = new GTrafficOverlay(trafficOptions);
map.addOverlay(trafficInfo);

var map = new google.maps.Map(
    document.getElementById('map'), {
  center: new google.maps.LatLng(34.0492459, -118.241043),
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  zoom: 13
});

var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);

على عكس الإصدار 2، لا تتوفّر خيارات للدالة الإنشائية TrafficLayer في الإصدار 3. لا تتوفّر الحوادث في الإصدار 3.

الخدمات

الترميز الجغرافي

توفّر واجهة Maps JavaScript API كائن geocoder لعناوين الترميز الجغرافي بشكل ديناميكي من البيانات التي يُدخلها المستخدم. إذا أردت ترميز العناوين الثابتة والمألوفة، راجِع مستندات واجهة برمجة التطبيقات للترميز الجغرافي.

تمت ترقية واجهة برمجة التطبيقات لميزة الترميز الجغرافي وتحسينها بشكل كبير، ما أدّى إلى إضافة ميزات جديدة وتغيير طريقة عرض البيانات.

في الإصدار الثاني من واجهة برمجة التطبيقات GClientGeocoder، وفّرت واجهة برمجة التطبيقات طريقتين مختلفتين للترميز الجغرافي لإعادة التوجيه والترميز العكسي، بالإضافة إلى طرق إضافية للتأثير في طريقة الترميز الجغرافي. وفي المقابل، يوفّر الكائن Geocoder المستنِد إلى إصدار v3 طريقة geocode() فقط، التي تأخذ كائنًا حرفيًا يحتوي على عبارات الإدخال (في شكل كائن طلبات الترميز الجغرافي) وطريقة لمعاودة الاتصال. استنادًا إلى ما إذا كان الطلب يحتوي على سمة address نصية أو عنصر LatLng، ستعرض واجهة برمجة التطبيقات Geocoding API رد ترميز جغرافي أو عكسية. يمكنك التأثير في طريقة تنفيذ الترميز الجغرافي من خلال تمرير حقول إضافية إلى طلب الترميز الجغرافي:

• يؤدي تضمين نص address نصي إلى إعادة توجيه الترميز الجغرافي، ما يعادل استدعاء طريقة getLatLng().
• يؤدي تضمين كائن latLng إلى تشغيل الترميز الجغرافي العكسي، ما يعادل استدعاء طريقة getLocations().
• يؤدي تضمين السمة bounds إلى تفعيل انحياز إطار العرض، أي ما يعادل استدعاء طريقة setViewport().
• يؤدي تضمين السمة region إلى تفعيل انحياز رمز المنطقة، أي ما يعادل استدعاء الطريقة setBaseCountryCode().

تختلف استجابات الترميز الجغرافي في الإصدار 3 عن استجابات الإصدار 2. وتحلّ واجهة برمجة التطبيقات v3 محلّ البنية المدمَجة التي يستخدمها الإصدار 2 ببنية مسطّحة يسهل تحليلها. بالإضافة إلى ذلك، تكون الردود في الإصدار الثالث أكثر تفصيلاً، فكل نتيجة تحتوي على عدة مكوّنات عنوان تساعد في تقديم فكرة أفضل عن حلّ كل نتيجة.

يتضمّن الرمز التالي عنوانًا نصيًا ويعرض النتيجة الأولى من ترميزه الجغرافي:

var geocoder = new GClientGeocoder();
var infoPanel;
var map;
var AccuracyDescription = [
  'Unknown accuracy', 'country level accuracy',
  'region level accuracy', 'sub-region level accuracy',
  'town level accuracy', 'post code level accuracy',
  'street level accuracy', 'intersection level accuracy',
  'address level accuracy', 'premise level accuracy',
];

function geocode_result_handler(response) {
  if (!response || response.Status.code != 200) {
    alert('Geocoding failed. ' + response.Status.code);
  } else {
    var bounds = new GLatLngBounds(new GLatLng(
        response.Placemark[0].ExtendedData.LatLonBox.south,
        response.Placemark[0].ExtendedData.LatLonBox.west
    ), new GLatLng(
        response.Placemark[0].ExtendedData.LatLonBox.north,
        response.Placemark[0].ExtendedData.LatLonBox.east
    ));
    map.setCenter(bounds.getCenter(),
        map.getBoundsZoomLevel(bounds));
    var latlng = new GLatLng(
        response.Placemark[0].Point.coordinates[1],
        response.Placemark[0].Point.coordinates[0]);
    infoPanel.innerHTML += '<p>1st result is <em>' +
        // No info about location type
        response.Placemark[0].address +
        '</em> of <em>' +
        AccuracyDescription[response.Placemark[0].
            AddressDetails.Accuracy] +
        '</em> at <tt>' + latlng + '</tt></p>';
    var marker_title = response.Placemark[0].address +
        ' at ' + latlng;
    map.clearOverlays();

    var marker = marker = new GMarker(
        latlng,
        {'title': marker_title}
    );
    map.addOverlay(marker);
  }
}

function geocode_address() {
  var address = document.getElementById('input-text').value;
  infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
  geocoder.getLocations(address, geocode_result_handler);
}

function initialize() {
  map = new GMap2(document.getElementById('map'));
  map.setCenter(new GLatLng(38, 15), 2);
  map.setUIToDefault();

  infoPanel = document.getElementById('info-panel');
}

var geocoder = new google.maps.Geocoder();
var infoPanel;
var map;
var marker;

function geocode_result_handler(result, status) {
  if (status != google.maps.GeocoderStatus.OK) {
    alert('Geocoding failed. ' + status);
  } else {
    map.fitBounds(result[0].geometry.viewport);
    infoPanel.innerHTML += '<p>1st result for geocoding is <em>' +
        result[0].geometry.location_type.toLowerCase() +
        '</em> to <em>' +
        result[0].formatted_address + '</em> of types <em>' +
        result[0].types.join('</em>, <em>').replace(/_/, ' ') +
        '</em> at <tt>' + result[0].geometry.location +
        '</tt></p>';
    var marker_title = result[0].formatted_address +
        ' at ' + latlng;
    if (marker) {
      marker.setPosition(result[0].geometry.location);
      marker.setTitle(marker_title);
    } else {
      marker = new google.maps.Marker({
        position: result[0].geometry.location,
        title: marker_title,
        map: map
      });
    }
  }
}

function geocode_address() {
  var address = document.getElementById('input-text').value;
  infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
  geocoder.geocode({'address': address}, geocode_result_handler);
}

function initialize() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(38, 15),
    zoom: 2,
    mapTypeId: google.maps.MapTypeId.HYBRID
  });
  infoPanel = document.getElementById('info-panel');
}

الاتجاهات

ويستبدل الإصدار الثالث من "واجهة برمجة تطبيقات JavaScript للخرائط" الفئة GDirections من الإصدار 2 بالفئة DirectionsService لحساب الاتجاهات.

تحلّ طريقة route() في الإصدار 3 محلّ الطريقتَين load() وloadFromWaypoints() من واجهة برمجة التطبيقات v2 API. تستخدم هذه الطريقة حرفيًا واحدًا من عناصر DirectionsRequest يحتوي على عبارات الإدخال وطريقة لرد الاتصال ليتم تنفيذه عند تلقّي الرد. يمكن تقديم خيارات في هذا الكائن حرفيًا، كما هو الحال مع الكائن GDirectionsOptions الحرفي في الإصدار 2.

في الإصدار الثالث من "واجهة برمجة تطبيقات JavaScript للخرائط"، تم فصل مهمة إرسال طلبات الاتجاهات عن مهمة طلبات العرض، والتي تتم الآن معالجتها من خلال الفئة DirectionsRenderer. يمكنك ربط عنصر DirectionsRenderer بأي خريطة أو عنصر DirectionsResult من خلال طريقتَي setMap() وsetDirections(). بما أنّ العارض هو MVCObject، سيتم رصد أي تغييرات في سماته وتعديل الخريطة عند تغيير الاتجاهات المرتبطة.

يوضّح الرمز التالي كيفية طلب اتجاهات المشي إلى موقع جغرافي معيّن باستخدام مسارات المشاة من عنوان معيّن. يُرجى العِلم أنّ الإصدار 3 فقط هو من يمكن توفير اتجاهات المشي في مسار المشاة في "حديقة حيوانات دبلن".

var map;
var directions;
var directionsPanel;

function initialize() {
  var origin = new google.maps.LatLng(53.348172, -6.297285);
  var destination = new google.maps.LatLng(53.355502, -6.30557);
  directionsPanel = document.getElementById("route");

  map = new GMap2(document.getElementById('map'));
  map.setCenter(origin, 10);
  map.setUIToDefault();

  directions = new GDirections(map, directionsPanel);

  directions.loadFromWaypoints(
      [origin, destination], {
        travelMode: 'G_TRAVEL_MODE_WALKING',
  });
}

var map;
var directionsRenderer;
var directionsService = new google.maps.DirectionsService();

function initialize() {
  var origin = new google.maps.LatLng(53.348172, -6.297285);
  var destination = new google.maps.LatLng(53.355502, -6.30557);
  directionsRenderer = new google.maps.DirectionsRenderer();

  map = new google.maps.Map(
      document.getElementById('map'), {
        center: origin,
        zoom: 10,
        mapTypeId: google.maps.MapTypeId.ROADMAP
  });

  directionsRenderer.setPanel(document.getElementById("route"));
  directionsRenderer.setMap(map);
  directionsService.route({
    origin: origin,
    destination: destination,
    travelMode: google.maps.DirectionsTravelMode.WALKING
  }, function(result, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsRenderer.setDirections(result);
    }
  });
}

التجوّل الافتراضي

توفّر ميزة "التجوّل الافتراضي من Google" صورًا تفاعلية بزاوية 360 درجة من مواقع جغرافية محدّدة داخل منطقة التغطية. تتوافق واجهة برمجة التطبيقات v3 API مع ميزة "التجوّل الافتراضي" في المتصفِّح على عكس الإصدار 2 الذي تطلّب المكوّن الإضافي Flash® لعرض صور "التجوّل الافتراضي".

يمكن استخدام صور "التجوّل الافتراضي" من خلال استخدام العنصر StreetViewPanorama في الإصدار 3 أو العنصر GStreetviewPanorama في الإصدار 2. لدى هذه الفئات واجهات مختلفة، ولكنها تؤدي الدور نفسه، وهو ربط حاوية div بصور "التجوّل الافتراضي" والسماح لك بتحديد الموقع الجغرافي وال وجهة النظرية الخاصة بالصورة البانورامية لميزة "التجوّل الافتراضي".

function initialize() {
  var fenwayPark = new GLatLng(42.345573, -71.098326);
  panoramaOptions = {
    latlng: fenwayPark,
    pov: {
      heading: 35,
      pitch: 5,
      zoom: 1
    }
  };

  var panorama = new GStreetviewPanorama(
      document.getElementById('pano'),
      panoramaOptions);

  GEvent.addListener(myPano, "error", handleNoFlash);
}

function handleNoFlash(errorCode) {
  if (errorCode == FLASH_UNAVAILABLE) {
    alert('Error: Your browser does not support Flash');
    return;
  }
}

function initialize() {
  var fenway = new google.maps.LatLng(42.345573, -71.098326);
  var panoramaOptions = {
    position: fenway,
    pov: {
      heading: 35,
      pitch: 5,
      zoom: 1
    }
  };

  var panorama = new google.maps.StreetViewPanorama(
      document.getElementById('pano'),
      panoramaOptions);
}

يمكن الوصول المباشر إلى بيانات "التجوّل الافتراضي" من خلال العنصر StreetViewService في الإصدار 3 أو كائن GStreetviewClient المشابه في الإصدار 2. يوفر كلاهما واجهات متشابهة لاسترداد بيانات "التجوّل الافتراضي" أو التحقّق من توفّرها، ويسمحان بالبحث حسب الموقع الجغرافي أو معرّف البانوراما.

وفي الإصدار الثالث، يتم تفعيل ميزة "التجوّل الافتراضي" بشكلٍ تلقائي. ستظهر الخريطة مع عنصر تحكّم في دليل "التجوّل الافتراضي" وستُعيد واجهة برمجة التطبيقات استخدام علامة div في الخريطة لعرض الصور البانورامية للتجوّل الافتراضي. ويوضّح الرمز التالي كيفية محاكاة سلوك الإصدار 2 من خلال فصل الصور البانورامية ضمن "التجوّل الافتراضي" في عنصر div منفصل.

var marker;
var panoClient = new GStreetviewClient();

function initialize() {
  if (GBrowserIsCompatible()) {
    var myPano = new GStreetviewPanorama(
        document.getElementById('pano'));
    GEvent.addListener(myPano, 'error', handleNoFlash);
    var map = new GMap2(document.getElementById('map'));
    map.setCenter(new GLatLng(42.345573, -71.098326), 16);
    map.setUIToDefault();

    GEvent.addListener(map, 'click', function(overlay, latlng) {
      if (marker) {
        marker.setLatLng(latlng);
      } else {
        marker = new GMarker(latlng);
        map.addOverlay(marker);
      }
      var nearestPano = panoClient.getNearestPanorama(
          latlng, processSVData);
    });

    function processSVData(panoData) {
      if (panoData.code != 200) {
        alert("Panorama data not found for this location.");
      }
      var latlng = marker.getLatLng();
      var dLat = latlng.latRadians()
          - panoData.location.latlng.latRadians();
      var dLon = latlng.lngRadians()
          - panoData.location.latlng.lngRadians();
      var y = Math.sin(dLon) * Math.cos(latlng.latRadians());
      var x = Math.cos(panoData.location.latlng.latRadians()) *
              Math.sin(latlng.latRadians()) -
              Math.sin(panoData.location.latlng.latRadians()) *
              Math.cos(latlng.latRadians()) * Math.cos(dLon);
      var bearing = Math.atan2(y, x) * 180 / Math.PI;

      myPano.setLocationAndPOV(panoData.location.latlng, {
        yaw: bearing
      });
    }

    function handleNoFlash(errorCode) {
      if (errorCode == FLASH_UNAVAILABLE) {
        alert('Error: Your browser does not support Flash');
        return;
      }
    }
  }
}

// Load the API with libraries=geometry
var map;
var marker;
var panorama;
var sv = new google.maps.StreetViewService();

function radians(degrees) { return Math.PI * degrees / 180.0 };

function initialize() {

  panorama = new google.maps.StreetViewPanorama(
      document.getElementById("pano"));

  map = new google.maps.Map(
      document.getElementById('map'), {
    center: new google.maps.LatLng(42.345573, -71.098326),
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    zoom: 16
  });

  google.maps.event.addListener(map, 'click', function(event) {
    if (!marker) {
      marker = new google.maps.Marker({
          position: event.latLng,
          map: map
      });
    } else {
      marker.setPosition(event.latLng);
    }
    sv.getPanoramaByLocation(event.latLng, 50, processSVData);
  });
}

function processSVData(panoData, status) {
  if (status == google.maps.StreetViewStatus.OK) {
    alert("Panorama data not found for this location.");
  }
  var bearing = google.maps.geometry.spherical.computeHeading(
      panoData.location.latLng, marker.getPosition());

  panorama.setPano(panoData.location.pano);

  panorama.setPov({
    heading: bearing,
    pitch: 0,
    zoom: 1
  });

  panorama.setVisible(true);
  marker.setMap(panorama);
}