ترقية تطبيق واجهة برمجة تطبيقات JavaScript من V2 إلى V3

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

نظرة عامة

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

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

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

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

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

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

ترقية تطبيقك

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

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

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

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

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

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

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

في أبسط الحالات، لن يحدّد بدء التشغيل باستخدام الإصدار 3 من سوى معلمة مفتاح واجهة برمجة التطبيقات فقط:

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

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

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

عند نقل بيانات تطبيقك إلى الإصدار 3، عليك تغيير الرمز للاستفادة من مساحة الاسم الجديدة. للأسف، لن يعمل البحث عن &"G" واستبدالها بـ "google;maps.google&";#39;t;;33;;33;;9، لكن يُفضّل تطبيقها عند مراجعة الرمز، في ما يلي بعض الأمثلة على الفئات المكافئة في الإصدارَين v2 وv3.

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

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

ملخّص

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

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

المرجع التفصيلي

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

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

الأحداث

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

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

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

النوافذ المتراكبة

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

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

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

طبقات

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

الخدمات