المحدِّدات

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

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

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

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

إضافة علامة

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

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

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 options = GMSMapViewOptions()
options.camera = camera
let mapView = GMSMapView(options: options)
// ...
mapView.clear()
      

Objective-C

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
options.camera = camera;
mapView = [[GMSMapView alloc] initWithOptions:options];
// ...
[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 نفسه لكل علامة. يساعد ذلك في تحسين أداء تطبيقك وتحسين استخدام ذاكرة التخزين المؤقت للزخرفة عند عرض العديد من العلامات.

تحذير: إنّ إضافة عدد كبير من العلامات التي تتضمّن صورًا مخصّصة فريدة أو ديناميكية أو عالية الدقة يمكن أن يؤدي إلى استنفاد ذاكرة التخزين المؤقت الداخلية لـ "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع iOS". عند الوصول إلى سعة ذاكرة التخزين المؤقت، قد تحدث حالات شاذة في العرض، مثل وميض الرموز أو تبديل الرموز بين العلامات.

إذا كان تطبيقك يتطلّب عددًا كبيرًا من العلامات الفريدة أو التي يتم إنشاؤها ديناميكيًا، ننصحك بالانتقال إلى GMSAdvancedMarker (متوافقة مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS 8.2 والإصدارات الأحدث). في معظم الحالات، يمكنك توقّع إتاحة محدّدات المواقع المخصّصة بالمئات، ولكن يعتمد هذا الحدّ بشكل كبير على حجم محدّدات المواقع، وقد يكون أقل بكثير. يعرض GMSAdvancedMarker الرموز مباشرةً باستخدام طرق العرض الأصلية (UIView أو CALayers)، متجاوزًا نظام تجميع أطلس الزخرفة الداخلي بالكامل.

بالإضافة إلى ذلك، يجب إعادة استخدام مرجع 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 options = GMSMapViewOptions()
    options.camera = camera
    let mapView = GMSMapView(options: options)
    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];
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = camera;
  _mapView = [[GMSMapView alloc] initWithOptions:options];
  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، بغض النظر عن قيمته الفعلية. يمكنك تطبيق التحويلات التي تعمل خارج الحدود، ولكن يجب أن يكون الكائن الذي ترسمه ضمن حدود الكائن. تتم مراقبة جميع عمليات التحويل/النقل وتطبيقها. باختصار: يجب أن تكون طرق العرض الفرعية مضمنة في طريقة العرض.
• لاستخدام -copyWithZone: في GMSMarker، عليك نسخ GMSMarker أولاً ثم ضبط مثيل جديد من iconView في النسخة. لا يتوافق "UIView" مع "NSCopying"، لذا لا يمكنه نسخ "iconView".

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

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

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

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

Swift

marker.opacity = 0.6
      

Objective-C

marker.opacity = 0.6;
      

يمكنك تحريك شفافية العلامة باستخدام Core Animation من خلال 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.