نشانگرها

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت

نشانگرها مکان‌های تکی را روی نقشه نشان می‌دهند.

به طور پیش‌فرض، نشانگرها از یک آیکون استاندارد استفاده می‌کنند که ظاهر و حس رایج نقشه‌های گوگل را دارد. اگر می‌خواهید نشانگر خود را سفارشی کنید، می‌توانید رنگ نشانگر پیش‌فرض را تغییر دهید، یا تصویر نشانگر را با یک آیکون سفارشی جایگزین کنید، یا سایر ویژگی‌های نشانگر را تغییر دهید.

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

اضافه کردن نشانگر

برای افزودن یک نشانگر، یک شیء GMSMarker ایجاد کنید که شامل position و title باشد و map آن را تنظیم کنید.

مثال زیر نحوه اضافه کردن یک نشانگر به یک شیء GMSMapView موجود را نشان می‌دهد. نشانگر در مختصات 10,10 ایجاد می‌شود و با کلیک روی آن، رشته "Hello world" در یک پنجره اطلاعات نمایش داده می‌شود.

سویفت

let position = CLLocationCoordinate2D(latitude: 10, longitude: 10)
let marker = GMSMarker(position: position)
marker.title = "Hello World"
marker.map = mapView
      

هدف-سی

CLLocationCoordinate2D position = CLLocationCoordinate2DMake(10, 10);
GMSMarker *marker = [GMSMarker markerWithPosition:position];
marker.title = @"Hello World";
marker.map = mapView;
      

شما می‌توانید با تنظیم ویژگی marker.appearAnimation به صورت زیر، افزودن نشانگرهای جدید به نقشه را متحرک‌سازی کنید:

• برای اینکه نشانگر هنگام اضافه شدن از groundAnchor خود بیرون بزند، kGMSMarkerAnimationPop کنید.
• برای اینکه نشانگر هنگام اضافه شدن، محو شود، kGMSMarkerAnimationFadeIn استفاده کنید.

حذف یک نشانگر

می‌توانید با تنظیم ویژگی map از GMSMarker به nil ، یک نشانگر را از نقشه حذف کنید. همچنین می‌توانید با فراخوانی متد clear از GMSMapView ، تمام پوشش‌ها (از جمله نشانگرها) که در حال حاضر روی نقشه هستند را حذف کنید.

سویفت

let camera = GMSCameraPosition.camera(
  withLatitude: -33.8683,
  longitude: 151.2086,
  zoom: 6
)
let mapView = GMSMapView.map(withFrame: .zero, camera: camera)
// ...
mapView.clear()
      

هدف-سی

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
// ...
[mapView clear];
      

اگر می‌خواهید پس از افزودن یک نشانگر به نقشه، آن را تغییر دهید، مطمئن شوید که شیء GMSMarker را نگه داشته‌اید. می‌توانید بعداً با ایجاد تغییرات در این شیء، نشانگر را تغییر دهید.

سویفت

let position = CLLocationCoordinate2D(latitude: 10, longitude: 10)
let marker = GMSMarker(position: position)
marker.map = mapView
// ...
marker.map = nil
      

هدف-سی

CLLocationCoordinate2D position = CLLocationCoordinate2DMake(10, 10);
GMSMarker *marker = [GMSMarker markerWithPosition:position];
marker.map = mapView;
// ...
marker.map = nil;
      

تغییر رنگ نشانگر

می‌توانید رنگ تصویر نشانگر پیش‌فرض را با درخواست یک نسخه رنگی از آیکون پیش‌فرض با استفاده از markerImageWithColor: و ارسال تصویر حاصل به ویژگی icon در GMSMarker ، سفارشی کنید.

سویفت

marker.icon = GMSMarker.markerImage(with: .black)
      

هدف-سی

marker.icon = [GMSMarker markerImageWithColor:[UIColor blackColor]];
      

سفارشی‌سازی تصویر نشانگر

اگر می‌خواهید تصویر پیش‌فرض نشانگر را تغییر دهید، می‌توانید با استفاده از icon نشانگر یا ویژگی iconView ، یک آیکون سفارشی تنظیم کنید. اگر iconView تنظیم شده باشد، API ویژگی icon را نادیده می‌گیرد.

استفاده از ویژگی icon نشانگر

قطعه کد زیر یک نشانگر با یک آیکون سفارشی ایجاد می‌کند که به عنوان یک UIImage در ویژگی icon ارائه شده است. این آیکون در مرکز لندن، انگلستان قرار دارد. این قطعه کد فرض می‌کند که برنامه شما حاوی تصویری با نام "house.png" است.

سویفت

let positionLondon = CLLocationCoordinate2D(latitude: 51.5, longitude: -0.127)
let london = GMSMarker(position: positionLondon)
london.title = "London"
london.icon = UIImage(named: "house")
london.map = mapView
      

هدف-سی

CLLocationCoordinate2D positionLondon = CLLocationCoordinate2DMake(51.5, -0.127);
GMSMarker *london = [GMSMarker markerWithPosition:positionLondon];
london.title = @"London";
london.icon = [UIImage imageNamed:@"house"];
london.map = mapView;
      

اگر چندین نشانگر با تصویر یکسان ایجاد می‌کنید، برای هر یک از نشانگرها از یک نمونه UIImage استفاده کنید. این کار به بهبود عملکرد برنامه شما هنگام نمایش نشانگرهای زیاد کمک می‌کند.

این تصویر ممکن است چندین فریم داشته باشد. علاوه بر این، ویژگی alignmentRectInsets رعایت می‌شود، که اگر یک نشانگر سایه یا ناحیه غیرقابل استفاده دیگری داشته باشد، مفید است.

استفاده از ویژگی iconView نشانگر

قطعه کد زیر با تنظیم ویژگی iconView مربوط به نشانگر، یک نشانگر با آیکون سفارشی ایجاد می‌کند و تغییر رنگ نشانگر را به صورت انیمیشن نمایش می‌دهد. این قطعه کد فرض می‌کند که برنامه شما حاوی تصویری با نام "house.png" است.

سویفت

import CoreLocation
import GoogleMaps

class MarkerViewController: UIViewController, GMSMapViewDelegate {
  var mapView: GMSMapView!
  var london: GMSMarker?
  var londonView: UIImageView?

  override func viewDidLoad() {
    super.viewDidLoad()

    let camera = GMSCameraPosition.camera(
      withLatitude: 51.5,
      longitude: -0.127,
      zoom: 14
    )
    let mapView = GMSMapView.map(withFrame: .zero, camera: camera)
    view = mapView

    mapView.delegate = self

    let house = UIImage(named: "House")!.withRenderingMode(.alwaysTemplate)
    let markerView = UIImageView(image: house)
    markerView.tintColor = .red
    londonView = markerView

    let position = CLLocationCoordinate2D(latitude: 51.5, longitude: -0.127)
    let marker = GMSMarker(position: position)
    marker.title = "London"
    marker.iconView = markerView
    marker.tracksViewChanges = true
    marker.map = mapView
    london = marker
  }

  func mapView(_ mapView: GMSMapView, idleAt position: GMSCameraPosition) {
    UIView.animate(withDuration: 5.0, animations: { () -> Void in
      self.londonView?.tintColor = .blue
    }, completion: {(finished) in
      // Stop tracking view changes to allow CPU to idle.
      self.london?.tracksViewChanges = false
    })
  }
}
      

هدف-سی

@import CoreLocation;
@import GoogleMaps;

@interface MarkerViewController : UIViewController <GMSMapViewDelegate>
@property (strong, nonatomic) GMSMapView *mapView;
@end

@implementation MarkerViewController {
  GMSMarker *_london;
  UIImageView *_londonView;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:51.5
                                                          longitude:-0.127
                                                               zoom:14];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
  self.view = _mapView;

  _mapView.delegate = self;

  UIImage *house = [UIImage imageNamed:@"House"];
  house = [house imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate];
  _londonView = [[UIImageView alloc] initWithImage:house];
  _londonView.tintColor = [UIColor redColor];

  CLLocationCoordinate2D position = CLLocationCoordinate2DMake(51.5, -0.127);
  _london = [GMSMarker markerWithPosition:position];
  _london.title = @"London";
  _london.iconView = _londonView;
  _london.tracksViewChanges = YES;
  _london.map = self.mapView;
}

- (void)mapView:(GMSMapView *)mapView idleAtCameraPosition:(GMSCameraPosition *)position {
  [UIView animateWithDuration:5.0
                   animations:^{
    self->_londonView.tintColor = [UIColor blueColor];
  }
                   completion:^(BOOL finished) {
    // Stop tracking view changes to allow CPU to idle.
    self->_london.tracksViewChanges = NO;
  }];
}

@end
      

از آنجا که iconView یک UIView را می‌پذیرد، می‌توانید سلسله مراتبی از کنترل‌های رابط کاربری استاندارد داشته باشید که نشانگرهای شما را تعریف می‌کنند و هر نما دارای مجموعه‌ای استاندارد از قابلیت‌های انیمیشن است. می‌توانید تغییراتی در اندازه، رنگ و سطح آلفای نشانگر و همچنین اعمال تبدیل‌های دلخواه ایجاد کنید. ویژگی iconView از انیمیشن تمام ویژگی‌های قابل انیمیشن UIView به جز frame و center پشتیبانی می‌کند.

لطفا هنگام استفاده از iconView به نکات زیر توجه کنید:

• وقتی tracksViewChanges روی YES تنظیم شده باشد، UIView می‌تواند منابع زیادی را مصرف کند که ممکن است منجر به افزایش مصرف باتری شود. در مقابل، یک UIImage تک فریمی ایستا است و نیازی به رندر مجدد ندارد.
• اگر نشانگرهای زیادی روی صفحه داشته باشید و هر نشانگر UIView مخصوص به خود را داشته باشد و همه نشانگرها همزمان تغییرات را ردیابی کنند، ممکن است برخی از دستگاه‌ها در رندر کردن نقشه با مشکل مواجه شوند.
• یک iconView به تعامل کاربر پاسخ نمی‌دهد، زیرا تصویری از view است.
• این نما طوری رفتار می‌کند که انگار clipsToBounds روی YES تنظیم شده است، صرف نظر از مقدار واقعی آن. می‌توانید تبدیل‌هایی را اعمال کنید که خارج از محدوده‌ها کار می‌کنند، اما شیئی که ترسیم می‌کنید باید درون محدوده‌های شی باشد. همه تبدیل‌ها/تغییرات نظارت و اعمال می‌شوند. به طور خلاصه: زیرنماها باید درون نما قرار گیرند.
• برای استفاده از -copyWithZone: در GMSMarker ، ابتدا باید GMSMarker را کپی کنید و سپس یک نمونه جدید از iconView را روی کپی تنظیم کنید. UIView از NSCopying پشتیبانی نمی‌کند، بنابراین نمی‌تواند iconView را کپی کند.

برای تصمیم‌گیری در مورد زمان تنظیم ویژگی tracksViewChanges ، باید ملاحظات مربوط به عملکرد را در مقابل مزایای ترسیم خودکار نشانگر، بسنجید. برای مثال:

• اگر می‌خواهید یک سری تغییرات ایجاد کنید، می‌توانید ویژگی را به YES تغییر دهید و سپس دوباره به NO برگردانید.
• وقتی یک انیمیشن در حال اجرا است یا محتویات به صورت غیرهمزمان بارگذاری می‌شوند، باید تا زمان تکمیل عملیات، مقدار ویژگی را روی YES نگه دارید.

تغییر میزان شفافیت نشانگر

شما می‌توانید میزان شفافیت یک نشانگر را با استفاده از ویژگی opacity آن کنترل کنید. باید میزان شفافیت را به صورت اعشاری بین 0.0 و 1.0 تعیین کنید، که در آن 0 کاملاً شفاف و 1 کاملاً مات است.

سویفت

marker.opacity = 0.6
      

هدف-سی

marker.opacity = 0.6;
      

شما می‌توانید با استفاده از Core Animation و GMSMarkerLayer میزان شفافیت نشانگر را متحرک‌سازی کنید.

صاف کردن یک نشانگر

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

می‌توانید جهت یک نشانگر را طوری تنظیم کنید که نسبت به زمین صاف باشد. نشانگرهای مسطح با چرخش نقشه می‌چرخند و با کج شدن نقشه، پرسپکتیو آنها تغییر می‌کند. همانند نشانگرهای معمولی، نشانگرهای مسطح با بزرگ‌نمایی یا کوچک‌نمایی نقشه، اندازه خود را حفظ می‌کنند.

برای تغییر جهت نشانگر، ویژگی flat نشانگر را روی YES یا true تنظیم کنید.

سویفت

let positionLondon = CLLocationCoordinate2D(latitude: 51.5, longitude: -0.127)
let londonMarker = GMSMarker(position: positionLondon)
londonMarker.isFlat = true
londonMarker.map = mapView
      

هدف-سی

CLLocationCoordinate2D positionLondon = CLLocationCoordinate2DMake(51.5, -0.127);
GMSMarker *londonMarker = [GMSMarker markerWithPosition:positionLondon];
londonMarker.flat = YES;
londonMarker.map = mapView;
      

چرخاندن یک نشانگر

شما می‌توانید با تنظیم ویژگی rotation ، یک نشانگر را حول نقطه لنگر آن بچرخانید. چرخش را از نوع CLLocationDegrees تعیین کنید که بر حسب درجه در جهت عقربه‌های ساعت از موقعیت پیش‌فرض اندازه‌گیری می‌شود. وقتی نشانگر روی نقشه صاف است، موقعیت پیش‌فرض شمال است.

مثال زیر نشانگر را ۹۰ درجه می‌چرخاند. تنظیم ویژگی groundAnchor با 0.5,0.5 باعث می‌شود نشانگر به جای چرخش حول پایه، حول مرکز خود بچرخد.

سویفت

let degrees = 90.0
londonMarker.groundAnchor = CGPoint(x: 0.5, y: 0.5)
londonMarker.rotation = degrees
londonMarker.map = mapView
      

هدف-سی

CLLocationDegrees degrees = 90;
londonMarker.groundAnchor = CGPointMake(0.5, 0.5);
londonMarker.rotation = degrees;
londonMarker.map = mapView;
      

مدیریت رویدادها روی نشانگرها

شما می‌توانید به رویدادهایی که روی نقشه رخ می‌دهند، مانند زمانی که کاربر روی یک نشانگر ضربه می‌زند، گوش دهید. برای گوش دادن به رویدادها، باید پروتکل GMSMapViewDelegate را پیاده‌سازی کنید. برای یادگیری نحوه مدیریت رویدادهای خاص نشانگر، به بخش رویدادها و حرکات نشانگر مراجعه کنید. راهنمای رویدادها همچنین لیستی از متدهای GMSMapViewDelegate را ارائه می‌دهد. برای رویدادهای نمای خیابان، به GMSPanoramaViewDelegate مراجعه کنید.