ارتقای برنامه Maps JavaScript API از V2 به V3

با مجموعه‌ها، منظم بمانید ذخیره و دسته‌بندی محتوا براساس اولویت‌های شما.

Maps JavaScript API v2 از 26 مه 2021 دیگر در دسترس نیست. در نتیجه، نقشه‌های v2 سایت شما از کار می‌افتند و خطاهای جاوا اسکریپت را برمی‌گردانند. برای ادامه استفاده از نقشه‌ها در سایت خود، به Maps JavaScript API نسخه 3 بروید. این راهنما به شما در طی این فرآیند کمک می کند.

بررسی اجمالی

هر برنامه یک روند مهاجرت کمی متفاوت خواهد داشت. با این حال، مراحلی وجود دارد که برای همه پروژه‌ها مشترک است:

  1. یک کلید جدید دریافت کنید. Maps JavaScript API اکنون از Google Cloud Console برای مدیریت کلیدها استفاده می کند. اگر همچنان از کلید v2 استفاده می کنید، قبل از شروع مهاجرت، حتما کلید API جدید خود را دریافت کنید.
  2. API Bootstrap خود را به روز کنید. اکثر برنامه ها Maps JavaScript API v3 را با کد زیر بارگذاری می کنند:
    <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 . یا این قابلیت را با کتابخانه های ابزار شخص ثالث جایگزین کنید یا این مراجع را از کد خود حذف کنید.
    • (اختیاری) کتابخانه ها را به کد خود اضافه کنید. بسیاری از ویژگی‌ها به کتابخانه‌های ابزار خارجی تبدیل شده‌اند، به طوری که هر برنامه فقط باید قسمت‌هایی از API را که مورد استفاده قرار می‌گیرد بارگیری کند.
    • (اختیاری) پروژه خود را برای استفاده از خارجی های v3 پیکربندی کنید. خارجی‌های v3 می‌توانند برای کمک به اعتبارسنجی کد شما با Closure Compiler یا برای فعال کردن تکمیل خودکار در IDE شما استفاده شوند. درباره کامپایل پیشرفته و خارجی بیشتر بیاموزید .
  4. تست و تکرار کنید. در این مرحله شما هنوز مقداری کار برای انجام خواهید داشت، اما خبر خوب این است که به خوبی در مسیر برنامه جدید نقشه های v3 خود خواهید بود!

تغییرات در V3 از Maps JavaScript API

قبل از برنامه ریزی مهاجرت خود، باید زمانی را برای درک تفاوت های بین Maps JavaScript API v2 و Maps JavaScript API v3 اختصاص دهید. جدیدترین نسخه Maps JavaScript API از ابتدا با تمرکز بر تکنیک های برنامه نویسی جاوا اسکریپت مدرن، افزایش استفاده از کتابخانه ها و یک API ساده شده نوشته شده است. بسیاری از ویژگی های جدید به API اضافه شده اند و چندین ویژگی آشنا تغییر کرده یا حتی حذف شده اند. این بخش برخی از تفاوت های کلیدی بین این دو نسخه را برجسته می کند.

برخی از تغییرات در API v3 عبارتند از:

  • یک کتابخانه اصلی کارآمد. بسیاری از توابع تکمیلی به کتابخانه‌ها منتقل شده‌اند و به کاهش بار و زمان تجزیه برای Core API کمک می‌کنند که به شما امکان می‌دهد نقشه شما به سرعت در هر دستگاهی بارگیری شود.
  • بهبود عملکرد چندین ویژگی، مانند رندر چند ضلعی و قرار دادن نشانگر.
  • یک رویکرد جدید برای محدودیت‌های استفاده سمت مشتری برای تطبیق بهتر آدرس‌های مشترک مورد استفاده توسط پراکسی‌های تلفن همراه و فایروال‌های شرکتی.
  • پشتیبانی از چندین مرورگر مدرن و مرورگرهای تلفن همراه اضافه شده است. پشتیبانی از اینترنت اکسپلورر 6 حذف شده است.
  • بسیاری از کلاس های کمکی همه منظوره ( GLog یا GDownloadUrl ) را حذف کرد. امروزه، بسیاری از کتابخانه‌های جاوا اسکریپت عالی وجود دارند که عملکردهای مشابهی را ارائه می‌کنند، مانند Closure یا jQuery .
  • یک پیاده سازی نمای خیابان HTML5 که در هر دستگاه تلفن همراه بارگیری می شود.
  • پانورامای نمای خیابان سفارشی با عکس های خود، به شما امکان می دهد تصاویر پانوراما از پیست های اسکی، خانه های برای فروش یا مکان های جالب دیگر را به اشتراک بگذارید.
  • سفارشی‌سازی‌های Styled Maps که به شما امکان می‌دهد نمایش عناصر را روی نقشه پایه تغییر دهید تا با سبک بصری منحصر به فرد خود مطابقت داشته باشد.
  • پشتیبانی از چندین سرویس جدید، مانند ElevationService و Distance Matrix .
  • خدمات مسیرهای بهبودیافته مسیرهای جایگزین، بهینه سازی مسیر (راه حل های تقریبی برای مشکل فروشنده دوره گرد)، مسیرهای دوچرخه سواری (با لایه دوچرخه سواری )، مسیرهای حمل و نقل، و مسیرهای قابل کشیدن را ارائه می دهد.
  • یک قالب Geocoding به روز شده که اطلاعات نوع دقیق تری را نسبت به مقدار accuracy از Geocoding API v2 ارائه می دهد.
  • پشتیبانی از چندین ویندوز اطلاعات در یک نقشه

ارتقاء برنامه شما

کلید جدید شما

Maps JavaScript API v3 از یک سیستم کلید جدید از نسخه 2 استفاده می کند. ممکن است قبلاً از یک کلید v3 برای برنامه خود استفاده کرده باشید، در این صورت نیازی به تغییر نیست. برای تأیید، نشانی اینترنتی را که Maps JavaScript API از آن بارگیری می‌کنید برای پارامتر key آن بررسی کنید. اگر مقدار کلید با "ABQIAA" شروع می شود، شما از یک کلید v2 استفاده می کنید. اگر یک کلید v2 دارید، باید به عنوان بخشی از انتقال، به یک کلید v3 ارتقا دهید، که:

هنگام بارگیری Maps JavaScript API v3، کلید ارسال می شود. درباره ایجاد کلیدهای API بیشتر بیاموزید .

توجه داشته باشید که اگر مشتری Google Maps APIs for Work هستید، ممکن است به جای استفاده از پارامتر key ، از شناسه مشتری با پارامتر client استفاده کنید. شناسه‌های سرویس گیرنده همچنان در Maps JavaScript API نسخه 3 پشتیبانی می‌شوند و نیازی به انجام فرآیند ارتقاء کلید ندارند.

در حال بارگیری API

اولین تغییری که باید در کد خود انجام دهید مربوط به نحوه بارگیری API است. در نسخه 2، Maps JavaScript API را از طریق یک درخواست به http://maps.google.com/maps بارگیری می‌کنید. اگر در حال بارگیری Maps JavaScript API v3 هستید، باید تغییرات زیر را اعمال کنید:

  1. API را از //maps.googleapis.com/maps/api/js بارگیری کنید
  2. پارامتر file را حذف کنید.
  3. پارامتر key را با کلید v3 جدید خود به روز کنید. مشتریان Google Maps APIs for Work باید از پارامتر client استفاده کنند.
  4. (فقط طرح ممتاز پلتفرم Google Maps) اطمینان حاصل کنید که پارامتر client همانطور که در راهنمای برنامه‌نویس برنامه Google Maps Platform Premium توضیح داده شده است، ارائه شده است.
  5. برای درخواست آخرین نسخه منتشر شده، پارامتر v را حذف کنید یا مقدار آن را مطابق با طرح نسخه سازی v3 تغییر دهید.
  6. (اختیاری) پارامتر hl را با language جایگزین کنید و مقدار آن را حفظ کنید.
  7. (اختیاری) برای بارگیری کتابخانه های اختیاری ، پارامتر libraries را اضافه کنید.

در ساده ترین حالت، bootstrap v3 فقط پارامتر کلید API شما را مشخص می کند:

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

مثال زیر آخرین نسخه Maps JavaScript API v2 را به زبان آلمانی درخواست می کند:

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

مثال زیر یک درخواست معادل برای v3 است.

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

معرفی فضای نام google.maps

احتمالاً قابل توجه ترین تغییر در Maps JavaScript API v3، معرفی فضای نام google.maps است. v2 API همه اشیا را به طور پیش‌فرض در فضای نام جهانی قرار می‌دهد که می‌تواند منجر به برخورد نام‌گذاری شود. در نسخه 3، همه اشیا در فضای نام google.maps قرار دارند.

هنگام انتقال برنامه خود به نسخه 3، باید کد خود را تغییر دهید تا از فضای نام جدید استفاده کنید. متأسفانه، جستجوی «G» و جایگزینی با «google.maps». به طور کامل کار نخواهد کرد. اما، این یک قانون سرانگشتی خوب است که هنگام بررسی کد خود اعمال کنید. در زیر چند نمونه از کلاس های معادل در v2 و v3 آورده شده است.

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

حذف کد منسوخ شده

Maps JavaScript API v3 برای بیشتر عملکردهای نسخه 2 مشابهی دارد. با این حال، برخی از کلاس ها هستند که دیگر پشتیبانی نمی شوند. به عنوان بخشی از مهاجرت خود، باید این کلاس ها را با کتابخانه های ابزار شخص ثالث جایگزین کنید یا این مراجع را از کد خود حذف کنید. بسیاری از کتابخانه های جاوا اسکریپت عالی وجود دارند که عملکردهای مشابهی مانند بستن یا جی کوئری را ارائه می دهند.

کلاس های زیر در Maps JavaScript API v3 مشابهی ندارند:

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

مقایسه کد

بیایید دو برنامه نسبتاً ساده را که با API های 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>
    

همانطور که می بینید، چندین تفاوت بین این دو برنامه وجود دارد. تغییرات قابل توجه عبارتند از:

  • آدرسی که API از آن بارگیری می شود تغییر کرده است.
  • GBrowserIsCompatible() و GUnload() دیگر در نسخه 3 مورد نیاز نیستند و از API حذف شده اند.
  • شی GMap2 با google.maps.Map به عنوان شی مرکزی در API جایگزین شده است.
  • اکنون ویژگی ها از طریق کلاس های Options بارگیری می شوند. در مثال بالا، ما سه ویژگی مورد نیاز برای بارگیری یک نقشه - center ، zoom و mapTypeId - را از طریق یک شی MapOptions .
  • رابط کاربری پیش فرض در نسخه 3 به طور پیش فرض روشن است. می‌توانید با تنظیم ویژگی disableDefaultUI روی true در شی MapOptions ، آن را غیرفعال کنید.

خلاصه

در این مرحله، برخی از نکات کلیدی مربوط به انتقال شما از نسخه 2 به نسخه 3 از Maps JavaScript API را خواهید چشید. اطلاعات بیشتری وجود دارد که ممکن است لازم باشد بدانید، اما به درخواست شما بستگی دارد. در بخش‌های بعدی، دستورالعمل‌های مهاجرت را برای موارد خاصی که ممکن است با آن‌ها مواجه شوید قرار داده‌ایم. علاوه بر این، منابع متعددی وجود دارد که ممکن است در طول فرآیند ارتقا برای شما مفید باشد.

  • Maps JavaScript API v3 Developers Documentation بهترین مکان برای کسب اطلاعات بیشتر در مورد API و نحوه عملکرد آن است.
  • مرجع Maps JavaScript API v3 به شما کمک می کند تا در مورد کلاس ها و روش های جدید در v3 API اطلاعات بیشتری کسب کنید.
  • انجمن Stack Overflow مکانی عالی برای پرسیدن سوالات مربوط به کد شما است. در سایت، سؤالات و پاسخ‌های مربوط به Maps JavaScript API از برچسب‌های « google-maps » یا « google-maps-api-3 » استفاده می‌شود.
  • مشتریان طرح ممتاز پلتفرم Google Maps مایلند اسناد طرح ممتاز پلتفرم Google Maps را مطالعه کنند.
  • وبلاگ Google Geo Developers یک راه عالی برای اطلاع از آخرین تغییرات API است.

اگر در مورد این مقاله مشکل یا سؤالی دارید، لطفاً از پیوند ارسال بازخورد در بالای این صفحه استفاده کنید.

مرجع تفصیلی

این بخش مقایسه دقیقی از محبوب ترین ویژگی های نسخه 2 و 3 از Maps JavaScript API ارائه می دهد. هر بخش از مرجع برای خواندن جداگانه طراحی شده است. توصیه می کنیم این مرجع را به طور کامل مطالعه نکنید. در عوض، از این مطالب برای کمک به مهاجرت خود به صورت موردی استفاده کنید.

  • رویدادها - ثبت و رسیدگی به رویدادها.
  • کنترل ها - دستکاری کنترل های ناوبری که روی نقشه ظاهر می شوند.
  • پوشش ها - اضافه کردن و ویرایش اشیاء روی نقشه.
  • انواع نقشه - کاشی هایی که نقشه پایه را تشکیل می دهند.
  • لایه ها - اضافه کردن و ویرایش محتوا به عنوان یک گروه، مانند لایه های KML یا ترافیک.
  • خدمات - کار با کدگذاری جغرافیایی Google، مسیرها یا خدمات نمای خیابان.

مناسبت ها

مدل رویداد برای Maps JavaScript API v3 شبیه به آنچه در نسخه 2 استفاده شده است، است، اگرچه بسیاری از موارد در زیر هود تغییر کرده است.

کنترل ها

Maps JavaScript API کنترل‌های UI را نمایش می‌دهد که به کاربران اجازه می‌دهد با نقشه شما تعامل داشته باشند. می‌توانید از API برای سفارشی کردن نحوه نمایش این کنترل‌ها استفاده کنید.

پوشش ها

روکش ها اشیایی را منعکس می کنند که برای تعیین نقاط، خطوط، مناطق یا مجموعه ای از اشیاء به نقشه "اضافه می کنید".

انواع نقشه

انواع نقشه های موجود در نسخه 2 و 3 کمی متفاوت هستند، اما همه انواع نقشه های اصلی در هر دو نسخه API موجود هستند. به‌طور پیش‌فرض، v2 از کاشی‌های نقشه راه استاندارد «رنگ‌شده» استفاده می‌کند. با این حال، v3 نیاز به یک نوع نقشه خاص برای ایجاد یک شی google.maps.Map دارد.

لایه های

لایه ها اشیایی روی نقشه هستند که از یک یا چند پوشش تشکیل شده اند. آنها را می توان به عنوان یک واحد دستکاری کرد و به طور کلی مجموعه ای از اشیاء را منعکس می کند.

خدمات