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

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

نظرة عامة

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

1. الحصول على مفتاح جديد: تستخدم Google Maps JavaScript API الآن Google Cloud Console لإدارة المفاتيح. إذا كنت لا تزال تستخدم مفتاحًا من الإصدار 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 من ملفات externs. يمكن استخدام العناصر الخارجية في الإصدار 3 للمساعدة في التحقّق من صحة الرمز البرمجي باستخدام مجمّع Closure compiler، أو لتشغيل ميزة الإكمال التلقائي في بيئة تطوير البرامج المتكاملة. اطّلِع على مزيد من المعلومات عن الترجمة المتقدّمة والبرامج الخارجية.
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 كجزء من عملية نقل البيانات، ما سيؤدي إلى:

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

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

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

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

يتضمن التعديل الأول الذي عليك إجراؤه على الرمز البرمجي كيفية تحميل واجهة برمجة التطبيقات. في الإصدار 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. تضع واجهة برمجة التطبيقات من الإصدار 2 جميع العناصر في مساحة الاسماء العامة تلقائيًا، ما قد يؤدي إلى تعارضات في التسمية. في الإصدار 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:

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

رمز المقارنة

لنقارن بين تطبيقَين بسيطَين تم كتابتهما باستخدام واجهتَي برمجة التطبيقات 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، وتمت إزالتهما من 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. تم تصميم كل قسم من المرجع ليتم قراءته بشكلٍ فردي. ننصحك بعدم قراءة هذا المرجع بالكامل، ولكن بدلاً من ذلك، استخدِم هذه المادة لمساعدة عملية نقل البيانات على أساس كل حالة على حدة.

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

الفعاليات

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

حدث جديد لدعم MVC

تضيف واجهة برمجة التطبيقات 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

إذا كنت تريد تسجيل أحداث 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 متزامنة متعددة على كل خريطة.
• سيظلّ InfoWindow من الإصدار 3 مفتوحًا عند النقر على الخريطة. يتم إغلاق 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" بعض التغييرات على أنواع الخريطة الأقل شيوعًا أيضًا:

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

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

طبقات KML وGeoRSS

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