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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

رمز المقارنة

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

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

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

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

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

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

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

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

ملخّص

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

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

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

مرجع تفصيلي

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

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

فعاليات

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

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

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

تراكبات

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

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

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

الطبقات

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

الخدمات