標記

選取平台： Android iOS JavaScript

標記是用來標出地圖上的某個位置。

標記預設會使用標準圖示，外觀和風格與 Google 地圖一致。如要自訂標記，可以變更預設標記的顏色、以自訂圖示取代標記圖片，或變更標記的其他屬性。

您可以開啟資訊視窗，回應標記上的點擊事件。資訊視窗會在標記上方的對話方塊視窗中顯示文字或圖片，您可以使用預設資訊視窗顯示文字，也可以建立自訂資訊視窗，完全掌控內容。

新增標記

如要新增標記，請建立包含 position 和 title 的 GMSMarker 物件，並設定其 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，讓標記在新增時淡入。

移除標記

如要從地圖中移除標記，請將 GMSMarker 的 map 屬性設為 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 的 icon 屬性。

Swift

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

Objective-C

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

自訂標記圖片

如要變更預設標記圖片，可以使用標記的 icon 或 iconView 屬性設定自訂圖示。如果設定 iconView，API 會忽略 icon 屬性。

使用標記的 icon 屬性

下列程式碼片段會建立標記，並在 icon 屬性中以 UIImage 形式提供自訂圖示。圖示位於英國倫敦的中心位置。程式碼片段假設應用程式包含名為「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 屬性，藉此建立具有自訂圖示的標記，並為標記的顏色變化加上動畫效果。The snippet assumes that your application contains an image named "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，因此您可以建立定義標記的標準 UI 控制項階層，每個檢視區塊都有一組標準的動畫功能。您可以變更標記大小、顏色和 Alpha 級別，以及套用任意轉換。iconView 屬性支援 UIView 的所有可設定動畫屬性，但 frame 和 center 除外。

使用 iconView 時，請注意下列事項：

  • 如果將 tracksViewChanges 設為 YES，UIView 可能會耗用大量資源，導致電池用量增加。相較之下，單一影格 UIImage 是靜態的，不需要重新算繪。
  • 如果畫面上有很多標記，且每個標記都有自己的 UIView，所有標記同時追蹤變更，部分裝置可能無法順利算繪地圖。
  • iconView 是檢視區塊的快照，因此不會回應使用者互動。
  • 無論 clipsToBounds 的實際值為何，檢視畫面都會像設為 YES 一樣運作。您可以套用超出邊界的變形，但繪製的物件必須在物件邊界內。系統會監控並套用所有轉換/位移。簡而言之，子檢視區塊必須包含在檢視區塊中。
  • 如要在 GMSMarker 上使用 -copyWithZone:，請先複製 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;

您可以使用 GMSMarkerLayer，透過 Core Animation 製作標記不透明度動畫。

將標記設為平放

標記圖示通常是根據裝置螢幕方向繪製 (而非地圖表面)，因此旋轉、傾斜或縮放地圖不一定會改變標記的方向。

你可以設置一個標記的方向是平貼在地上。地圖旋轉時，平放標記會跟著旋轉；地圖傾斜時，標記也會改變角度。和一般標記一樣，縮放地圖時，平放標記的大小不會改變。

如要變更標記的方向，請將標記的 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。