ترقية تطبيقك المزوّد لواجهة برمجة التطبيقات Maps JavaScript API من الإصدار 2 إلى الإصدار 3

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

نظرة عامة

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

  1. الحصول على مفتاح جديد: تستخدم Google Maps JavaScript API الآن وحدة تحكّم Google Cloud لإدارة المفاتيح. إذا كنت لا تزال تستخدم مفتاحًا من الإصدار 2، احرص على الحصول على مفتاح واجهة برمجة التطبيقات الجديد قبل بدء عملية نقل البيانات.
  2. تعديل ملف Bootstrap الخاص بواجهة برمجة التطبيقات ستحمِّل معظم التطبيقات واجهة برمجة التطبيقات Maps JavaScript API الإصدار 3 باستخدام الرمز التالي:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. عدِّل الرمز. يعتمد مقدار التغيير المطلوب إلى حد كبير على تطبيقك. تشمل التغييرات الشائعة ما يلي:
    • يجب دائمًا الإشارة إلى مساحة الاسم google.maps. في الإصدار 3، يتم تخزين كل رمز Maps JavaScript API في مساحة الاسم google.maps.* بدلاً من مساحة الاسم الشاملة. تمت أيضًا إعادة تسمية معظم العناصر كجزء من هذه العملية. على سبيل المثال، بدلاً من GMap2، سيتم الآن تحميل google.maps.Map.
    • أزِل أي إشارات إلى الطرق القديمة. تمّت إزالة عددٍ من طرق الأدوات العامة، مثل GDownloadURL وGLog. استبدِل هذه الوظيفة بمكتبات أدوات تابعة لجهات خارجية، أو أزِل هذه الإشارات من الرمز البرمجي.
    • (اختياري) إضافة مكتبات إلى الرمز البرمجي تم نقل العديد من الميزات إلى مكتبات الأدوات لكي لا يحتاج كل تطبيق إلى تحميل سوى أجزاء واجهة برمجة التطبيقات التي سيتم استخدامها.
    • (اختياري) يمكنك ضبط مشروعك لاستخدام العناصر الخارجية في الإصدار 3. يمكن استخدام العناصر الخارجية في الإصدار 3 للمساعدة في التحقّق من صحة الرمز البرمجي باستخدام مجمّع Closureأو لتشغيل ميزة "الإكمال التلقائي" في بيئة تطوير البرامج المتكاملة. اطّلِع على مزيد من المعلومات عن الترجمة المتقدّمة والبرامج الخارجية.
  4. الاختبار والتكرار التحسيني: في هذه المرحلة، سيظل أمامك بعض العمل، ولكن الخبر السارّ هو أنّك ستكون على بُعد خطوة واحدة من إكمال تطبيق الخرائط الجديد بالإصدار 3.

التغييرات في الإصدار 3 من واجهة برمجة التطبيقات JavaScript لخرائط Google

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

تشمل بعض التغييرات في الإصدار 3 من واجهة برمجة التطبيقات ما يلي:

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

ترقية طلبك

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

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

يتم تمرير المفتاح عند تحميل الإصدار 3 من واجهة برمجة تطبيقات JavaScript لخرائط Google. مزيد من المعلومات حول إنشاء مفاتيح واجهة برمجة التطبيقات

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

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

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

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

في أبسط الحالات، سيحدِّد الإصدار 3 من أداة Bootstrap مَعلمة مفتاح واجهة برمجة التطبيقات فقط:

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

يطلب المثال أدناه أحدث إصدار من واجهة برمجة التطبيقات JavaScript API v2 لتطبيق "خرائط Google" باللغة الألمانية:

<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

من المحتمل أن يكون التغيير الأكثر بروزًا في الإصدار 3 من واجهة برمجة التطبيقات JavaScript لـ "خرائط Google" هو تقديم مساحة الاسم 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

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

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

لا تتوفّر فئات مماثلة للفئات التالية في الإصدار 3 من واجهة برمجة التطبيقات JavaScript لخرائط Google:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

رمز المقارنة

لنقارن بين تطبيقَين بسيطَين تم كتابتهما باستخدام واجهتَي برمجة التطبيقات v2 وv3.

<!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، وتمت إزالتهما من Google Sheets API.
  • تم استبدال العنصر GMap2 بأحد العناصر التالية: google.maps.Map كعنصر مركزي في واجهة برمجة التطبيقات.
  • يتم الآن تحميل المواقع من خلال فئات الخيارات. في المثال أعلاه، ضبطنا السمات الثلاث المطلوبة لتحميل خريطة، وهي center وzoom وmapTypeId ، من خلال عنصر MapOptions مضمّن.
  • تكون واجهة المستخدم التلقائية مفعَّلة تلقائيًا في الإصدار 3. يمكنك إيقاف هذه الميزة من خلال ضبط الخاصية disableDefaultUI على true في عنصر MapOptions.

ملخّص

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

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

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

مرجع تفصيلي

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

الفعاليات

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

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

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

يصدّر كل عنصر من عناصر Maps API عددًا من الأحداث المُسمّاة. على التطبيقات التي تهمّها أحداث معيّنة تسجيل أدوات معالجة الأحداث لهذه الأحداث وتنفيذ الرمز عند تلقّي هذه الأحداث. هذه المنظومة المستندة إلى الحدث هي نفسها في كلّ من الإصدارين GEvent وgoogle.maps.event من واجهة برمجة التطبيقات JavaScript لـ "خرائط Google"، باستثناء أنّ نطاق الاسم قد تغيّر من 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 في الإصدار 3).
  2. عندما تريد إزالة أداة معالجة الحدث، مرِّر هذا العنصر إلى الأسلوب removeListener() (GEvent.removeListener() في الإصدار 2 أو google.maps.event.removeListener() في الإصدار 3) لإزالة أداة معالجة الحدث.

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

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

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

// 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 لخرائط Google عناصر التحكّم في واجهة المستخدم التي تسمح للمستخدمين بالتفاعل مع خريطتك. يمكنك استخدام واجهة برمجة التطبيقات لتخصيص طريقة ظهور عناصر التحكّم هذه.

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

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

باستخدام الإصدار 2 من واجهة برمجة التطبيقات JavaScript لـ "خرائط Google"، يمكنك إضافة عناصر تحكّم إلى خريطتك من خلال طريقة addControl() لعنصر الخريطة. في الإصدار 3، بدلاً من الوصول إلى عناصر التحكّم أو تعديلها مباشرةً، يمكنك تعديل عنصر 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);

تتيح لك واجهة برمجة التطبيقات Maps JavaScript API إنشاء عناصر تحكّم مخصّصة في التنقّل. لتخصيص عناصر التحكّم باستخدام واجهة برمجة التطبيقات v2، عليك إنشاء فئة فرعية من فئة GControl وتحديد معالِجات لطريقتَي initialize() وgetDefaultPosition(). لا تتوفّر فئة مكافئة لفئة GControl في الإصدار 3. وبدلاً من ذلك، يتم تمثيل عناصر التحكّم كعناصر DOM. لإضافة عنصر تحكّم مخصّص باستخدام واجهة برمجة التطبيقات v3، أنشئ بنية 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 API على تبسيط هذه العملية قليلاً. ما عليك سوى ضبط سمة icon للعلامة على عنوان URL لصورتك المخصّصة، وستضبط واجهة برمجة التطبيقات حجم الرمز تلقائيًا.

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

ترسم الأمثلة أدناه الخط المتعدّد الأضلاع المشفَّر نفسه، ويستخدم رمز الإصدار 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 في الإصدار 3 إلى حد كبير فئة GPolygon في الإصدار 2، باستثناء أنّه لم يعُد عليك تكرار رأس البداية في نهاية المسار لإغلاق الحلقة. ستغلق واجهة برمجة التطبيقات لإصدار 3 أي مضلّعات تلقائيًا من خلال رسم خط يربط الإحداثي الأخير بالإحداثي الأول. تنشئ المقتطفات التالية من الرموز البرمجية مضلعًا يمثّل مثلث برمودا:

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:

  • لا تتيح واجهة برمجة التطبيقات في الإصدار 2 سوى GInfoWindow لكل خريطة، في حين تتيح واجهة برمجة التطبيقات في الإصدار 3 InfoWindow متزامنة متعددة على كل خريطة.
  • سيظل الإصدار 3 من InfoWindow مفتوحًا عند النقر على الخريطة. يتم إغلاق GInfoWindow الإصدار 2 تلقائيًا عند النقر على الخريطة. يمكنك محاكاة سلوك الإصدار 2 عن طريق إضافة مستمع click إلى العنصر Map.
  • لا توفّر الإصدار 3 من واجهة برمجة التطبيقات دعمًا أصليًا ل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 تحديد نوع خريطة معيّن عند إنشاء عنصر 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 من واجهة برمجة التطبيقات JavaScript لـ "خرائط Google" بعض التغييرات على أنواع الخريطة الأقل شيوعًا أيضًا:

  • لا تتوفّر أجسام سماوية غير الأرض كأنواع خرائط في واجهة برمجة التطبيقات v3، ولكن يمكن الوصول إليها كأنواع خرائط مخصّصة كما هو موضّح في هذا المثال.
  • لا يتوفّر نوع خريطة خاص في الإصدار 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، تكون عناصر التحكّم مشابهة لعنصر التحكّم GLargeZoomControl3D في الإصدار 2، مع عنصر تحكّم إضافي للتدوير من خلال الاتجاهات المتوافقة.

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

الطبقات

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

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

  • يعرض عنصر KmlLayer عناصر KML وGeoRSS في ملف GeoXml v3، ما يوفر العنصر المكافئ لملف GeoXml v2.
  • يعرض عنصر TrafficLayer طبقة تعرض ظروف حركة المرور، على غرار تراكب GTrafficOverlay الإصدار 2.

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

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

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

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

عند عرض 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);

تتيح لك الإصدار 3 إضافة معلومات عن حركة المرور في الوقت الفعلي (حيثما كان ذلك متاحًا) إلى خرائطك باستخدام العنصر 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 ل ترميز العناوين الجغرافية ديناميكيًا من إدخال المستخدم. إذا كنت تريد ترميز العناوين الثابتة والمعروفة جغرافيًا، يُرجى الاطّلاع على مستندات Geocoding API.

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

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

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

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

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

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');
}

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

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

في الإصدار 3 من واجهة برمجة التطبيقات JavaScript لخرائط Google، تم فصل مهمة إرسال طلبات تحديد الاتجاهات عن مهمة عرض الطلبات، والتي تتم إدارتها الآن باستخدام فئة 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 استخدام "التجوّل الافتراضي" بشكلٍ أصلي داخل المتصفّح، على عكس الإصدار 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. يقدّم كلاهما واجهتَين مشابهتَين لاسترداد بيانات "التجوّل الافتراضي" أو التحقّق من توفّرها، والسماح بالبحث حسب الموقع الجغرافي أو رقم تعريف البانوراما.

في الإصدار 3، تكون ميزة "التجوّل الافتراضي" مفعَّلة تلقائيًا. ستظهر الخريطة مع عنصر التحكّم Pegman في "التجوّل الافتراضي" وستعيد واجهة برمجة التطبيقات استخدام 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);
}