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

رویداد جدید برای پشتیبانی 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 به همین ترتیب عمل می کند:

1. هنگامی که شنونده رویداد ایجاد می کنید، یک شیء مات ( GEventListener در v2، MapsEventListener در v3) برگردانده می شود.
2. هنگامی که می خواهید شنونده رویداد را حذف کنید، این شی را به متد 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
  });
});

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

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

1. v3 API از انواع نقشه های اضافی از جمله نقشه های زمین و توانایی اضافه کردن انواع نقشه های سفارشی پشتیبانی می کند.
2. کنترل سلسله مراتبی v2، GHierarchicalMapTypeControl ، دیگر در دسترس نیست. می توانید با استفاده از کنترل google.maps.MapTypeControlStyle.HORIZONTAL_BAR به جلوه مشابهی دست پیدا کنید.
3. طرح افقی ارائه شده توسط 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 موجود است:

• 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 اضافه می شود.