形狀

Maps SDK for iOS 提供一些簡單的做法，方便您在地圖中加入形狀。下面的圖形支持：

• 折線是一系列的線段，可構成您想要的任何形狀，並可用來標記地圖上的路徑和路線。
• 多邊形是一個封閉的形狀，可用於在地圖上標記的區域。
• 圓形是地球表面的圓形精確投影。

你可以修改每個形狀的多種方式的外觀。

折線

折線讓你在地圖上繪製線條。GMSPolyline 物件代表一連串的位置，以一系列線條區隔顯示。您可以使用 GMSStrokeStyle 設定折線的顏色。

如要建立折線，您必須建立含有兩個以上點的對應 GMSMutablePath 物件，藉此指定折線。每個 CLLocationCoordinate2D 都代表地球表面上的一個點。根據您在路徑中新增路徑的順序，系統會在點與點之間繪製線段。您可以使用 addCoordinate: 或 addLatitude:longitude: 方法在路徑中新增路徑點。

let path = GMSMutablePath()
path.add(CLLocationCoordinate2D(latitude: -33.85, longitude: 151.20))
path.add(CLLocationCoordinate2D(latitude: -33.70, longitude: 151.40))
path.add(CLLocationCoordinate2D(latitude: -33.73, longitude: 151.41))
let polyline = GMSPolyline(path: path)
      

GMSMutablePath *path = [GMSMutablePath path];
[path addCoordinate:CLLocationCoordinate2DMake(-33.85, 151.20)];
[path addCoordinate:CLLocationCoordinate2DMake(-33.70, 151.40)];
[path addCoordinate:CLLocationCoordinate2DMake(-33.73, 151.41)];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
      

新增折線

1. 建立 GMSMutablePath 物件。
2. 使用 addCoordinate: 或 addLatitude:longitude: 方法設定路徑中的路徑點。
3. 使用路徑做為引數，將新的 GMSPolyline 物件執行個體化。
4. 視需要設定其他屬性，例如 strokeWidth 和 strokeColor。
5. 設定 GMSPolyline 的 map 屬性。
6. 折線將出現在地圖上。

下面的代碼片斷添加一個矩形的地圖：

let rectanglePath = GMSMutablePath()
rectanglePath.add(CLLocationCoordinate2D(latitude: 37.36, longitude: -122.0))
rectanglePath.add(CLLocationCoordinate2D(latitude: 37.45, longitude: -122.0))
rectanglePath.add(CLLocationCoordinate2D(latitude: 37.45, longitude: -122.2))
rectanglePath.add(CLLocationCoordinate2D(latitude: 37.36, longitude: -122.2))
rectanglePath.add(CLLocationCoordinate2D(latitude: 37.36, longitude: -122.0))

let rectangle = GMSPolyline(path: path)
rectangle.map = mapView
      

GMSMutablePath *rectanglePath = [GMSMutablePath path];
[rectanglePath addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];
[rectanglePath addCoordinate:CLLocationCoordinate2DMake(37.45, -122.0)];
[rectanglePath addCoordinate:CLLocationCoordinate2DMake(37.45, -122.2)];
[rectanglePath addCoordinate:CLLocationCoordinate2DMake(37.36, -122.2)];
[rectanglePath addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];

GMSPolyline *rectangle = [GMSPolyline polylineWithPath:path];
rectangle.map = mapView;
      

移除折線

將 GMSPolyline 的 map 屬性設為 nil，即可從地圖中移除折線。或者，您也可以呼叫 GMSMapView clear 方法，移除目前地圖中的所有疊加層 (包括折線和其他形狀)。

mapView.clear()
      

[mapView clear];
      

自訂折線

GMSPolyline 物件提供多個屬性來控制線條的外觀。它支持下面的選項：

strokeWidth

整個線條的寬度 (以螢幕點表示)。默認為1。縮放地圖時，寬度的尺寸不會改變。

geodesic

在 YES 中，將這個折線邊緣顯示為測地線。測地線段依照地球表面的最短路徑，在麥卡托投影地圖中可能會顯示為曲線。非測地線段在地圖上繪製成直線。這個變數預設為 NO。

spans

用於指定折線的一或多個線段的顏色。Span 屬性是 GMSStyleSpan 物件的陣列。建議更改 spans 屬性以變更折線的顏色。

strokeColor

UIColor 物件，用來指定折線的色彩。預設為 blueColor。如果設定了 spans，則系統會忽略 strokeColor 屬性。

下列程式碼片段會針對墨爾本至伯斯新增粗的折線，帶有測地線內插。

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView
      

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.geodesic = YES;
polyline.map = mapView;
      

如果您在將折線加入地圖後進行修改，請務必保留 GMSPolyline 物件，

polyline.strokeColor = .blue
      

polyline.strokeColor = [UIColor blueColor];
      

變更折線的顏色

折線會在地圖上繪製成一系列的區隔。您可以使用 spans 屬性變更個別片段或整行的顏色。雖然這項屬性可讓您精細地控制折線的色彩，但也有一些便利，可以讓您輕鬆將單一樣式套用至整個線條。

下方的程式碼片段使用 spanWithColor: 方法，將整個線條的顏色變更為紅色。

polyline.spans = [GMSStyleSpan(color: .red)]
      

polyline.spans = @[[GMSStyleSpan spanWithColor:[UIColor redColor]]];
      

或者，如果您已有 GMSStrokeStyle 物件的存取權，可以使用 spanWithStyle: 方法。

let solidRed = GMSStrokeStyle.solidColor(.red)
polyline.spans = [GMSStyleSpan(style: solidRed)]
      

GMSStrokeStyle *solidRed = [GMSStrokeStyle solidColor:[UIColor redColor]];
polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed]];
      

在 Maps SDK for iOS 1.7 版之前，可使用單一屬性 strokeColor 來設定 GMSPolyline 的完整顏色。spans 屬性的優先順序高於 strokeColor。

polyline.strokeColor = .red
      

polyline.strokeColor = [UIColor redColor];
      

樣式

如果您的應用程式多次套用相同的筆劃顏色，您可能會發現定義可重複使用的樣式很有幫助。您必須使用 GMSStrokeStyle 物件來指定折線樣式。筆劃樣式可以是單色，也可以是某色的漸層色彩。建立樣式後，您可以使用 spanWithStyle: 方法將其套用至 GMSStyleSpan。

// Create two styles: one that is solid blue, and one that is a gradient from red to yellow
let solidBlue = GMSStrokeStyle.solidColor(.blue)
let solidBlueSpan = GMSStyleSpan(style: solidBlue)
let redYellow = GMSStrokeStyle.gradient(from: .red, to: .yellow)
let redYellowSpan = GMSStyleSpan(style: redYellow)
      

// Create two styles: one that is solid blue, and one that is a gradient from red to yellow
GMSStrokeStyle *solidBlue = [GMSStrokeStyle solidColor:[UIColor blueColor]];
GMSStyleSpan *solidBlueSpan = [GMSStyleSpan spanWithStyle:solidBlue];
GMSStrokeStyle *redYellow =
    [GMSStrokeStyle gradientFromColor:[UIColor redColor] toColor:[UIColor yellowColor]];
GMSStyleSpan *redYellowSpan = [GMSStyleSpan spanWithStyle:redYellow];
      

span 的樣式會繼續，直到折線結束或持續設定新樣式為止。只要將折線的 spans 屬性設為單一 GMSStyleSpan，即可變更整個線條的顏色。以下程式碼片段說明如何在折線的整個長度上套用漸層。

polyline.spans = [GMSStyleSpan(style: redYellow)]
      

polyline.spans = @[[GMSStyleSpan spanWithStyle:redYellow]];
      

變更個別線段的顏色

如果您想要個別設定折線的樣式，可以建立 GMSStyleSpan 物件的陣列，並將其傳送至 spans 屬性。根據預設，陣列的各個項目會設為對應線段的顏色。如果陣列中的元素數量超過行中的區隔數量，系統會忽略額外的元素。如果陣列中的元素數量較少，最後一個 GMSStyleSpan 將描述線條剩餘顏色。

您可以使用色彩和/或漸層折線的區塊來表示折線上的變化，例如海拔高度或速度。下方程式碼片段會將折線前兩段的色彩設為紅色，而線條的剩餘部分則是從紅色變成黃色的漸層。

polyline.spans = [
  GMSStyleSpan(style: solidRed),
  GMSStyleSpan(style: solidRed),
  GMSStyleSpan(style: redYellow)
]
      

polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed],
                   [GMSStyleSpan spanWithStyle:solidRed],
                   [GMSStyleSpan spanWithStyle:redYellow]];
      

您可以使用 spanWithStyle:segments: 方法一次設定多個片段的樣式。舉例來說，以下程式碼等同於上述內容。系統會忽略最終 GMSStyleSpan 的區段長度，因為該樣式將用來描述這行的其餘部分。

polyline.spans = [
  GMSStyleSpan(style: solidRed, segments:2),
  GMSStyleSpan(style: redYellow, segments:10)
]
      

polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed segments:2],
                   [GMSStyleSpan spanWithStyle:redYellow segments:10]];
      

片段

區隔也可以指定為分數值。這會將樣式套用至一定比例的片段，並可能在單一區隔中分割。每個 GMSStyleSpan 都會立即在前一個片段之後開始：在以下範例中，灰色的顏色從 1⁄2 到第二個片段開始，一直到 1⁄2 到第三個片段。

polyline.spans = [
  GMSStyleSpan(style: solidRed, segments: 2.5),
  GMSStyleSpan(color: .gray),
  GMSStyleSpan(color: .purple, segments: 0.75),
  GMSStyleSpan(style: redYellow)
]
      

polyline.spans = @[[GMSStyleSpan spanWithStyle:solidRed segments:2.5],
                   [GMSStyleSpan spanWithColor:[UIColor grayColor]],
                   [GMSStyleSpan spanWithColor:[UIColor purpleColor] segments:0.75],
                   [GMSStyleSpan spanWithStyle:redYellow]];
      

在折線中加入重複的色彩模式

如果您想在折線中新增圖案，可以使用 GMSGeometryUtils 中的 GMSStyleSpans 公用程式方法。GMSStyleSpans 方法可接受兩個定義重複模式的陣列。其中一個陣列會設定應重複的樣式，另一個陣列則定義重複的間隔。您可以搭配使用，這樣可以建立適用於任何折線的模式，而不受折線的長度或可用區隔的數量影響。

例如，以下程式碼片段定義了採用黑白加固模式的折線。由於類型指定為 kGMSLengthRhumb，因此系統會將其長度視為以一條小線 (在麥卡托上，此為直線) 的公尺。

let styles = [
  GMSStrokeStyle.solidColor(.white),
  GMSStrokeStyle.solidColor(.black)
]
let lengths: [NSNumber] = [100000, 50000]
polyline.spans = GMSStyleSpans(
  polyline.path!,
  styles,
  lengths,
  GMSLengthKind.rhumb
)
      

NSArray *styles = @[[GMSStrokeStyle solidColor:[UIColor whiteColor]],
                    [GMSStrokeStyle solidColor:[UIColor blackColor]]];
NSArray *lengths = @[@100000, @50000];
polyline.spans = GMSStyleSpans(polyline.path, styles, lengths, kGMSLengthRhumb);
      

多邊形

多邊形與折線類似，都是由一系列座標依序組成。不過，多邊形並不是開放的線段，而是用來定義封閉環中的固體區域。多邊形是由 Maps SDK for iOS 的 GMSPolygon 類別所定義。

在地圖中新增 GMSPolygon 的做法與加入 GMSPolyline 的方式相同。首先，請建立對應的 GMSMutablePath 物件並新增路徑點來指定路徑。這些點會構成多邊形的外框。每個 CLLocationCoordinate2D 都代表地球表面上的一個點。根據您在路徑中新增路徑的順序，在點之間繪製線段。

加入多邊形

1. 建立 GMSMutablePath 物件。
2. 使用 addCoordinate: 或 addLatitude:longitude: 方法設定路徑中的路徑點。這些點會構成多邊形的外框。
3. 使用路徑做為引數，將新的 GMSPolygon 物件執行個體化。
4. 視需要設定其他屬性，例如 strokeWidth、strokeColor 和 fillColor。
5. 將 GMSPolygon.map 屬性設定為 GMSMapView 物件，將多邊形指派給 GMSMapView 物件。
6. 地圖上會顯示多邊形。

以下程式碼片段會將矩形加進地圖。

// Create a rectangular path
let rect = GMSMutablePath()
rect.add(CLLocationCoordinate2D(latitude: 37.36, longitude: -122.0))
rect.add(CLLocationCoordinate2D(latitude: 37.45, longitude: -122.0))
rect.add(CLLocationCoordinate2D(latitude: 37.45, longitude: -122.2))
rect.add(CLLocationCoordinate2D(latitude: 37.36, longitude: -122.2))

// Create the polygon, and assign it to the map.
let polygon = GMSPolygon(path: rect)
polygon.fillColor = UIColor(red: 0.25, green: 0, blue: 0, alpha: 0.05);
polygon.strokeColor = .black
polygon.strokeWidth = 2
polygon.map = mapView
      

// Create a rectangular path
GMSMutablePath *rect = [GMSMutablePath path];
[rect addCoordinate:CLLocationCoordinate2DMake(37.36, -122.0)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.45, -122.0)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.45, -122.2)];
[rect addCoordinate:CLLocationCoordinate2DMake(37.36, -122.2)];

// Create the polygon, and assign it to the map.
GMSPolygon *polygon = [GMSPolygon polygonWithPath:rect];
polygon.fillColor = [UIColor colorWithRed:0.25 green:0 blue:0 alpha:0.05];
polygon.strokeColor = [UIColor blackColor];
polygon.strokeWidth = 2;
polygon.map = mapView;
      

不管是在將多邊形加入地圖之前或之後，您都可以自訂多邊形的外觀。

移除多邊形

將多邊形的 GMSPolygon.map 屬性設為 nil，並從它的父項卸離 layer，藉此移除多邊形。

 polygon.map = nil
 polygon.layer.removeFromSuperLayer()

 polygon.map = nil;
 [polygon.layer removeFromSuperlayer];
 

圓圈

除了一般的 GMSPolygon 類別之外，Maps SDK for iOS 還提供 GMSCircle，方便您在地球表面上繪製圓形。

如要建構圓形，您必須指定以下兩個屬性：

• 以 CLLocationCoordinate2D 格式指定的 position。
• radius (單位為公尺)。

接著，將圓形定義為地球表面上距離 center radius 公尺的所有點的集合。Maps API 使用的麥卡托投影會在平面上算繪球體，而受到該投影方式的影響，圓形位於赤道附近時，在地圖上呈現出來的會是近乎完美的圓形，但一旦離赤道越來越遠，(在螢幕上) 看起來就越不像圓形。

新增社交圈

下面的代碼片斷添加一個圓形的地圖：

let circleCenter = CLLocationCoordinate2D(latitude: 37.35, longitude: -122.0)
let circle = GMSCircle(position: circleCenter, radius: 1000)
circle.map = mapView
      

CLLocationCoordinate2D circleCenter = CLLocationCoordinate2DMake(37.35, -122.0);
GMSCircle *circle = [GMSCircle circleWithPosition:circleCenter
                                         radius:1000];
circle.map = mapView;
      

不管是在將圓形加入地圖之前或之後，您都可以自訂圓形的外觀。

自訂社交圈

您可以藉由修改 GMSCircle 的屬性來指定自訂色彩和筆劃寬度。它支持下面的選項：

fillColor

UIColor 物件，用於指定圓形的內部色彩。默認為透明。

strokeColor

UIColor 物件，用於指定圓形外框顏色。預設值為 blackColor。

strokeWidth

圓形外框的粗細 (以螢幕點表示)。預設值為 1。 縮放地圖時，厚度不會改變。

下列程式碼片段會加上粗紅色的半圓形紅色圓圈。

circle.fillColor = UIColor(red: 0.35, green: 0, blue: 0, alpha: 0.05)
circle.strokeColor = .red
circle.strokeWidth = 5
      

circle.fillColor = [UIColor colorWithRed:0.25 green:0 blue:0 alpha:0.05];
circle.strokeColor = [UIColor redColor];
circle.strokeWidth = 5;
      

建立一個中空的多邊形

您可以在單一 GMSPolygon 物件中組合多條路徑，建立複雜的形狀，例如填滿的環形 (或環形) 中，多邊形區域會在多邊形內以獨立形狀呈現。複雜的形狀是由多個路徑組成。

建立一個具有指定路徑且指定多邊形所涵蓋最大面積的多邊形。接著，將多邊形的 holes 屬性指定為一或多個 GMSPath 物件的陣列，而這些物件會定義多邊形內的空洞。

如果較小的路徑完全被較大的路徑包圍，它看起來像是某一段多邊形已移除。

下列程式碼範例會建立具有兩個孔的多邊形：

let hydeParkLocation = CLLocationCoordinate2D(latitude: -33.87344, longitude: 151.21135)
let camera = GMSCameraPosition.camera(withTarget: hydeParkLocation, zoom: 16)
let mapView = GMSMapView.map(withFrame: .zero, camera: camera)
mapView.animate(to: camera)

let hydePark = "tpwmEkd|y[QVe@Pk@BsHe@mGc@iNaAKMaBIYIq@qAMo@Eo@@[Fe@DoALu@HUb@c@XUZS^ELGxOhAd@@ZB`@J^BhFRlBN\\BZ@`AFrATAJAR?rAE\\C~BIpD"
let archibaldFountain = "tlvmEqq|y[NNCXSJQOB[TI"
let reflectionPool = "bewmEwk|y[Dm@zAPEj@{AO"

let hollowPolygon = GMSPolygon()
hollowPolygon.path = GMSPath(fromEncodedPath: hydePark)
hollowPolygon.holes = [GMSPath(fromEncodedPath: archibaldFountain)!, GMSPath(fromEncodedPath: reflectionPool)!]
hollowPolygon.fillColor = UIColor(red: 1.0, green: 0.0, blue: 0.0, alpha: 0.2)
hollowPolygon.strokeColor = UIColor(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
hollowPolygon.strokeWidth = 2
hollowPolygon.map = mapView
      

CLLocationCoordinate2D hydeParkLocation = CLLocationCoordinate2DMake(-33.87344, 151.21135);
GMSCameraPosition *camera = [GMSCameraPosition cameraWithTarget:hydeParkLocation
                                                           zoom:16];
mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];

NSString *hydePark = @"tpwmEkd|y[QVe@Pk@BsHe@mGc@iNaAKMaBIYIq@qAMo@Eo@@[Fe@DoALu@HUb@c@XUZS^ELGxOhAd@@ZB`@J^BhFRlBN\\BZ@`AFrATAJAR?rAE\\C~BIpD";
NSString *archibaldFountain = @"tlvmEqq|y[NNCXSJQOB[TI";
NSString *reflectionPool = @"bewmEwk|y[Dm@zAPEj@{AO";

GMSPolygon *hollowPolygon = [[GMSPolygon alloc] init];
hollowPolygon.path = [GMSPath pathFromEncodedPath:hydePark];
hollowPolygon.holes = @[[GMSPath pathFromEncodedPath:archibaldFountain],
                  [GMSPath pathFromEncodedPath:reflectionPool]];
hollowPolygon.fillColor = [UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:0.2];
hollowPolygon.strokeColor = [UIColor colorWithRed:1.0 green:0.0 blue:0.0 alpha:1.0];
hollowPolygon.strokeWidth = 2;
hollowPolygon.map = mapView;