Markers

اختيار النظام الأساسي: Android iOS JavaScript

تشير العلامات إلى مواقع فردية على الخريطة.

بشكل افتراضي، تستخدم العلامات رمزًا قياسيًا له الشكل والأسلوب الشائعين في خرائط Google. إذا كنت ترغب في تخصيص العلامة، يمكنك تغيير لون العلامة الافتراضية، أو استبدال صورة العلامة برمز مخصص، أو تغيير الخصائص الأخرى للعلامة.

استجابةً لحدث نقرة على محدّد موقع، يمكنك فتح نافذة معلومات. تعرض نافذة المعلومات نصًا أو صورًا في نافذة مربع حوار فوق العلامة. يمكنك استخدام نافذة معلومات تلقائية لعرض النص أو إنشاء نافذة معلومات مخصّصة للتحكّم بشكل كامل في محتواها.

إضافة علامة

لإضافة علامة تحديد، أنشِئ كائن GMSMarker يتضمّن position وtitle، واضبط map.

يعرض المثال التالي كيفية إضافة علامة إلى عنصر GMSMapView حالي. يتم إنشاء العلامة في الإحداثيات 10,10، وتعرض السلسلة "Hello world" في نافذة المعلومات عند النقر عليها.

Swift

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

Objective-C

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

يمكنك إضافة تأثيرات متحركة إلى الخريطة عن طريق ضبط السمة marker.appearAnimation على:

• kGMSMarkerAnimationPop في إظهار العلامة من groundAnchor عند إضافتها.
• kGMSMarkerAnimationFadeIn للتسبب في تلاشي العلامة عند إضافتها.

إزالة علامة

يمكنك إزالة محدِّد الموقع من الخريطة من خلال ضبط السمة map في GMSMarker على nil. يمكنك بدلاً من ذلك إزالة جميع العناصر المركّبة (بما في ذلك العلامات) الظاهرة على الخريطة حاليًا من خلال استدعاء طريقة GMSMapView clear.

Swift

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

Objective-C

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

إذا أردت إجراء تعديلات على محدّد موقع بعد إضافته إلى الخريطة، احرص على الاحتفاظ بعنصر GMSMarker. يمكنك تعديل العلامة لاحقًا عن طريق إجراء تغييرات على هذا الكائن.

Swift

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

Objective-C

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

تغيير لون العلامة

يمكنك تخصيص لون صورة العلامة التلقائية من خلال طلب نسخة ملوَّنة من الرمز التلقائي الذي يتضمّن markerImageWithColor:، وتمرير الصورة الناتجة إلى خاصية الرمز GMSMarker.

Swift

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

Objective-C

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

تخصيص صورة العلامة

إذا أردت تغيير صورة العلامة التلقائية، يمكنك ضبط رمز مخصّص، باستخدام السمة icon أو iconView الخاصة بالعلامة. في حال ضبط السمة iconView، تتجاهل واجهة برمجة التطبيقات السمة icon.

استخدام السمة icon للعلامة

ينشئ المقتطف التالي علامة مع رمز مخصّص يتم تقديمه على أنّه UIImage في السمة icon. يتم عرض الرمز في وسط لندن بإنجلترا. يفترض المقتطف أن تطبيقك يحتوي على صورة باسم "house.png".

Swift

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
      

Objective-C

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".

Swift

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

Objective-C

@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:

• قد يستدعي ضبط UIView على الموارد عند ضبط tracksViewChanges على YES، ما قد يؤدي إلى زيادة استخدام البطارية. في المقابل، إطار UIImage ثابت ولا يحتاج إلى إعادة عرضه.
• قد تواجه بعض الأجهزة صعوبة في عرض الخريطة إذا كان لديك العديد من العلامات على الشاشة، ولكل علامة UIView خاصة بها، وجميع العلامات تتتبّع التغييرات في الوقت نفسه.
• لا يستجيب iconView لتفاعل المستخدم، لكونه نبذة عن طريقة العرض.
• تعمل طريقة العرض كما لو تم ضبط clipsToBounds على YES، بغض النظر عن قيمتها الفعلية. يمكنك تطبيق التحويلات التي تعمل خارج الحدود، ولكن يجب أن يكون الكائن الذي ترسمه داخل حدود الكائن. تتم مراقبة جميع عمليات التحويل/الورديات وتطبيقها. باختصار: يجب أن يتم تضمين المشاهدات الفرعية ضمن العرض.

لتحديد وقت ضبط السمة tracksViewChanges، يجب مراعاة اعتبارات الأداء في ضوء مزايا إعادة رسم العلامة تلقائيًا. مثلاً:

• إذا أردت إجراء سلسلة من التغييرات، يمكنك تغيير السمة إلى YES ثم العودة إلى NO.
• عندما تكون الصورة المتحركة قيد التشغيل أو يتم تحميل المحتوى بشكل غير متزامن، عليك ضبط السمة على YES إلى أن تكتمل الإجراءات.

تغيير مدى تعتيم العلامة

يمكنك التحكّم في تعتيم العلامة باستخدام السمة opacity الخاصة بها. يجب عليك تحديد التعتيم كعدد عائم بين 0.0 و1.0، حيث يكون 0 شفافًا تمامًا و1 معتم تمامًا.

Swift

marker.opacity = 0.6
      

Objective-C

marker.opacity = 0.6;
      

يمكنك تحريك معدل تعتيم العلامة باستخدام ["صورة متحركة أساسية"] باستخدام GMSMarkerLayer.

تسوية العلامة

يتم رسم أيقونات العلامات عادةً على شاشة الجهاز بدلاً من سطح الخريطة، لذلك لا يؤدي تدوير أو إمالة أو تكبير الخريطة بالضرورة إلى تغيير اتجاه العلامة.

يمكنك ضبط اتجاه علامة بحيث يكون مسطحًا مقابل الأرض. يتم تدوير العلامات المسطحة عند تدوير الخريطة، وتغير المنظور عند إمالة الخريطة. كما هو الحال مع محددات المواقع العادية، تحتفظ محددات المواقع المسطحة بحجمها عند تكبير الخريطة أو تصغيرها.

لتغيير اتجاه محدّد الموقع، اضبط السمة flat للعلامة على YES أو true.

Swift

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

Objective-C

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

تدوير علامة

يمكنك تدوير علامة حول نقطة الارتساء الخاصة بها من خلال ضبط السمة rotation. حدِّد التدوير كنوع CLLocationDegrees، ويتم قياسه بالدرجات في اتجاه عقارب الساعة من الموضع التلقائي. عندما تكون العلامة مسطحة على الخريطة، فيكون الموضع الافتراضي هو الشمال.

يؤدي المثال التالي إلى تدوير العلامة بزاوية 90°. يؤدي ضبط السمة groundAnchor على 0.5,0.5 إلى تدوير العلامة حول مركزها، بدلاً من قاعدتها.

Swift

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

Objective-C

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

التعامل مع الأحداث على العلامات

يمكنك الاستماع إلى الأحداث التي تقع على الخريطة، مثل عندما ينقر المستخدم على محدّد موقع. للاستماع إلى الأحداث، عليك تنفيذ بروتوكول GMSMapViewDelegate. يمكنك الاطّلاع على أحداث وإيماءات العلامات لمعرفة كيفية التعامل مع أحداث محدّدات مواقع معيّنة. يوفّر دليل الأحداث أيضًا قائمة بالطرق على GMSMapViewDelegate. بالنسبة إلى أحداث "التجوّل الافتراضي"، راجِع GMSPanoramaViewDelegate.