اعلامیه: سبک نقشه پایه جدید به زودی به پلتفرم نقشه های گوگل می آید. این به‌روزرسانی برای استایل نقشه شامل یک پالت رنگی پیش‌فرض جدید، پین‌های مدرن شده و بهبودهایی در تجربه‌ها و قابلیت استفاده از نقشه است. همه سبک‌های نقشه به‌طور خودکار در مارس 2025 به‌روزرسانی می‌شوند. برای اطلاعات بیشتر در مورد در دسترس بودن و نحوه انتخاب زودتر، به سبک نقشه جدید برای پلتفرم Google Maps مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

نمای کلی

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

یک کلید جدید دریافت کنید. Maps JavaScript API اکنون از Google Cloud Console برای مدیریت کلیدها استفاده می کند. اگر همچنان از کلید v2 استفاده می کنید، قبل از شروع مهاجرت، حتما کلید API جدید خود را دریافت کنید.
API Bootstrap خود را به روز کنید. اکثر برنامه ها Maps JavaScript API v3 را با کد زیر بارگذاری می کنند:
```
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
```
کد خود را به روز کنید مقدار تغییر مورد نیاز بستگی زیادی به درخواست شما دارد. تغییرات رایج عبارتند از:
- همیشه به فضای نام google.maps ارجاع دهید. در نسخه 3، تمام کدهای Maps JavaScript API در فضای نام google.maps.* به جای فضای نام جهانی ذخیره می شود. اکثر اشیا نیز به عنوان بخشی از این فرآیند تغییر نام داده اند. به عنوان مثال، به جای GMap2 ، اکنون google.maps.Map بارگیری خواهید کرد.
- هرگونه ارجاع به روش های منسوخ را حذف کنید. تعدادی از روش‌های کاربردی عمومی حذف شده‌اند، مانند GDownloadURL و GLog . یا این قابلیت را با کتابخانه های ابزار شخص ثالث جایگزین کنید یا این مراجع را از کد خود حذف کنید.
- (اختیاری) کتابخانه ها را به کد خود اضافه کنید. بسیاری از ویژگی‌ها به کتابخانه‌های ابزار خارجی تبدیل شده‌اند، به طوری که هر برنامه فقط باید قسمت‌هایی از API را که مورد استفاده قرار می‌گیرد بارگیری کند.
- (اختیاری) پروژه خود را برای استفاده از خارجی های v3 پیکربندی کنید. خارجی‌های v3 می‌توانند برای کمک به اعتبارسنجی کد شما با Closure Compiler یا برای فعال کردن تکمیل خودکار در IDE شما استفاده شوند. درباره کامپایل پیشرفته و خارجی بیشتر بیاموزید.
تست و تکرار کنید. در این مرحله شما هنوز مقداری کار برای انجام خواهید داشت، اما خبر خوب این است که به خوبی در مسیر برنامه جدید نقشه های 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 ارتقا دهید، که:

به شما این امکان را می دهد که استفاده از API خود را در Google Cloud Console نظارت کنید .
به شما امکان می دهد در صورت لزوم سهمیه اضافی خریداری کنید .
به Google راهی برای تماس با شما در مورد برنامه خود بدهید.

هنگام بارگیری 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 هستید، باید تغییرات زیر را اعمال کنید:

API را از //maps.googleapis.com/maps/api/js بارگیری کنید
پارامتر file حذف کنید.
پارامتر key را با کلید v3 جدید خود به روز کنید. مشتریان Google Maps APIs for Work باید از پارامتر client استفاده کنند.
(فقط طرح ممتاز پلتفرم Google Maps) اطمینان حاصل کنید که پارامتر client همانطور که در راهنمای برنامه‌نویس برنامه Google Maps Platform Premium توضیح داده شده است، ارائه شده است.
برای درخواست آخرین نسخه منتشر شده، پارامتر v را حذف کنید یا مقدار آن را مطابق با طرح نسخه سازی v3 تغییر دهید.
(اختیاری) پارامتر hl با language جایگزین کنید و مقدار آن را حفظ کنید.
(اختیاری) برای بارگیری کتابخانه های اختیاری، پارامتر 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 استفاده شده است، است، اگرچه بسیاری از موارد در زیر هود تغییر کرده است.

رویداد جدید برای پشتیبانی MVC

v3 API نوع جدیدی از رویداد را اضافه می کند تا تغییرات حالت MVC را منعکس کند. در حال حاضر دو نوع رویداد وجود دارد:

رویدادهای کاربر (مانند رویدادهای "کلیک" ماوس) از DOM به Maps JavaScript API منتشر می شوند. این رویدادها جدا و متمایز از رویدادهای استاندارد DOM هستند.
اعلان‌های تغییر حالت MVC تغییرات در اشیاء Maps API را منعکس می‌کنند و با استفاده از یک قرارداد property _changed نام‌گذاری می‌شوند.

هر شی Maps API تعدادی رویداد نامگذاری شده را صادر می کند. برنامه‌هایی که علاقه‌مند به رویدادهای خاص هستند باید شنوندگان رویداد را برای آن رویدادها ثبت کنند و هنگام دریافت آن رویدادها کد را اجرا کنند. این مکانیسم رویداد محور در هر دو Maps JavaScript API v2 و v3 یکسان است، با این تفاوت که فضای نام از 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 به همین ترتیب عمل می کند:

هنگامی که شنونده رویداد ایجاد می کنید، یک شیء مات ( GEventListener در v2، MapsEventListener در v3) برگردانده می شود.
هنگامی که می خواهید شنونده رویداد را حذف کنید، این شی را به متد removeListener() ( GEvent.removeListener() در v2 یا google.maps.event.removeListener() در v3) منتقل کنید تا شنونده رویداد حذف شود.

گوش دادن به رویدادهای DOM

اگر می‌خواهید رویدادهای DOM (مدل شیء سند) را بگیرید و به آنها پاسخ دهید، v3 متد ثابت google.maps.event.addDomListener() را ارائه می‌کند که معادل متد GEvent.addDomListener() در نسخه 2 است.

استفاده از آرگومان های پاس شده در رویدادها

رویدادهای UI اغلب یک آرگومان رویداد را ارسال می کنند که سپس شنونده رویداد می تواند به آن دسترسی داشته باشد. اکثر آرگومان‌های رویداد در v3 ساده‌سازی شده‌اند تا بر روی اشیاء در API سازگارتر باشند. (برای جزئیات به مرجع v3 مراجعه کنید.)

هیچ آرگومان overlay در شنوندگان رویداد v3 وجود ندارد. اگر یک رویداد click روی نقشه نسخه 3 ثبت کنید، پاسخ تماس تنها زمانی اتفاق می‌افتد که کاربر روی نقشه پایه کلیک کند. در صورت نیاز به واکنش به آن کلیک‌ها، می‌توانید تماس‌های اضافی را روی همپوشانی‌های قابل کلیک ثبت کنید.

// 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
  });
});

کنترل ها

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

تغییرات در انواع کنترل

برخی تغییرات در انواع control با API v3 معرفی شده است.

v3 API از انواع نقشه های اضافی از جمله نقشه های زمین و توانایی اضافه کردن انواع نقشه های سفارشی پشتیبانی می کند.
کنترل سلسله مراتبی v2، GHierarchicalMapTypeControl ، دیگر در دسترس نیست. می توانید با استفاده از کنترل google.maps.MapTypeControlStyle.HORIZONTAL_BAR به جلوه مشابهی دست پیدا کنید.
طرح افقی ارائه شده توسط GMapTypeControl در نسخه 2 در نسخه 3 موجود نیست.

افزودن کنترل ها به نقشه

با Maps JavaScript API v2 می‌توانید کنترل‌هایی را از طریق متد 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 بسیار تغییر کرده است. در v2، متد addControl() یک پارامتر دوم اختیاری می گیرد که به شما امکان می دهد موقعیت کنترل را نسبت به گوشه های نقشه مشخص کنید.

در v3، شما موقعیت یک کنترل را از طریق ویژگی position گزینه های کنترل تنظیم می کنید. تعیین موقعیت این کنترل ها مطلق نیست. در عوض، API کنترل‌ها را با «جریان‌دادن» آن‌ها در اطراف عناصر نقشه موجود در محدودیت‌های داده شده (مانند اندازه نقشه) به‌طور هوشمندانه چیدمان می‌کند. این تضمین می کند که کنترل های پیش فرض با کنترل های شما سازگار هستند. برای اطلاعات بیشتر به کنترل موقعیت در نسخه 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 به شما امکان می دهد کنترل های ناوبری سفارشی ایجاد کنید. برای سفارشی‌سازی کنترل‌ها با API v2، کلاس GControl را زیر کلاس می‌دهید و برای متدهای initialize() و getDefaultPosition() هندلرهایی تعریف می‌کنید. هیچ معادلی برای کلاس GControl در نسخه 3 وجود ندارد. در عوض، کنترل ها به عنوان عناصر DOM نشان داده می شوند. برای افزودن یک کنترل سفارشی با v3 API، یک ساختار DOM برای کنترل در سازنده به عنوان فرزند یک Node ایجاد کنید (به عنوان مثال یک عنصر <div> ) و شنوندگان رویداد را برای مدیریت هر رویداد DOM اضافه کنید. Node به آرایه controls[ position ] های نقشه ها فشار دهید تا نمونه ای از کنترل سفارشی را به نقشه خود اضافه کنید.

با توجه به اجرای کلاس HomeControl که به الزامات واسط ذکر شده در بالا پایبند است (برای جزئیات به اسناد Custom Controls مراجعه کنید)، نمونه کد زیر نحوه افزودن یک کنترل سفارشی به نقشه را نشان می دهد.

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);

روکش ها

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

افزودن و حذف روکش ها

انواع اشیاء نشان داده شده توسط یک Overlay بین v2 و v3 یکسان است، با این حال، آنها به طور متفاوتی مدیریت می شوند.

همپوشانی ها در v2 API با استفاده از متدهای addOverlay() و removeOverlay() شی GMap2 به نقشه اضافه و از آن حذف شدند. در نسخه 3، شما یک نقشه را از طریق ویژگی map کلاس گزینه های پوشش مرتبط، به یک Overlay اختصاص می دهید. همچنین می‌توانید مستقیماً با فراخوانی متد setMap() شیء همپوشانی و تعیین نقشه مورد نظر، یک پوشش اضافه یا حذف کنید. با تنظیم ویژگی map روی 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 تصویر سفارشی خود تنظیم کنید و API نماد را به طور خودکار اندازه می‌دهد.

Maps JavaScript API همچنین از نمادهای پیچیده پشتیبانی می کند. یک نماد پیچیده ممکن است شامل چندین کاشی، اشکال پیچیده باشد، یا «ترتیب پشته» نحوه نمایش تصاویر را نسبت به دیگر پوشش‌ها مشخص کند. برای افزودن یک شکل به یک نشانگر در v2، باید ویژگی اضافی را در هر نمونه 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 s، به اضافه یک سری پاره خط تشکیل شده است که آن مکان ها را در یک دنباله مرتب به هم متصل می کند. ایجاد و نمایش یک شی Polyline در v3 شبیه به استفاده از یک شی GPolyline در v2 است. نمونه های زیر یک پلی خط ژئودزیکی نیمه شفاف با عرض 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 مستقیماً از چند خطوط کدگذاری شده وجود ندارد. در عوض، The Geometry Library روش هایی را برای رمزگذاری و رمزگشایی چند خطوط ارائه می دهد. برای اطلاعات بیشتر در مورد نحوه بارگیری این کتابخانه، به کتابخانه ها در v3 Maps API مراجعه کنید.

مثال های زیر همان چند خط کدگذاری شده را ترسیم می کنند. کد v3 از متد 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);

چند ضلعی ها

یک Polygon یک منطقه را در یک حلقه بسته تعریف می کند. مانند شی Polyline ، اشیاء Polygon از یک سری نقاط در یک دنباله مرتب تشکیل شده است. کلاس v3 Polygon تقریباً مشابه کلاس v2 GPolygon است، با این استثنا که دیگر لازم نیست راس شروع را در انتهای مسیر برای بستن حلقه تکرار کنید. v3 API به طور خودکار هر چند ضلعی را با کشیدن یک ضربه که آخرین مختصات را به اولین مختصات متصل می کند، می بندد. تکه‌های کد زیر یک چند ضلعی ایجاد می‌کنند که مثلث برمودا را نشان می‌دهد:

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);

برای قابلیت‌های طراحی پیشرفته‌تر، به کتابخانه طراحی در مستندات v3 مراجعه کنید.

اطلاعات ویندوز

InfoWindow محتوا را در یک پنجره شناور بالای نقشه نمایش می دهد. چند تفاوت کلیدی بین پنجره های اطلاعات v2 و v3 وجود دارد:

API v2 فقط GInfoWindow در هر نقشه پشتیبانی می کند، در حالی که API v3 از چندین InfoWindow همزمان در هر نقشه پشتیبانی می کند.
هنگامی که روی نقشه کلیک می کنید، InfoWindow v3 باز می ماند. وقتی روی نقشه کلیک می‌کنید GInfoWindow v2 به‌طور خودکار بسته می‌شود. می‌توانید با افزودن یک click شنونده روی شی Map ، رفتار v2 را شبیه‌سازی کنید.
v3 API پشتیبانی بومی برای InfoWindow برگه دار ارائه نمی دهد.

پوشش های زمینی

برای قرار دادن یک تصویر روی نقشه، باید از یک شی GroundOverlay استفاده کنید. سازنده برای GroundOverlay اساساً در v2 و v3 یکسان است: 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 کمی متفاوت هستند، اما همه انواع نقشه های اصلی در هر دو نسخه API موجود هستند. به‌طور پیش‌فرض، v2 از کاشی‌های نقشه راه استاندارد «رنگ‌شده» استفاده می‌کند. با این حال، v3 نیاز به یک نوع نقشه خاص برای ایجاد یک شی 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 ) یک نقشه فیزیکی را بر اساس اطلاعات زمین نمایش می دهد.

در زیر نمونه ای از v2 و v3 است که نقشه را برای نمای زمین تنظیم می کند:

map.setMapType(G_PHYSICAL_MAP);

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);

Maps JavaScript API v3 نیز تغییراتی را در انواع نقشه های کمتر رایج ایجاد کرد:

کاشی‌های نقشه برای اجرام آسمانی غیر از زمین به‌عنوان انواع نقشه در API v3 در دسترس نیستند، اما همانطور که در این مثال نشان داده شده است، می‌توان به‌عنوان انواع نقشه‌های سفارشی به آن‌ها دسترسی داشت.
هیچ نوع نقشه خاصی در نسخه 3 وجود ندارد که جایگزین نوع G_SATELLITE_3D_MAP از نسخه 2 شود. در عوض، می‌توانید با استفاده از این کتابخانه ، افزونه Google Earth را در نقشه‌های نسخه 3 خود ادغام کنید.

حداکثر زوم تصاویر

تصاویر ماهواره ای همیشه در سطوح زوم بالا در دسترس نیستند. اگر ممکن است بخواهید قبل از تنظیم سطح بزرگنمایی، بالاترین سطح بزرگنمایی موجود را بدانید، از کلاس google.maps.MaxZoomService استفاده کنید. این کلاس جایگزین متد GMapType.getMaxZoomAtLatLng() از v2 می شود.

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، کنترل‌ها مشابه کنترل v2 GLargeZoomControl3D هستند، با یک کنترل چرخش بینابینی اضافی برای چرخش در جهت‌های پشتیبانی‌شده.

می‌توانید شهرهایی را که در حال حاضر تصاویر 45 درجه در آن‌ها موجود است، در این نقشه ردیابی کنید. هنگامی که تصاویر 45 درجه در دسترس است، یک گزینه از منوی فرعی به دکمه Maps API Satellite اضافه می شود.

لایه ها

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

لایه های پشتیبانی شده

v3 API دسترسی به چندین لایه مختلف را فراهم می کند. این لایه ها در قسمت های زیر با کلاس v2 GLayer همپوشانی دارند:

شی KmlLayer عناصر KML و GeoRSS را به روکش‌های v3 تبدیل می‌کند و معادل لایه GeoXml v2 را ارائه می‌کند.
شی TrafficLayer لایه ای را ارائه می دهد که شرایط ترافیک را نشان می دهد، شبیه به پوشش v2 GTrafficOverlay .

این لایه ها با v2 متفاوت هستند. تفاوت ها در زیر توضیح داده شده است. آنها را می توان با فراخوانی setMap() به نقشه اضافه کرد و شی Map را برای نمایش لایه ارسال کرد.

اطلاعات بیشتر در مورد لایه های پشتیبانی شده در مستندات لایه ها موجود است.

لایه های KML و GeoRSS

Maps JavaScript API از فرمت های داده های KML و GeoRSS برای نمایش اطلاعات جغرافیایی پشتیبانی می کند. اگر می‌خواهید فایل‌های KML یا GeoRSS را در نقشه قرار دهید، باید در دسترس عموم قرار گیرند. در نسخه 3، این فرمت های داده با استفاده از نمونه ای از KmlLayer نمایش داده می شوند که جایگزین شی GGeoXml از v2 می شود.

v3 API هنگام رندر KML انعطاف پذیرتر است و به شما امکان می دهد InfoWindows را سرکوب کنید و پاسخ کلیک را تغییر دهید. برای جزئیات بیشتر به مستندات V3 KML و GeoRSS Layers مراجعه کنید.

هنگام ارائه یک 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);

لایه ترافیک

v3 به شما امکان می دهد تا با استفاده از شی 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);

برخلاف v2، هیچ گزینه ای برای سازنده TrafficLayer در v3 وجود ندارد. حوادث در نسخه 3 در دسترس نیستند.

خدمات

ژئوکدینگ

Maps JavaScript API یک شی geocoder برای geocoding آدرس ها به صورت پویا از ورودی کاربر فراهم می کند. اگر می خواهید آدرس های ثابت و شناخته شده را به صورت جغرافیایی کدگذاری کنید، به مستندات API Geocoding مراجعه کنید.

Geocoding API به طور قابل توجهی ارتقا یافته و بهبود یافته است و ویژگی‌های جدیدی اضافه کرده و نحوه نمایش داده‌ها را تغییر داده است.

GClientGeocoder در v2 API دو روش مختلف برای geocoding رو به جلو و معکوس و همچنین روش های اضافی برای تأثیرگذاری بر نحوه انجام geocoding ارائه کرد. در مقابل، شئ v3 Geocoder تنها یک متد geocode() ارائه می‌کند، که یک شی را به صورت تحت اللفظی شامل عبارت‌های ورودی (به شکل یک شی درخواست‌های جغرافیایی ) و یک متد برگشت فراخوان می‌گیرد. بسته به اینکه درخواست حاوی یک ویژگی address متنی یا یک شی LatLng باشد، API Geocoding یک پاسخ کدگذاری جغرافیایی رو به جلو یا معکوس را برمی‌گرداند. شما می توانید با ارسال فیلدهای اضافی به درخواست geocoding بر نحوه انجام geocoding تأثیر بگذارید:

گنجاندن یک address متنی، رمزگذاری جغرافیایی رو به جلو، معادل فراخوانی متد getLatLng() راه‌اندازی می‌کند.
گنجاندن یک شی latLng باعث ایجاد geocoding معکوس می شود که معادل فراخوانی متد getLocations() .
شامل کردن ویژگی bounds ، Viewport Biasing را فعال می‌کند، که معادل فراخوانی متد setViewport() .
شامل کردن ویژگی region ، منطقه کد بایاس را فعال می کند، که معادل فراخوانی متد setBaseCountryCode() .

پاسخ های کدگذاری جغرافیایی در v3 بسیار متفاوت از پاسخ های v2 هستند. v3 API ساختار تودرتویی را که v2 استفاده می‌کند با ساختار صاف‌تری جایگزین می‌کند که تجزیه آسان‌تر است. علاوه بر این، پاسخ‌های v3 جزئیات بیشتری دارند: هر نتیجه دارای چندین مؤلفه آدرس است که به ارائه ایده بهتر از وضوح هر نتیجه کمک می‌کند.

کد زیر یک آدرس متنی می گیرد و اولین نتیجه از کدگذاری جغرافیایی آن را نشان می دهد:

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');
}

مسیرها

Maps JavaScript API v3 کلاس GDirections از v2 را با کلاس DirectionsService برای محاسبه جهت ها جایگزین می کند.

متد route() در v3 جایگزین متد load() و loadFromWaypoints() از API v2 می شود. این روش یک شی DirectionsRequest را به صورت تحت اللفظی می گیرد که شامل عبارت های ورودی و یک متد برگشت به تماس است تا پس از دریافت پاسخ اجرا شود. گزینه‌ها ممکن است در این شی به معنای واقعی کلمه داده شوند، مشابه شیء GDirectionsOptions در v2.

در Maps JavaScript API v3، وظیفه ارسال درخواست‌های جهت از وظیفه ارائه درخواست‌ها جدا شده است، که اکنون با کلاس DirectionsRenderer انجام می‌شود. شما می توانید یک شی DirectionsRenderer را از طریق متدهای setMap() و setDirections() به هر نقشه یا شی DirectionsResult گره بزنید. از آنجایی که رندر یک MVCObject است، هر گونه تغییر در ویژگی های آن را شناسایی می کند و زمانی که جهت های مرتبط تغییر کرد، نقشه را به روز می کند.

کد زیر نحوه درخواست مسیرهای پیاده روی به یک مکان خاص را با استفاده از مسیرهای عابر پیاده از یک آدرس نشان می دهد. توجه داشته باشید که فقط v3 قادر به ارائه مسیرهای پیاده روی در مسیر پیاده روی باغ وحش دوبلین است.

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);
    }
  });
}

نمای خیابان

نمای خیابان گوگل نماهای تعاملی 360 درجه را از مکان های تعیین شده در محدوده تحت پوشش خود ارائه می دهد. API v3 به طور بومی از نمای خیابان در مرورگر پشتیبانی می کند، برخلاف v2 که برای نمایش تصاویر نمای خیابان به پلاگین Flash® نیاز داشت.

تصاویر نمای خیابان از طریق استفاده از شی StreetViewPanorama در نسخه 3 یا شیء GStreetviewPanorama در نسخه 2 پشتیبانی می شوند. این کلاس‌ها رابط‌های متفاوتی دارند، اما نقش یکسانی دارند: اتصال ظرف div با تصاویر نمای خیابان و به شما امکان تعیین مکان و POV (نقطه دید) پانورامای نمای خیابان.

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);
}

دسترسی مستقیم به داده های Street View از طریق شی StreetViewService در نسخه 3 یا شیء مشابه GStreetviewClient در نسخه 2 امکان پذیر است. هر دو رابط‌های مشابهی برای بازیابی یا بررسی در دسترس بودن داده‌های نمای خیابان ارائه می‌کنند و امکان جستجو بر اساس مکان یا شناسه پانوراما را فراهم می‌کنند.

در نسخه 3، نمای خیابان به طور پیش فرض فعال است. نقشه با یک کنترل آدمک نمای خیابان ظاهر می شود و API از div نقشه برای نمایش پانورامای StreetView استفاده مجدد می کند. کد زیر نحوه شبیه‌سازی رفتار v2 را با جدا کردن پانوراماهای نمای خیابان در یک بخش جداگانه نشان می‌دهد.

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);
}

نمای کلی

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

یک کلید جدید دریافت کنید. Maps JavaScript API اکنون از Google Cloud Console برای مدیریت کلیدها استفاده می کند. اگر همچنان از کلید v2 استفاده می کنید، قبل از شروع مهاجرت، حتما کلید API جدید خود را دریافت کنید.
API Bootstrap خود را به روز کنید. اکثر برنامه ها Maps JavaScript API v3 را با کد زیر بارگذاری می کنند:
```
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
```
کد خود را به روز کنید مقدار تغییر مورد نیاز بستگی زیادی به درخواست شما دارد. تغییرات رایج عبارتند از:
- همیشه به فضای نام google.maps ارجاع دهید. در نسخه 3، تمام کدهای Maps JavaScript API در فضای نام google.maps.* به جای فضای نام جهانی ذخیره می شود. اکثر اشیا نیز به عنوان بخشی از این فرآیند تغییر نام داده اند. به عنوان مثال، به جای GMap2 ، اکنون google.maps.Map بارگیری خواهید کرد.
- هرگونه ارجاع به روش های منسوخ را حذف کنید. تعدادی از روش‌های کاربردی عمومی حذف شده‌اند، مانند GDownloadURL و GLog . یا این قابلیت را با کتابخانه های ابزار شخص ثالث جایگزین کنید یا این مراجع را از کد خود حذف کنید.
- (اختیاری) کتابخانه ها را به کد خود اضافه کنید. بسیاری از ویژگی‌ها به کتابخانه‌های ابزار خارجی تبدیل شده‌اند، به طوری که هر برنامه فقط باید قسمت‌هایی از API را که مورد استفاده قرار می‌گیرد بارگیری کند.
- (اختیاری) پروژه خود را برای استفاده از خارجی های v3 پیکربندی کنید. خارجی‌های v3 می‌توانند برای کمک به اعتبارسنجی کد شما با Closure Compiler یا برای فعال کردن تکمیل خودکار در IDE شما استفاده شوند. درباره کامپایل پیشرفته و خارجی بیشتر بیاموزید.
تست و تکرار کنید. در این مرحله شما هنوز مقداری کار برای انجام خواهید داشت، اما خبر خوب این است که به خوبی در مسیر برنامه جدید نقشه های v3 خود خواهید بود!

تغییرات در V3 از Maps JavaScript 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 ارتقا دهید ، که این امر خواهد بود:

به شما امکان می دهد تا استفاده از API خود را در کنسول Google Cloud نظارت کنید .
به شما امکان می دهد در صورت لزوم سهمیه اضافی خریداری کنید .
راهی به Google بدهید تا در مورد برنامه خود با شما تماس بگیرد.

کلید هنگام بارگیری نقشه های 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 هستید ، باید تغییرات زیر را ایجاد کنید:

API را از //maps.googleapis.com/maps/api/js بارگیری کنید
پارامتر file حذف کنید.
پارامتر key را با کلید V3 جدید خود به روز کنید. Google Maps API برای کار مشتریان باید از یک پارامتر client استفاده کند.
(Google Maps Maps Platform فقط برنامه حق بیمه) اطمینان حاصل کنید که پارامتر client همانطور که در راهنمای توسعه دهنده برنامه PLAMIUM PLAMIUM PLATOM PLATOM PLATFORM توضیح داده شده است ، تهیه می شود.
پارامتر v را حذف کنید تا آخرین نسخه منتشر شده را درخواست کنید یا مقدار آن را مطابق با طرح نسخه V3 تغییر دهید.
(اختیاری) پارامتر hl را با language جایگزین کنید و مقدار آن را حفظ کنید.
(اختیاری) برای بارگذاری کتابخانه های اختیاری یک پارامتر 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 است ، اگرچه در زیر کاپوت بسیار تغییر کرده است.

رویداد جدید برای پشتیبانی MVC

V3 API نوع جدیدی از رویداد را برای منعکس کننده تغییرات حالت MVC اضافه می کند. اکنون دو نوع رویداد وجود دارد:

رویدادهای کاربر (مانند رویدادهای ماوس "کلیک") از DOM به نقشه های JavaScript API پخش می شوند. این رویدادها جدا و متمایز از رویدادهای استاندارد DOM هستند.
اعلان های تغییر حالت MVC منعکس کننده تغییرات در اشیاء API MAPS هستند و با استفاده از یک کنوانسیون property _changed نامگذاری شده اند.

هر شیء نقشه API تعدادی از رویدادهای نامگذاری شده را صادر می کند. برنامه های علاقمند به رویدادهای خاص باید شنوندگان رویداد را برای آن رویدادها ثبت کنند و هنگام دریافت این رویدادها کد را اجرا کنند. این مکانیسم رویداد محور در هر دو نقشه JavaScript API V2 و V3 یکسان است ، به جز این که فضای نام از 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.');
});

حذف شنوندگان رویداد

به دلایل عملکرد ، بهتر است وقتی دیگر نیازی به آن نیست ، شنونده رویداد را حذف کنید. حذف یک شنونده رویداد به همان روش در V2 و V3 کار می کند:

هنگامی که شما یک شنونده رویداد ایجاد می کنید ، یک شیء مات ( GeventListener در V2 ، MapSeventListener در V3) بازگردانده می شود.
هنگامی که می خواهید شنونده رویداد را حذف کنید ، این شی را به روش removeListener() ( GEvent.removeListener() در v2 یا google.maps.event.removeListener() در v3) منتقل کنید تا شنونده رویداد را حذف کنید.

گوش دادن به رویدادهای DOM

اگر می خواهید رویدادهای DOM (مدل شیء اسناد) را ضبط و پاسخ دهید ، V3 روش استاتیک google.maps.event.addDomListener() را ارائه می دهد ، معادل روش GEvent.addDomListener() در v2.

با استفاده از استدلال های تصویب شده در رویدادها

رویدادهای UI اغلب یک آرگومان رویداد را تصویب می کنند که می تواند توسط شنونده رویداد قابل دسترسی باشد. بیشتر استدلال های رویداد در V3 ساده تر شده است تا نسبت به اشیاء موجود در API سازگارتر باشد. (برای جزئیات بیشتر با مرجع V3 مشورت کنید.)

هیچ استدلال overlay در شنوندگان رویداد V3 وجود ندارد. اگر یک رویداد click بر روی نقشه V3 ثبت کنید ، پاسخ به تماس فقط زمانی رخ می دهد که کاربر روی نقشه پایه کلیک کند. در صورت نیاز به واکنش به این کلیک ها ، می توانید تماس های اضافی را در پوشش های قابل کلیک ثبت کنید.

// 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 API کنترل های UI را نشان می دهد که به کاربران امکان تعامل با نقشه شما را می دهد. می توانید از API برای سفارشی کردن نحوه ظاهر این کنترل ها استفاده کنید.

تغییر در انواع کنترل

برخی از تغییرات در انواع control با API V3 معرفی شده است.

V3 API از انواع نقشه های اضافی از جمله نقشه های زمین و امکان اضافه کردن انواع نقشه های سفارشی پشتیبانی می کند.
کنترل سلسله مراتبی V2 ، GHierarchicalMapTypeControl ، دیگر در دسترس نیست. با استفاده از کنترل google.maps.MapTypeControlStyle.HORIZONTAL_BAR می توانید به یک اثر مشابه دست پیدا کنید.
طرح افقی ارائه شده توسط GMapTypeControl در V2 در V3 موجود نیست.

افزودن کنترل به نقشه

با استفاده از MAPS JavaScript API V2 ، از طریق روش addControl() شیء نقشه خود ، کنترل های خود را به نقشه خود اضافه می کنید. در V3 ، به جای دسترسی یا اصلاح مستقیم کنترل ، شما شیء 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);

کنترل های موقعیت یابی روی نقشه

کنترل های موقعیت یابی در V3 بسیار تغییر کرده است. در V2 ، روش addControl() یک پارامتر دوم اختیاری را می گیرد که به شما امکان می دهد موقعیت کنترل را نسبت به گوشه های نقشه مشخص کنید.

در V3 ، موقعیت یک کنترل را از طریق ویژگی position گزینه های کنترل تنظیم می کنید. موقعیت این کنترل ها مطلق نیست ؛ در عوض ، API با "جاری شدن" آنها در اطراف عناصر نقشه موجود در محدودیت های داده شده (مانند اندازه نقشه) ، کنترل ها را به صورت هوشمندانه تنظیم می کند. این تضمین می کند که کنترل های پیش فرض با کنترل های شما سازگار هستند. برای اطلاعات بیشتر به موقعیت کنترل در V3 مراجعه کنید.

موضع گیری مجدد کد زیر از نمونه های فوق کنترل می کند:

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);

کنترل های سفارشی

نقشه های JavaScript API به شما امکان می دهد کنترل های پیمایشی سفارشی ایجاد کنید. برای سفارشی سازی کنترل ها با API V2 ، کلاس GControl را زیر طبقه بندی می کنید و دستگیرندگان را برای initialize() و getDefaultPosition() تعریف می کنید. هیچ معادل کلاس GControl در V3 وجود ندارد. در عوض ، کنترل ها به عنوان عناصر DOM نشان داده می شوند. برای اضافه کردن یک کنترل سفارشی با V3 API ، یک ساختار 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);

روکش ها

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

افزودن و حذف روکش ها

انواع اشیاء نشان داده شده توسط یک پوشش بین V2 و V3 یکسان هستند ، با این حال ، آنها به طور متفاوتی اداره می شوند.

روکش های موجود در API V2 با استفاده از MAP با استفاده از روش های addOverlay() و removeOverlay() روشهای GMap2 به نقشه اضافه و حذف شدند. در V3 ، شما یک نقشه را از طریق ویژگی map کلاس گزینه های Overlay Assocray به یک پوشش اختصاص می دهید. همچنین می توانید با فراخوانی روش setMap() شیء Overlay و مشخص کردن نقشه مورد نظر ، یک پوشش را مستقیماً اضافه یا حذف کنید. تنظیم ویژگی MAP به null پوشش را حذف می کند.

هیچ روش clearOverlays() در V3 وجود ندارد. اگر می خواهید مجموعه ای از پوشش ها را مدیریت کنید ، باید یک آرایه برای نگه داشتن پوشش ها ایجاد کنید. با استفاده از این آرایه ، می توانید 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
});

نمادها

می توانید یک نماد سفارشی را برای نشان دادن به جای نشانگر پیش فرض تعریف کنید. برای استفاده از یک تصویر سفارشی در V2 ، می توانید یک نمونه GIcon از G_DEFAULT_ICON type ایجاد کرده و آن را تغییر دهید. اگر تصویر شما بزرگتر یا کوچکتر از نماد پیش فرض است ، باید آن را با یک نمونه GSize مشخص کنید. API V3 این روند را کمی ساده می کند. به سادگی ویژگی icon نشانگر را روی URL تصویر سفارشی خود تنظیم کنید و API به طور خودکار نماد را اندازه می گیرد.

نقشه های JavaScript API همچنین از نمادهای پیچیده پشتیبانی می کند. یک نماد پیچیده ممکن است شامل چندین کاشی ، اشکال پیچیده باشد ، یا "ترتیب پشته" نحوه نمایش تصاویر را نسبت به سایر پوشش ها مشخص کند. برای افزودن یک شکل به یک نشانگر در V2 ، باید خاصیت اضافی را در هر نمونه GIcon مشخص کنید و این را به عنوان گزینه ای برای سازنده GMarker منتقل کنید. در V3 ، نمادهای مشخص شده به این روش باید خصوصیات icon خود را بر روی یک شی از نوع Icon تنظیم کنند. سایه های نشانگر در V3 پشتیبانی نمی شوند.

مثالهای زیر پرچم ساحلی را در Bondi Beach در استرالیا نشان می دهد ، در حالی که قسمت شفاف نماد قابل کلیک نیست:

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 S ، به علاوه مجموعه ای از بخش های خط است که آن مکان ها را به یک دنباله سفارش داده شده متصل می کند. ایجاد و نمایش یک شیء Polyline در V3 شبیه به استفاده از یک شیء GPolyline در V2 است. نمونه های زیر یک پلی خط ژئودزیک نیمه شفاف ، 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);

پولیلین های رمزگذاری شده

در V3 برای ایجاد اشیاء Polyline مستقیم از پولیلین های رمزگذاری شده هیچ گونه پشتیبانی وجود ندارد. در عوض ، کتابخانه هندسه روش هایی برای رمزگذاری و رمزگشایی پولیلین ها فراهم می کند. برای کسب اطلاعات بیشتر در مورد نحوه بارگیری این کتابخانه ، به کتابخانه ها در API نقشه های V3 مراجعه کنید.

مثالهای زیر همان پلی خط رمزگذاری شده را ترسیم می کنند. کد V3 از روش 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 V3 تقریباً مشابه کلاس GPolygon V2 است ، با این استثناء قابل توجه که دیگر نیازی به تکرار راس شروع در انتهای مسیر برای بستن حلقه نیست. V3 API با کشیدن سکته مغزی که آخرین مختصات را به اولین مختصات متصل می کند ، به طور خودکار هر چند ضلعی را می بندد. قطعه کد زیر چند ضلعی ایجاد می کند که نمایانگر مثلث برمودا است:

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);

برای قابلیت های پیشرفته تر طراحی ، به کتابخانه نقاشی در مستندات V3 مراجعه کنید.

اطلاعات ویندوز

یک InfoWindow محتوا را در یک پنجره شناور بالای نقشه نشان می دهد. چند تفاوت اساسی بین ویندوزهای اطلاعات V2 و V3 وجود دارد:

V2 API فقط GInfoWindow در هر نقشه پشتیبانی می کند ، در حالی که API V3 از چندین و InfoWindow همزمان در هر نقشه پشتیبانی می کند.
V3 InfoWindow هنگام کلیک بر روی نقشه باز خواهد ماند. V2 GInfoWindow هنگام کلیک بر روی نقشه به طور خودکار بسته می شود. می توانید با اضافه کردن یک شنونده click روی شیء Map ، رفتار V2 را تقلید کنید.
API V3 پشتیبانی بومی را برای یک InfoWindow زبانه فراهم نمی کند.

پوشش زمینی

برای قرار دادن یک تصویر روی نقشه ، باید از یک شیء GroundOverlay استفاده کنید. سازنده یک GroundOverlay در اصل در V2 و V3 یکسان است: URL یک تصویر و مرزهای تصویر را به عنوان پارامترها مشخص می کند.

مثال زیر نقشه عتیقه ای از Newark ، NJ را روی نقشه به عنوان یک پوشش قرار می دهد:

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);

انواع نقشه

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

انواع نقشه مشترک

چهار نوع نقشه اصلی در هر دو V2 و V3 موجود است:

MapTypeId.ROADMAP (جایگزین G_NORMAL_MAP ) نمای نقشه راه را نشان می دهد.
MapTypeId.SATELLITE (جایگزین G_SATELLITE_MAP ) تصاویر ماهواره ای Google Earth.
MapTypeId.HYBRID (جایگزین G_HYBRID_MAP ) ترکیبی از نماهای طبیعی و ماهواره ای را نشان می دهد.
MapTypeId.TERRAIN (جایگزین G_PHYSICAL_MAP ) نقشه فیزیکی را بر اساس اطلاعات زمین نمایش می دهد.

در زیر نمونه ای از V2 و V3 تنظیم نقشه به Terrain View:

map.setMapType(G_PHYSICAL_MAP);

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);

Maps JavaScript API V3 چند تغییر در انواع نقشه های کمتر متداول نیز ایجاد کرد:

کاشی های نقشه برای اجسام آسمانی غیر از زمین به عنوان انواع نقشه در API V3 در دسترس نیستند ، اما همانطور که در این مثال نشان داده شده است می توانید به عنوان انواع نقشه های سفارشی دسترسی پیدا کنید.
هیچ نوع نقشه خاصی در V3 وجود ندارد که جایگزین نوع G_SATELLITE_3D_MAP از V2 شود. در عوض ، می توانید با استفاده از این کتابخانه ، افزونه Google Earth را در نقشه های V3 خود ادغام کنید.

حداکثر تصاویر بزرگنمایی

تصاویر ماهواره ای همیشه در سطح بزرگنمایی بالا موجود نیست. اگر ممکن است قبل از تعیین سطح زوم ، بالاترین سطح بزرگنمایی موجود را بدانید ، از کلاس google.maps.MaxZoomService استفاده کنید. این کلاس جایگزین روش GMapType.getMaxZoomAtLatLng() از V2 می شود.

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.");
    }
});

تصاویر چشم انداز هوایی

هنگام فعال کردن تصاویر هوایی در V3 ، کنترل ها مشابه کنترل V2 GLargeZoomControl3D هستند ، با یک کنترل چرخش بینابینی اضافی برای چرخش از طریق جهت های پشتیبانی شده.

شما می توانید شهرهایی را که در آن تصاویر 45 درجه در حال حاضر در این نقشه موجود است ، ردیابی کنید. هنگامی که تصاویر 45 درجه در دسترس است ، گزینه زیرمنو به دکمه ماهواره API MAPS اضافه می شود.

لایه ها

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

لایه های پشتیبانی شده

V3 API دسترسی به چندین لایه مختلف را فراهم می کند. این لایه ها با کلاس GLayer V2 در مناطق زیر همپوشانی دارند:

شیء KmlLayer عناصر KML و Georss را به پوشش V3 تبدیل می کند و معادل آن برای لایه GeoXml V2 را فراهم می کند.
شیء TrafficLayer لایه ای را نشان می دهد که شرایط ترافیکی را نشان می دهد ، مشابه پوشش V2 GTrafficOverlay .

این لایه ها با V2 متفاوت است. تفاوت ها در زیر توضیح داده شده است. آنها را می توان با فراخوانی setMap() به نقشه اضافه کرد و از آن به عنوان Map برای نمایش لایه عبور کرد.

اطلاعات بیشتر در مورد لایه های پشتیبانی شده در مستندات Layers در دسترس است.

لایه های KML و Georss

نقشه های JavaScript API از قالب های داده KML و Georss برای نمایش اطلاعات جغرافیایی پشتیبانی می کند. اگر می خواهید آنها را در نقشه قرار دهید ، پرونده های KML یا Georss باید در دسترس عموم باشند. در V3 ، این قالبهای داده با استفاده از نمونه ای از KmlLayer نمایش داده می شوند ، که جایگزین جسم GGeoXml از V2 می شود.

API V3 هنگام ارائه KML انعطاف پذیرتر است و به شما امکان می دهد تا infowindows را سرکوب کرده و پاسخ کلیک را تغییر دهید. برای جزئیات بیشتر ، مستندات لایه های V3 KML و Georss را ببینید.

هنگام ارائه 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);

لایه ترافیک

V3 به شما امکان می دهد تا با استفاده از شیء 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);

بر خلاف V2 ، هیچ گزینه ای برای سازنده TrafficLayer در V3 وجود ندارد. حوادث در V3 در دسترس نیست.

خدمات

ژئوکدینگ

MAPS JavaScript API یک شیء geocoder را برای آدرس های GeoCoding به صورت پویا از ورودی کاربر فراهم می کند. اگر می خواهید آدرس های شناخته شده GeoCode ، معروف ، به اسناد API GeoCoding مراجعه کنید.

API GeoCoding به طور قابل توجهی به روز شده و بهبود یافته است و ویژگی های جدید را اضافه می کند و نحوه نمایش داده ها را تغییر می دهد.

GClientGeocoder در API V2 دو روش مختلف برای جغرافیایی رو به جلو و معکوس و همچنین روشهای اضافی برای تأثیرگذاری بر نحوه انجام جغرافیایی فراهم کرد. در مقابل ، شیء Geocoder V3 فقط یک روش geocode() را ارائه می دهد ، که یک شیء تحت اللفظی را شامل می شود که شامل اصطلاحات ورودی (به شکل یک شیء درخواست های GeoCoding ) و یک روش پاسخ به تماس است. بسته به اینکه این درخواست حاوی یک ویژگی address متنی یا یک شیء LatLng باشد ، API GeoCoding یک پاسخ geoCoding رو به جلو یا معکوس را برمی گرداند. شما می توانید با انتقال زمینه های اضافی به درخواست GeoCoding ، بر نحوه انجام GeoCoding تأثیر بگذارید:

از جمله address متنی ، جغرافیایی را به جلو ، معادل فراخوانی روش getLatLng() ایجاد می کند.
از جمله یک شیء latLng باعث ایجاد جغرافیایی معکوس ، معادل فراخوانی روش getLocations() می شود.
از جمله ویژگی bounds ، تعصب بینش را امکان پذیر می کند ، معادل تماس با روش setViewport() .
از جمله ویژگی region ، تعصب کد منطقه را امکان پذیر می کند ، معادل فراخوانی روش setBaseCountryCode() .

پاسخ های GeoCoding در V3 با پاسخ های V2 بسیار متفاوت است. V3 API جایگزین ساختار تو در تو است که V2 با یک ساختار مسطح تر از آن استفاده می کند که تجزیه آن آسان تر است. علاوه بر این ، پاسخ های V3 مفصل تر است: هر نتیجه دارای چندین مؤلفه آدرس است که به ایده بهتری از وضوح هر نتیجه کمک می کند.

کد زیر یک آدرس متنی می گیرد و اولین نتیجه را از Geocoding IT نشان می دهد:

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');
}

جهت

نقشه های JavaScript API V3 جایگزین کلاس GDirections از V2 با کلاس DirectionsService برای محاسبه جهت ها می شود.

روش route() در V3 هر دو روش load() و loadFromWaypoints() را از API V2 جایگزین می کند. این روش به معنای واقعی کلمه یک شیء DirectionsRequest است که حاوی اصطلاحات ورودی و یک روش پاسخ به تماس برای اجرای پس از دریافت پاسخ است. گزینه ها ممکن است در این شیء تحت اللفظی ، مشابه با شیء GDirectionsOptions در V2 ارائه شود.

در نقشه های JavaScript API V3 ، وظیفه ارسال درخواست های جهت از وظیفه ارائه درخواست ها جدا شده است ، که اکنون با کلاس DirectionsRenderer اداره می شود. شما می توانید از طریق روش های setMap() و setDirections() آن ، یک شیء DirectionsRenderer را با هر نقشه یا شیء DirectionsResult گره بزنید. از آنجا که Renderer یک MVCObject است ، هرگونه تغییر در خصوصیات خود را تشخیص می دهد و هنگام تغییر جهت های مرتبط ، نقشه را به روز می کند.

کد زیر نحوه درخواست مسیرهای پیاده روی به یک مکان خاص را با استفاده از مسیرهای عابر پیاده از یک آدرس نشان می دهد. توجه داشته باشید که فقط V3 قادر به ارائه مسیرهای پیاده روی در مسیر عابر پیاده در باغ وحش دوبلین است.

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 Street View نمای تعاملی و 360 درجه ای را از مکان های تعیین شده در منطقه پوشش خود ارائه می دهد. V3 API بر خلاف V2 که به افزونه Flash® نیاز داشت تا تصاویر نمای خیابان را به نمایش بگذارد ، از نمای خیابان به طور بومی در مرورگر پشتیبانی می کند.

تصاویر نمای خیابان با استفاده از شیء StreetViewPanorama در V3 یا شیء GStreetviewPanorama در V2 پشتیبانی می شوند. این کلاس ها دارای رابط های مختلفی هستند ، اما آنها همان نقش را بازی می کنند: اتصال کانتینر div با تصاویر نمای خیابان و به شما امکان می دهد مکان و POV (نقطه دید) پانوراما نمای خیابان را مشخص کنید.

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 در V3 یا شیء GStreetviewClient مشابه در V2 امکان پذیر است. هر دو رابط های مشابه برای بازیابی یا بررسی در دسترس بودن داده های نمای خیابان و امکان جستجو بر اساس مکان یا شناسه پانوراما فراهم می کنند.

در V3 ، نمای خیابان به طور پیش فرض فعال است. این نقشه با کنترل Pegman Control در خیابان نمایش داده می شود و API از نقشه DIV استفاده می کند تا Panoramas StreetView را به نمایش بگذارد. کد زیر نحوه تقلید از رفتار V2 را با جدا کردن پانورامای نمای خیابان به یک بخش جداگانه نشان می دهد.

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);
}