ارتقای برنامه 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 دارد.

لایه ها

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

خدمات

،

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 ارائه می دهد.
  • پشتیبانی از چندین ویندوز اطلاعات در یک نقشه

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

کلید جدید شما

نقشه های JavaScript API V3 از یک سیستم کلید جدید از V2 استفاده می کند. شما ممکن است در حال حاضر از یک کلید V3 با برنامه خود استفاده کنید ، در این صورت هیچ تغییری لازم نیست. برای تأیید ، URL را که از آن استفاده می کنید API JavaScript را برای پارامتر key آن بارگذاری کنید. اگر مقدار کلیدی با "ABQIAA" شروع شود ، شما از یک کلید V2 استفاده می کنید. اگر یک کلید V2 دارید ، باید به عنوان بخشی از مهاجرت به یک کلید V3 ارتقا دهید ، که این امر خواهد بود:

کلید هنگام بارگیری نقشه های JavaScript API V3 منتقل می شود. در مورد تولید کلیدهای API بیشتر بدانید .

توجه داشته باشید که اگر شما یک API های Google Maps برای مشتری کار هستید ، ممکن است به جای استفاده از پارامتر key ، از یک شناسه مشتری با پارامتر client استفاده کنید. شناسه مشتری هنوز در نقشه های JavaScript API V3 پشتیبانی می شود و نیازی به طی کردن فرآیند ارتقاء کلیدی نیست.

بارگیری API

اولین اصلاحاتی که باید به کد خود بسازید شامل نحوه بارگیری API است. در V2 ، نقشه های JavaScript API را از طریق درخواست به http://maps.google.com/maps بارگیری می کنید. اگر در حال بارگیری نقشه های JavaScript API V3 هستید ، باید تغییرات زیر را ایجاد کنید:

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

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

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

مثال زیر آخرین نسخه نقشه های 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

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

هنگام مهاجرت درخواست خود به V3 ، باید کد خود را تغییر دهید تا از فضای نام جدید استفاده کنید. متأسفانه ، جستجوی "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

حذف کد منسوخ

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

کلاس های زیر هیچ موازی در نقشه های 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() دیگر در V3 مورد نیاز نیست و از API حذف شده است.
  • شیء GMap2 توسط google.maps.Map به عنوان شی مرکزی در API جایگزین می شود.
  • اکنون خواص از طریق کلاس های گزینه ها بارگیری می شوند. در مثال بالا ، ما سه ویژگی مورد نیاز برای بارگذاری نقشه - center ، zoom و mapTypeId - را از طریق یک شیء MapOptions Inlined تنظیم می کنیم.
  • UI پیش فرض به طور پیش فرض در V3 روشن است. می توانید با تنظیم ویژگی disableDefaultUI در True در شیء MapOptions این مسئله را غیرفعال کنید.

خلاصه

در این مرحله ، شما برای برخی از نکات کلیدی درگیر در مهاجرت خود از V2 به V3 از نقشه های JavaScript API طعم و مزه پیدا کرده اید. اطلاعات بیشتری وجود دارد که ممکن است شما نیاز به دانستن داشته باشید ، اما به برنامه شما بستگی دارد. در بخش های بعدی ، ما دستورالعمل های مهاجرت را برای موارد خاص که ممکن است با آنها روبرو شوید ، درج کرده ایم. علاوه بر این ، منابع مختلفی وجود دارد که ممکن است در طی فرآیند ارتقاء مفید باشد.

  • مستندات MAPS JavaScript API V3 Developers بهترین مکان برای کسب اطلاعات بیشتر در مورد API و نحوه عملکرد آن است.
  • MAPS JavaScript API V3 Reference به شما کمک می کند تا در مورد کلاس ها و روش های جدید در API V3 اطلاعات بیشتری کسب کنید.
  • جامعه سرریز پشته مکانی عالی برای پرسیدن سوالات مربوط به کد شما است. در سایت ، سؤالات و پاسخ های مربوط به نقشه های JavaScript API از برچسب های " Google-Maps " یا " Google-MAPS-API-3 " استفاده می کنند.
  • Google Maps Platform Plate Plam Plan مشتریان می خواهند از طریق مستندات طرح حق بیمه پلت فرم Google Maps Platform بخوانند.
  • وبلاگ Google Geo Developers یک روش عالی برای اطلاع از آخرین تغییرات در API است.

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

مرجع دقیق

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

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

رویدادها

مدل رویداد برای نقشه های JavaScript API V3 شبیه به استفاده در V2 است ، اگرچه در زیر کاپوت بسیار تغییر کرده است.

کنترل ها

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

روکش ها

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

انواع نقشه

انواع نقشه های موجود در V2 و V3 کمی متفاوت است ، اما تمام انواع اصلی نقشه در هر دو نسخه API موجود است. به طور پیش فرض ، V2 از کاشی های نقشه راه استاندارد "نقاشی شده" استفاده می کند. با این حال ، V3 نیاز به یک نوع نقشه خاص دارد که هنگام ایجاد یک شیء google.maps.Map داده می شود.

لایه ها

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

خدمات