
原文:A Swift Tutorial for Google Maps SDK。本文由 CocoaChina 與百度智客聯盟共同翻譯,譯者:slowwind
在 iOS 裡用地圖,能帶給開發者無限可能——這個主題通常足以寫成書裡的一整章。從單純在畫面上標出一個位置,到串起多個中途點畫出一條旅程路線,甚至用完全不同的方式探索地圖的玩法,處理這些事本身就是一段極棒的經歷,成果也往往令人驚豔。
直到 iOS 5.1(含)為止,iOS 都是使用 Google Mobile Maps 服務來提供地圖能力。此後情況有了變化:Apple 推出了 Map Kit,一個完全內建於 iOS 的全新框架,沿用至今。Apple 停用 Google 地圖服務之後,Google 決定打造自己的地圖 SDK,涵蓋包含 iOS 在內的所有平台,與 Map Kit 及其他平台的方案競爭。如今這個 SDK 已有大量開發者在用,Google 在這個領域是強者,因此為它寫一篇入門文章絕對值得。
本文撰寫時,iOS 版 Google Maps SDK 的版本為 1.9.2。它包含大量特性,絕大多數與網頁版地圖一致,另一方面也有部分移動平台特有的能力。值得一提的是,這個版本的 SDK 佔用磁碟空間不小,如果你要把框架原始碼複製進專案,這點必須納入考量。不過它提供的功能實在有趣而關鍵,我二話不說就複製了。
與我其他教程不同,這次的鋪陳不會太長——因為後面要做的事情實在太多,在這裡逐一討論各種特性反而顯得漫無目標,我們會在後續詳細檢視。總之,準備好迎接真正有趣的內容吧。如果你以前沒用過 Google Maps SDK,我相信你會愛上它。接下來的章節會完整涵蓋開發者在處理地圖時最常遇到的任務:
如何在地圖上顯示用戶目前位置
如何定位自訂地址
如何繪製路線
如何在路線中加入中途點(航路點)
以及更多…
那就不浪費時間了,我們直接進入正題。
先說明本教程使用的範例專案。我們不必從零建立新工程,而是用一個起始專案當基礎,再逐步加功能。請先下載它並在 Xcode 中打開。
這個範例實際上是一個單視圖程式,包含三個子視圖:
螢幕頂部的工具列,上面有幾個工具列按鈕。起始專案中,這些按鈕已經與 IBAction 方法連接好了。
佔據大部分可用螢幕空間的視圖(UIView),地圖就顯示在這裡。
底部的標籤,用來顯示路線的長度與預估時間。
頂部工具列按鈕由左至右分別是:
指定自訂地址
設定路線的起點與終點
切換行進模式
切換地圖類型
後續都會逐一實作。目前你要做的只是快速瀏覽起始專案,讓自己能在其中自在翻閱。以下是一組截圖,作為我們要達成的目標樣例。

重要提示:如果你下載並執行最終版 App,請確認已把自己的 API key 設定進 AppDelegate.swift。細節見下一節。
使用 Google Maps SDK 之前,必須先取得一組 API Key。也就是說,我們要向 Google 索取一段特殊字串,之後 App 才能呼叫 Google API。這組 Key 需要從 Google Developers Console 取得——顧名思義,那是開發者專屬的地方。前提是你得有 Google 帳號;還沒有的話先去申請,有的話就可以繼續往下。
你可以直接參考 Google 官方的入門指南,不過在本文撰寫時,Developers Console 的介面已與該指南不一致(介面更新了,指南還沒跟上),所以我建議依下列步驟操作。
用你的 Google 帳號登入 Developers Console,點選如畫面所示的 API Project:

接著展開 API & auth,選擇 APIs,你會看到 Google 提供的所有可用 API,但我們只關心 iOS 版 Google Maps SDK。依瀏覽器不同,API 可能顯示為清單(需捲動尋找地圖相關項目),也可能分組顯示(直接點對應分組即可)。以下兩張截圖說明了這兩種情況:

選好 iOS 版 Google Maps SDK API 後進入新頁面,在這裡把它啟用:

完成後點 Credentials,同樣位於 API & auth 之下。在新頁面中點左下角的 Create new Key:

接著會彈出對話框詢問你要建立的 Key 類型,顯然要點 iOS Key,才能為我們的程式產生合法的 Key。

下一步必須輸入或貼上 App 的 bundle identifier。起始專案的 bundle ID 是 com.appcoda.GMapsDemo,複製貼上即可:

這一步是授權的必要條件。注意,如果你打算讓多個 App 共用同一組 API Key,必須先在此對話框(之後也能回來修改)把它們的 bundle ID 都加上。
點 Create,需要的 API Key 就產生了。回到上一頁的右下角,你會看到類似下圖的區域:

點 Edit allowed iOS applications 可以增減 App 的 bundle ID,也能重新產生 Key(目前不需要)。你現在要做的只是複製這組 API Key,稍後貼進專案。
使用非 Apple 提供的 SDK 有個缺點:專案必須依賴並額外配置它。本節要完成一連串必要初始化步驟,否則根本用不起來。以下部分步驟能在 Google 官方文件找到,另一些則沒有明確記載,得自己搜尋——好消息是,在這裡你不需要搜尋了。
首先請下載 Google Maps SDK(這個框架必須加進專案)。點 Download the SDK,在跳轉的頁面選擇建議版本(目前為 1.9.2),下載後解壓。
在 Xcode 中打開起始專案,接著從 Finder 把 GoogleMaps.framework 拖進 Project Navigator。當 Xcode 詢問時,請勾選 Copy items if needed,也別忘了勾選 GMapsDemo:

下一步回到 Finder,再次點進 GoogleMaps.framework,從 Resources 資料夾中把 GoogleMaps.bundle 拖進 Xcode 的 Project Navigator,選項同上。
完成後,專案裡應該會出現這兩項(Google Maps SDK 分組是我為了方便整理而建立的):

要讓 SDK 正常運作,還得加入幾個相依框架。在 Project Navigator 中選取專案,點 Build Phases 並展開 Link Binary With Libraries,用 + 號依序加入:
AVFoundation.framework
CoreData.framework
CoreLocation.framework
CoreText.framework
GLKit.framework
ImageIO.framework
libc++.dylib
libicucore.dylib
libz.dylib
OpenGLES.framework
QuartzCore.framework
SystemConfiguration.framework
最終你應該看到這樣的結果:

接著切到 Build Settings,找到 Other Linker Flags,把 -ObjC 指派給它。這是因為我們要把以 Objective-C 撰寫的地圖 SDK 連結進目前的 Swift 專案。

說到連結,不幸的是 Swift 目前還沒有直接嵌入 Objective-C 程式碼的方式。而我們必須這麼做,因為得引入 Google 地圖靜態庫的 Objective-C 標頭檔。實際上我們需要 Xcode 幫我們產生一個 bridging header,但沒有直接的做法,只能間接繞一圈:
1. 按 Command + N 在專案中加入新檔案。
2. 在檔案範本中選擇 Objective-C File,依向導命名為 temp 並建立。

3. 完成向導後,Xcode 會顯示如下提示,務必點 Yes。

4. 除了 temp.m,也會產生一個名為 GMapsDemo-Bridging-Header.h 的檔案。在編輯器中打開它,加入引入 Google 地圖標頭的程式碼:
#import <GoogleMaps/GoogleMaps.h>
5. 刪除 temp.m,我們不需要它。
最後,輪到使用前一節產生的 API Key。打開 AppDelegate.swift,在 application(_:didFinishLaunchingWithOptions:) 中加入:
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
// Override point for customization after application launch.
GMSServices.provideAPIKey("YOUR_API_KEY")
return true
}記得把 "YOUR_API_KEY" 換成你在 Developers Console 取得的真實 Key。要注意的是,如果漏掉了前面的橋接與引入標頭步驟,你根本無法存取 GoogleMaps 框架與它的類別。
初始化到此完成,我們可以開始寫程式了。如同本節開頭所說,使用外部 SDK 這類配置無法避免,但值得慶幸的是,這些前置工作雖然繁瑣,每一步都不難。
現在來把 Google 地圖第一次加進 App。你會發現這出乎意料地簡單。
打開 Main.storyboard,你會注意到 View Controller 場景正中央有一個視圖(UIView)。

這個視圖將作為我們的地圖視圖,但要這樣用它,得先做一些修改。選取它並打開 Utilities 面板,找到 Identity Inspector,在 Custom Class 的 Class 欄位把類別設為 GMSMapView。這個 GMSMapView 是 Google Maps 框架的一部分,實際上是 UIView 的子類別。
還有一處修改要在 ViewController.swift 中完成。在類別頂部你會找到這樣的 IBOutlet 宣告:
@IBOutlet weak var viewMap: UIView!
我們要把 viewMap 的型別從 UIView 改成 GMSMapView:
@IBOutlet weak var viewMap: GMSMapView!
這樣一來,我們就能把 viewMap 當作地圖視圖使用了。
把 Google 地圖加進 App 真的非常容易,只要在 viewDidLoad 中加上兩行:
override func viewDidLoad() {
super.viewDidLoad()
let camera: GMSCameraPosition = GMSCameraPosition.cameraWithLatitude(48.857165, longitude: 2.354613, zoom: 8.0)
viewMap.camera = camera
}設定地圖的第一步是初始化一個 GMSCameraPosition 物件,用它指定地圖顯示的初始位置。上圖座標以巴黎為中心,你可以替換成其他座標(這裡只是示範)。除了座標,還要指定初始縮放層級。
接著把這個物件指派給地圖視圖的 camera 屬性,實際地圖就能在 viewMap 中渲染出來了。
現在可以第一次執行 App,用真機或模擬器,等地圖出現吧。

進入下一節前,我們先擴充一下。做一個 action sheet 讓使用者能切換地圖類型。Maps SDK 在 iOS 中提供三種:
標準(Normal)
地形(Terrain)
混合(Hybrid)
標準模式是預設值,如上圖所示;另外兩種會依類型改變地圖外觀。如果我們能讓使用者切換它們,那就更好了。
地圖視圖有一個名為 mapType 的屬性,SDK 中以三個常數代表三種類型:
kGMSTypeNormal
kGMSTypeTerrain
kGMSTypeHybrid
現在到 changeMapType(_:) 這個 IBAction 方法中,加上顯示 action sheet 並設定地圖類型的程式碼:
@IBAction func changeMapType(sender: AnyObject) {
let actionSheet = UIAlertController(title: "Map Types", message: "Select map type:", preferredStyle: UIAlertControllerStyle.ActionSheet)
let normalMapTypeAction = UIAlertAction(title: "Normal", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.viewMap.mapType = kGMSTypeNormal
}
let terrainMapTypeAction = UIAlertAction(title: "Terrain", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.viewMap.mapType = kGMSTypeTerrain
}
let hybridMapTypeAction = UIAlertAction(title: "Hybrid", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.viewMap.mapType = kGMSTypeHybrid
}
let cancelAction = UIAlertAction(title: "Close", style: UIAlertActionStyle.Cancel) { (alertAction) -> Void in }
actionSheet.addAction(normalMapTypeAction)
actionSheet.addAction(terrainMapTypeAction)
actionSheet.addAction(hybridMapTypeAction)
actionSheet.addAction(cancelAction)
presentViewController(actionSheet, animated: true, completion: nil)
}這裡沒什麼難處。如你所見,每個 action(除了關閉)都設定了對應的地圖類型。
再次執行 App,這次只要點最右邊的工具列按鈕,就能切換地圖類型。

在螢幕上顯示地圖固然有趣,但若沒有指向任何對象,就沒什麼實用價值。從本節開始,我們逐步加上真正實用的功能。
使用地圖時最常見的任務就是指出用戶目前位置。這做起來很簡單,但需要用戶授權。從 iOS 8 開始,申請權限分成兩步:首先必須在 Info.plist 中加入一個條目,key 是所需權限的類型,value 是描述文字——這段文字會在 App 首次執行時於警告視圖中呈現給用戶;第二步是以程式碼請求權限,這會觸發警告視圖出現。
使用 Core Location 服務時(我們這裡會用到很多),App 會監控位置更新,要嘛持續監控(即使 App 在背景執行),要嘛僅在 App 使用期間監控。前面提到的權限就是為此而設:依我們希望 App 如何監控位置變化,在 plist 中提供對應的 key,再在程式碼中請求對應權限。我們的情況不需要持續監控——App 沒在跑時監控位置毫無意義,還會大量耗電。
在 Project Navigator 中找到並打開 Info.plist,透過 Editor > Add Item 新增一個條目,key 設為 NSLocationWhenInUseUsageDescription,value 填一段描述,例如:「允許存取你的位置,如此一來你可以在地圖上定位自己。」(不含引號)

回到 ViewController.swift,先宣告兩個接下來會用到的屬性,加在 IBOutlet 宣告之後:
var locationManager = CLLocationManager() var didFindMyLocation = false
locationManager 用來向用戶請求定位權限,並依授權狀態決定是否顯示他的目前位置;didFindMyLocation 則用來標記位置是否已定位成功,避免後續不必要的位置更新。
先處理要緊事。locationManager 在宣告時就已初始化,但這還不夠。在 viewDidLoad 中我們必須把它設為自身的 delegate,並向用戶請求權限:
override func viewDidLoad() {
...
locationManager.delegate = self
locationManager.requestWhenInUseAuthorization()
}注意此處的請求類型必須與 plist 中新增的一致。呼叫 requestWhenInUseAuthorization() 之後,要嘛 App 首次執行時彈出警告視圖請求定位權限,要嘛系統直接回傳用戶先前的選擇。無論哪種情況,我們都必須透過 CLLocationManagerDelegate 的代理方法檢查授權狀態——先讓類別採用這個協議:
class ViewController: UIViewController, CLLocationManagerDelegate {
...
}來看代理方法:
func locationManager(manager: CLLocationManager!, didChangeAuthorizationStatus status: CLAuthorizationStatus) {
if status == CLAuthorizationStatus.AuthorizedWhenInUse {
viewMap.myLocationEnabled = true
}
}我們唯一在意的情況就是授權狀態等於上圖所示的值。此時只要把地圖視圖的 myLocationEnabled 設為 true,Maps SDK 就會去完成尋找用戶位置的繁重工作。
用戶目前位置由地圖視圖的 myLocation 屬性描述。關於這個屬性的好消息是它支援 KVO(鍵值觀察),代表我們可以直接觀察它的變化,因此位置更新時我們就能收到通知。想深入了解 KVO 的話,可以參考相關入門文章。
因此下一步,讓我們的類別觀察 viewMap 的 myLocation 屬性。回到 viewDidLoad 加上:
override func viewDidLoad() {
...
viewMap.addObserver(self, forKeyPath: "myLocation", options: NSKeyValueObservingOptions.New, context: nil)
}當 SDK 定位到用戶位置時,我們真正想要的是讓該位置位於地圖中央,並以那顆廣為人知的藍點顯示。好消息是藍點會自動出現,不必額外寫程式。所以只要位置被定位到、而我們還沒處理過,就把視角移到該處:
override func observeValueForKeyPath(keyPath: String, ofObject object: AnyObject, change: [NSObject : AnyObject], context: UnsafeMutablePointer) {
if !didFindMyLocation {
let myLocation: CLLocation = change[NSKeyValueChangeNewKey] as CLLocation
viewMap.camera = GMSCameraPosition.cameraWithTarget(myLocation.coordinate, zoom: 10.0)
viewMap.settings.myLocationButton = true
didFindMyLocation = true
}
}如前面所說,didFindMyLocation 能幫 App 避免重複的位置更新。另外,我們從變更字典中取得新的位置——這個字典由系統以參數形式傳入,用 NSKeyValueChangeNewKey 這個 key 就能取到被觀察屬性的新值。有了位置資訊後,我們建立一個 GMSCameraPosition 並直接指派給 camera 屬性,視角便會以新位置為中心。
這裡還有一個有趣細節:把地圖視圖 settings 中的 myLocationButton 設為 true,就能在螢幕右下角顯示一個「回到目前位置」的預設按鈕,避免用戶移動地圖後找不到自己。這個按鈕由 SDK 提供。指南針按鈕也能以同樣方式啟用,但這裡我們不需要。
現在可以再試一次。如果你在模擬器中測試,必須提供一個假位置,因為真實位置不會被模擬器偵測到。做法是編輯 scheme,在 Options 分頁中選擇一個預設位置:

比找到用戶位置更進一步,另一個常見場景是定位自訂位置。通常做法是給地圖 API 一個地址(街道、城市、國家、區域),而不是經緯度——畢竟沒人能記住座標。但你會不會好奇:地圖服務並不知道座標,怎麼可能定位到你給的確切地址?
答案是有一個名為 geocoding 的過程,會在地圖定位之前把地址翻譯成經緯度。也就是說,像 Google Maps 這樣的地圖服務其實根本不「認識」地址,它只是把地址「翻譯」成地理座標。因此真正有趣的地方在於:我們如何把地址交給 Google Maps SDK,它又如何轉換成座標,最後顯示到地圖上。
值得慶幸的是,Google 提供了 Google Geocoding API——一個 web 服務,接受包含真實地址的請求,回傳經度與緯度。如果你真的對 Google 地圖有興趣,絕對該讀讀 geocoding API 文件。我建議你現在就去看一眼服務細節,這會幫你更好理解我們下一步要做的事。
geocoding API 的回應資料可以是 JSON 或 XML 格式。本範例使用 JSON,因為它一行程式碼就能轉換成 Swift(或 Objective-C)的資料結構(字典或陣列)。以下範例直接取自 Google 文件,是 JSON 回應的極好示範:
{
"results" : [
{
"address_components" : [
{
"long_name" : "1600",
"short_name" : "1600",
"types" : [ "street_number" ]
},
{
"long_name" : "Amphitheatre Pkwy",
"short_name" : "Amphitheatre Pkwy",
"types" : [ "route" ]
},
{
"long_name" : "Mountain View",
"short_name" : "Mountain View",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Clara",
"short_name" : "Santa Clara",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "California",
"short_name" : "CA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "94043",
"short_name" : "94043",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry" : {
"location" : {
"lat" : 37.42291810,
"lng" : -122.08542120
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 37.42426708029149,
"lng" : -122.0840722197085
},
"southwest" : {
"lat" : 37.42156911970850,
"lng" : -122.0867701802915
}
}
},
"types" : [ "street_address" ]
}
],
"status" : "OK"
}仔細看,這個回應以兩種方式表達了找到的地址:一是地址組件(一個陣列,元素是字典),二是 formatted_address(整段地址組成一字串)。此外還有兩個更有趣的部分:包含經緯度的 geometry 字典,以及明確描述請求結果的 status。
我們在 App 中會用到三樣東西:格式化地址、地理詳情與狀態。建議你看看 Google 文件中的狀態碼;在這裡討論已超出教程範圍。往下走之前,請確保你能「讀懂」JSON 的結構。如果你對 JSON 還不適應,值得先補一下基礎。提醒一下:以「」包住的是字典,以中括號 [ 開始的是陣列。
回到 App。我們要建立一個新類別,負責向 geocoding API 發請求並處理回應。之所以用新類別有兩個理由:
程式碼更容易複用。
之後我們還會用到另一個 Google web 服務,把這類任務集中在一處是好習慣。
建立一個新類別,確認它是 NSObject 的子類別,命名為 MapTasks 並加入專案。
開始在 MapTasks.swift 中工作,先宣告幾個屬性:
let baseURLGeocode = "https://maps.googleapis.com/maps/api/geocode/json?" var lookupAddressResults: Dictionary! var fetchedFormattedAddress: String! var fetchedAddressLongitude: Double! var fetchedAddressLatitude: Double!
baseURLGeocode 是我們發請求時使用的基本 URL,地址會以參數方式附加(因為地址是動態值,必須程式化組出)。lookupAddressResults 用來存放回傳的第一個地址——注意,一個地址可能返回多筆結果,但為了簡化,我們只保留第一筆。最後三個屬性顧名思義。
接著加上初始化函式,方便之後在 ViewController 中建立物件。由於沒有自訂初始化的必要,用預設的就好:
override init() {
super.init()
}現在建立這個新方法:
func geocodeAddress(address: String!, withCompletionHandler completionHandler: ((status: String, success: Bool) -> Void)) { }第一個參數是我想在地圖上定位的地址;第二個是 completion handler,一旦我們收到並處理完回應就會呼叫它。App 只會在這個 handler 被呼叫後才把結果顯示到地圖上。如你所見,這個 handler 有兩個參數:第一個是從回應中擷取的狀態字串,第二個由我們決定 geocoding 是否成功(也就是我們是否拿到了地圖所需的資料)。
現在逐步實作。首先正確組出 URL 字串、轉成合適格式,再建立 NSURL 物件。注意我們先確認傳入的地址合法:
if let lookupAddress = address {
var geocodeURLString = baseURLGeocode + "address=" + lookupAddress
geocodeURLString = geocodeURLString.stringByAddingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
let geocodeURL = NSURL(string: geocodeURLString)
}接著向 geocoding API 發出請求,並把回傳結果存進 NSData。這裡有個關鍵細節:整個過程(包括資料處理)都以非同步方式進行,讓 App 在等待資料期間仍能保持響應。從 API 取到資料後,我們把它從 JSON 轉成字典:
dispatch_async(dispatch_get_main_queue(), { () -> Void in
let geocodingResultsData = NSData(contentsOfURL: geocodeURL!)
var error: NSError?
let dictionary: Dictionary = NSJSONSerialization.JSONObjectWithData(geocodingResultsData!, options: NSJSONReadingOptions.MutableContainers, error: &error) as Dictionary
})最後一行就是把資料從 JSON 轉為 Swift 的表示方式。
如你所注意,我們用 NSError 物件「捕捉」轉換過程中可能的錯誤。因此現在最該關心的是:轉換之後 error 是否為 nil。若不是,就呼叫 handler 並把標記設為 false:
if (error != nil) {
println(error)
completionHandler(status: "", success: false)
}如果一切順利,先取得回應的狀態。若它等於 "OK",我們就取出第一筆結果存進 lookupAddressResults,再取得其餘感興趣的值(格式化地址、經度、緯度)。若狀態不是 "OK",則呼叫 handler 並傳入狀態值,同時把標記設為 false:
else {
// Get the response status.
let status = dictionary["status"] as String
if status == "OK" {
let allResults = dictionary["results"] as Array
self.lookupAddressResults = allResults[0]
// Keep the most important values.
self.fetchedFormattedAddress = self.lookupAddressResults["formatted_address"] as String
let geometry = self.lookupAddressResults["geometry"] as Dictionary
self.fetchedAddressLongitude = ((geometry["location"] as Dictionary)["lng"] as NSNumber).doubleValue
self.fetchedAddressLatitude = ((geometry["location"] as Dictionary)["lat"] as NSNumber).doubleValue
completionHandler(status: status, success: true)
} else {
completionHandler(status: status, success: false)
}
}這其實就是方法的「核心」。注意上面用到的 key 名稱都來自我先前給你的 JSON 範例,你也可以在 Google Geocoding API 文件中找到它們。
最後還有一種情況要處理:傳入的地址是 nil。
else {
completionHandler(status: "No valid address.", success: false)
}這次我們在 status 參數中提供一則自訂訊息。
以下是完整的方法:
func geocodeAddress(address: String!, withCompletionHandler completionHandler: ((status: String, success: Bool) -> Void)) {
if let lookupAddress = address {
var geocodeURLString = baseURLGeocode + "address=" + lookupAddress
geocodeURLString = geocodeURLString.stringByAddingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
let geocodeURL = NSURL(string: geocodeURLString)
dispatch_async(dispatch_get_main_queue(), { () -> Void in
let geocodingResultsData = NSData(contentsOfURL: geocodeURL!)
var error: NSError?
let dictionary: Dictionary = NSJSONSerialization.JSONObjectWithData(geocodingResultsData!, options: NSJSONReadingOptions.MutableContainers, error: &error) as Dictionary
if (error != nil) {
println(error)
completionHandler(status: "", success: false)
} else {
let status = dictionary["status"] as String
if status == "OK" {
let allResults = dictionary["results"] as Array
self.lookupAddressResults = allResults[0]
self.fetchedFormattedAddress = self.lookupAddressResults["formatted_address"] as String
let geometry = self.lookupAddressResults["geometry"] as Dictionary
self.fetchedAddressLongitude = ((geometry["location"] as Dictionary)["lng"] as NSNumber).doubleValue
self.fetchedAddressLatitude = ((geometry["location"] as Dictionary)["lat"] as NSNumber).doubleValue
completionHandler(status: status, success: true)
} else {
completionHandler(status: status, success: false)
}
}
})
} else {
completionHandler(status: "No valid address.", success: false)
}
}是時候用上這個方法了。回到 ViewController.swift,先宣告並初始化一個 MapTasks 物件:
var mapTasks = MapTasks()
接著找到 findAddress(_:) 這個 IBAction——左邊的工具列按鈕被按下時會呼叫它。在方法內,我們建立一個帶文字輸入框的警告控制器,請用戶輸入地址,並提供兩個按鈕:一個啟動搜尋,一個取消。按下第一個按鈕時,我們呼叫剛才建立的方法,然後處理 completion handler 的結果:
@IBAction func findAddress(sender: AnyObject) {
let addressAlert = UIAlertController(title: "Address Finder", message: "Type the address you want to find:", preferredStyle: UIAlertControllerStyle.Alert)
addressAlert.addTextFieldWithConfigurationHandler { (textField) -> Void in
textField.placeholder = "Address?"
}
let findAction = UIAlertAction(title: "Find Address", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
let address = (addressAlert.textFields![0] as UITextField).text as String
self.mapTasks.geocodeAddress(address, withCompletionHandler: { (status, success) -> Void in
...
})
}
let closeAction = UIAlertAction(title: "Close", style: UIAlertActionStyle.Cancel) { (alertAction) -> Void in }
addressAlert.addAction(findAction)
addressAlert.addAction(closeAction)
presentViewController(addressAlert, animated: true, completion: nil)
}在 completion handler 的程式碼區塊中,我們要處理結果。若 success 為 false,就把狀態印到 console;此外,若狀態等於 "ZERO_RESULTS",就顯示另一個警告控制器告知用戶找不到該地址(狀態碼可參考 Google 文件)。另一方面,若一切正常,就讓地圖以新位置為中心:
@IBAction func findAddress(sender: AnyObject) {
...
let createRouteAction... // 略
self.mapTasks.geocodeAddress(address, withCompletionHandler: { (status, success) -> Void in
if !success {
println(status)
if status == "ZERO_RESULTS" {
self.showAlertWithMessage("The location could not be found.")
}
} else {
let coordinate = CLLocationCoordinate2D(latitude: self.mapTasks.fetchedAddressLatitude, longitude: self.mapTasks.fetchedAddressLongitude)
self.viewMap.camera = GMSCameraPosition.cameraWithTarget(coordinate, zoom: 14.0)
}
})
...
}showAlertWithMessage(_:) 是另一個自訂方法,只負責用指定訊息顯示一個警告控制器,屬於明確可複用的程式碼:
func showAlertWithMessage(message: String) {
let alertController = UIAlertController(title: "GMapsDemo", message: message, preferredStyle: UIAlertControllerStyle.Alert)
let closeAction = UIAlertAction(title: "Close", style: UIAlertActionStyle.Cancel) { (alertAction) -> Void in }
alertController.addAction(closeAction)
presentViewController(alertController, animated: true, completion: nil)
}準備好了。再次執行 App,這次輸入一個地址,它會指向地圖上的某處。如果地址輸入正確,地圖就會以該處為中心。

在地圖上加一個標記是非常簡單的工作,基本上兩行程式碼就能完成。不過有多種屬性可以設定,讓標記依你的需求與偏好客製化。在 Google Maps SDK 中,標記是 GMSMarker 類別的物件。初始化時必須指定以 CLLocationCoordinate2D 表示的經緯度。前一節我們已建立過這樣的物件:
let coordinate = CLLocationCoordinate2D(latitude: self.mapTasks.fetchedAddressLatitude, longitude: self.mapTasks.fetchedAddressLongitude)
標記物件初始化後,SDK 就知道該放在哪裡;接著只要為它指定一個地圖物件,標記就會被加到那張地圖上。
先看程式碼怎麼寫。首先宣告一個標記屬性,好讓我們能持有強引用。到 ViewController 類別開頭加上:
var locationMarker: GMSMarker!
接著定義這個方法。每次自訂地址被定位到地圖時我們都會呼叫它,因此把位置作為參數傳入:
func setupLocationMarker(coordinate: CLLocationCoordinate2D) { }需要的座標物件會以參數形式提供。來初始化標記:
func setupLocationMarker(coordinate: CLLocationCoordinate2D) {
locationMarker = GMSMarker(position: coordinate)
locationMarker.map = viewMap
}回到 findAddress(_:) 並再加一行,讓自訂位置被找到、地圖也調整到以它為中心時呼叫上述方法:
@IBAction func findAddress(sender: AnyObject) {
...
self.mapTasks.geocodeAddress(address, withCompletionHandler: { (status, success) -> Void in
...
else {
let coordinate = CLLocationCoordinate2D(latitude: self.mapTasks.fetchedAddressLatitude, longitude: self.mapTasks.fetchedAddressLongitude)
self.viewMap.camera = GMSCameraPosition.cameraWithTarget(coordinate, zoom: 14.0)
self.setupLocationMarker(coordinate)
}
})
...
}再次執行並輸入自訂地址,現在會有一個標記正好指向新位置。
如本節開頭所說,標記有多種屬性可做一定程度的客製化。例如指定顏色、被點擊時顯示文字,或改變不透明度。我們來擴充上述方法,設定其中幾個屬性:
func setupLocationMarker(coordinate: CLLocationCoordinate2D) {
...
locationMarker.title = mapTasks.fetchedFormattedAddress
locationMarker.appearAnimation = kGMSMarkerAnimationPop
locationMarker.icon = GMSMarker.markerImageWithColor(UIColor.blueColor())
locationMarker.opacity = 0.75
}透過 title 屬性,標記被點擊時會顯示從 mapTasks 取得的格式化地址。appearAnimation 指定標記是否以動畫方式出現,我們指派的是 SDK 提供的選項之一。關於顏色,如你所見它不能被直接改變;相反地,我們要存取 icon 屬性並以圖片形式提供所需顏色,後續都由 GMSMarker 處理,我們不必操心。最後我們也改了不透明度。以上程式碼會產生一個略微透明、以彈跳動畫出現的藍色標記。
當你旋轉地圖或用手勢改變視角時,標記會留在原位。不過這個行為是可以改的:告訴 SDK 你希望標記是「平貼」的,它就會依手勢一起透視變形。
此外,也可以在點擊標記時彈出的氣泡中加上額外文字,這要指派給標記的 snippet 屬性。
以下是這兩個功能的實作:
func setupLocationMarker(coordinate: CLLocationCoordinate2D) {
...
locationMarker.flat = true
locationMarker.snippet = "The best place on earth."
}再次執行 App,你就能看到所有修改後的效果。
進入下一節前,還有一個細節必須說明。我們在上面方法中建立的標記,會在每次找到新的自訂地址時被加到地圖上。然而這個流程有問題——除非我們先移除舊的(如果已存在),否則會出錯。因此要在方法開頭加上條件:
func setupLocationMarker(coordinate: CLLocationCoordinate2D) {
if locationMarker != nil {
locationMarker.map = nil
}
...
}上面提到的屬性並非 SDK 的全部,鼓勵你去翻官方文件,肯定能找到更多好用的東西。

除了 Geocode API,Google 還提供了其他能與 Maps SDK 搭配的 web 服務,其中之一是 Directions API,它能幫我們在地圖上建立路線。路線本質上是連接兩個地點的線段,而且除了起點與終點外,還可以包含中途位置——這些中途位置稱為航路點(waypoint)。
我們向 Directions API 發請求的方式與 Geocode API 十分相似:提供所需參數,再處理回傳的 JSON 或 XML 資料。現在是查看 Directions API 文件的好時機,特別是 sample responses 那一節,你可以在那裡找到 JSON 回應的絕佳範例。
實作之前,理解路線的一些基本結構以及 API 回傳的資料非常重要。我在這裡只強調幾個重點,更多細節請參考官方文件。
首先,Directions API 的單次回應可以給出從 A 到 B 的多條可能路線(本範例只使用第一條,其餘忽略)。每條路線由多段 legs 組成,每段 leg 是整趟旅程的一部分。
接著,每段 leg 又由多個 steps 組成。step 是一個方向單元,指示路線該如何走。每個 step 都帶有自己的實用資料:行駛距離、耗時、起訖位置,以及在地圖上繪製該 step 所需的點。實際上還有更多,但我刻意只提這些,方便你在後續閱讀時對照。
除了 legs 與 steps,路線還包含其他有用資料。其中一項是 Google 文件回應範例中標示為 overview_polyline 的資料,它包含了繪製整條路線所需的所有點(polyline 即折線,是在地圖上畫出路徑所需的線段集合)。本範例會使用這項資料,但我必須事先提醒:這條 overview polyline 並不精準,它是真實路線的一種近似。對包含少量 legs 的短距離而言,它表現得不錯;但有些情況下,依它繪出的路線會漏掉一些轉彎或路段。實際上,legs 與 steps 越多,這個 overview 就越不準。
解法是逐一走訪每段 leg 的每個 step,收集各自的折線點,再一段段畫出路線。但我們不在這裡實作它,因為那會讓範例變得過度複雜,而我們必須保持簡單易懂。我們就沿用 overview polyline,讓你看看它怎麼用,之後你完全可以自行改進。
來寫程式吧。切到 MapTasks.swift,先宣告以下類別屬性:
let baseURLDirections = "https://maps.googleapis.com/maps/api/directions/json?" var selectedRoute: Dictionary! var overviewPolyline: Dictionary! var originCoordinate: CLLocationCoordinate2D! var destinationCoordinate: CLLocationCoordinate2D! var originAddress: String! var destinationAddress: String!
各屬性的用途:
selectedRoute 存放從 Directions API 回傳的第一條路線(在全部路線之中)。它是字典,內部還包含其他字典與陣列。
overviewPolyline 持有 overview polyline 的字典,其中還有一個字典,存放繪製線段所需的點。
originCoordinate 與 destinationCoordinate 都是 CLLocationCoordinate2D,分別代表起點與終點的經緯度。
originAddress 與 destinationAddress 以字串形式持有起點與終點地址,內容來自 API 回應。
宣告完成後,接著定義方法:
func getDirections(origin: String!, destination: String!, waypoints: Array!, travelMode: AnyObject!, completionHandler: ((status: String, success: Bool) -> Void)) { }除了起點與終點(以地址表示),這個方法還接受兩個參數:航路點陣列(路線中的中途點),以及旅程的行進模式。透過行進模式,我們能定義以何種方式規劃路線——開車、步行還是騎自行車。最後一個參數是已知的 completion handler,當我們把資料套用到地圖上時會呼叫它。
目前我們先不理會航路點與行進模式,只用起點與終點地址。如我先前所說,你至少會看到一些與 Geocode API 相似之處。首先要用這兩個地址組出請求的 URL,再轉成 NSURL:
func getDirections(origin: String!, destination: String!, waypoints: Array!, travelMode: AnyObject!, completionHandler: ((status: String, success: Bool) -> Void)) {
if let originLocation = origin {
if let destinationLocation = destination {
var directionsURLString = baseURLDirections + "origin=" + originLocation + "&destination=" + destinationLocation
directionsURLString = directionsURLString.stringByAddingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
let directionsURL = NSURL(string: directionsURLString)
} else {
completionHandler(status: "Destination is nil.", success: false)
}
} else {
completionHandler(status: "Origin is nil", success: false)
}
}值得注意:當起點或終點地址為 nil 時,我們在對應的 else 分支中呼叫 handler,指示取得路線失敗,同時傳出自訂訊息。
下一步是用剛建立的 URL 向 Directions API 請求路線。回傳資料為 JSON,所有作業都以非同步方式進行。以下程式碼先取得 JSON,再轉為字典,並處理可能的錯誤:
dispatch_async(dispatch_get_main_queue(), { () -> Void in
let directionsData = NSData(contentsOfURL: directionsURL!)
var error: NSError?
let dictionary: Dictionary = NSJSONSerialization.JSONObjectWithData(directionsData!, options: NSJSONReadingOptions.MutableContainers, error: &error) as Dictionary
if (error != nil) {
println(error)
completionHandler(status: "", success: false)
} else {
...
}
})這部分沒有新東西。有趣的地方在 else 分支中新增的程式碼:
let status = dictionary["status"] as String
if status == "OK" {
self.selectedRoute = (dictionary["routes"] as Array)[0]
self.overviewPolyline = self.selectedRoute["overview_polyline"] as Dictionary
let legs = self.selectedRoute["legs"] as Array
let startLocationDictionary = legs[0]["start_location"] as Dictionary
self.originCoordinate = CLLocationCoordinate2DMake(startLocationDictionary["lat"] as Double, startLocationDictionary["lng"] as Double)
let endLocationDictionary = legs[legs.count - 1]["end_location"] as Dictionary
self.destinationCoordinate = CLLocationCoordinate2DMake(endLocationDictionary["lat"] as Double, endLocationDictionary["lng"] as Double)
self.originAddress = legs[0]["start_address"] as String
self.destinationAddress = legs[legs.count - 1]["end_address"] as String
self.calculateTotalDistanceAndDuration()
completionHandler(status: status, success: true)
} else {
completionHandler(status: status, success: false)
}先通讀一遍。首先取得回應狀態,僅當它等於 "OK" 時才繼續。在此情況下,第一件事是讓 selectedRoute 持有第一條找到的路線(為了簡化,若有多條則忽略)。透過這個字典,我們直接存取 overview polyline,取得繪製路線所需的點(即使是近似的)。接著在區域宣告的 legs 陣列中存放所有路段,因為我們稍後需要它來取得起訖位置的資料。
注意我們如何取得起點與終點的座標,以及它們的名稱。對起點,我們用第一條 leg;對終點,我們用最後一條(legs.count - 1)。
就在呼叫 completion handler 之前,我們呼叫了一個自訂方法 calculateTotalDistanceAndDuration()——你這是第一次看到它,可以暫時理解為「計算旅程距離與時間」。稍後我們會實作它。
以下是 getDirections 的完整實作:
func getDirections(origin: String!, destination: String!, waypoints: Array!, travelMode: AnyObject!, completionHandler: ((status: String, success: Bool) -> Void)) {
if let originLocation = origin {
if let destinationLocation = destination {
var directionsURLString = baseURLDirections + "origin=" + originLocation + "&destination=" + destinationLocation
directionsURLString = directionsURLString.stringByAddingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
let directionsURL = NSURL(string: directionsURLString)
dispatch_async(dispatch_get_main_queue(), { () -> Void in
let directionsData = NSData(contentsOfURL: directionsURL!)
var error: NSError?
let dictionary: Dictionary = NSJSONSerialization.JSONObjectWithData(directionsData!, options: NSJSONReadingOptions.MutableContainers, error: &error) as Dictionary
if (error != nil) {
println(error)
completionHandler(status: "", success: false)
} else {
let status = dictionary["status"] as String
if status == "OK" {
self.selectedRoute = (dictionary["routes"] as Array)[0]
self.overviewPolyline = self.selectedRoute["overview_polyline"] as Dictionary
let legs = self.selectedRoute["legs"] as Array
let startLocationDictionary = legs[0]["start_location"] as Dictionary
self.originCoordinate = CLLocationCoordinate2DMake(startLocationDictionary["lat"] as Double, startLocationDictionary["lng"] as Double)
let endLocationDictionary = legs[legs.count - 1]["end_location"] as Dictionary
self.destinationCoordinate = CLLocationCoordinate2DMake(endLocationDictionary["lat"] as Double, endLocationDictionary["lng"] as Double)
self.originAddress = legs[0]["start_address"] as String
self.destinationAddress = legs[legs.count - 1]["end_address"] as String
self.calculateTotalDistanceAndDuration()
completionHandler(status: status, success: true)
} else {
completionHandler(status: status, success: false)
}
}
})
} else {
completionHandler(status: "Destination is nil.", success: false)
}
} else {
completionHandler(status: "Origin is nil", success: false)
}
}現在,就在實作計算距離與時間的新方法前,我們要在類別頂部宣告幾個屬性:
var totalDistanceInMeters: UInt = 0 var totalDistance: String! var totalDurationInSeconds: UInt = 0 var totalDuration: String!
接著實作新方法。不幸的是,SDK 沒有直接計算路線總距離與時間的方法,我們必須走訪所有 legs 並逐段累加。距離以公尺計,時間以秒計。以下實作在計算完畢後,會把距離轉為公里,把時間轉成天、小時、分鐘與秒:
func calculateTotalDistanceAndDuration() {
let legs = self.selectedRoute["legs"] as Array
totalDistanceInMeters = 0
totalDurationInSeconds = 0
for leg in legs {
totalDistanceInMeters += (leg["distance"] as Dictionary)["value"] as UInt
totalDurationInSeconds += (leg["duration"] as Dictionary)["value"] as UInt
}
let distanceInKilometers: Double = Double(totalDistanceInMeters / 1000)
totalDistance = "Total Distance: \(distanceInKilometers) Km"
let mins = totalDurationInSeconds / 60
let hours = mins / 60
let days = hours / 24
let remainingHours = hours % 24
let remainingMins = mins % 60
let remainingSecs = totalDurationInSeconds % 60
totalDuration = "Duration: \(days) d, \(remainingHours) h, \(remainingMins) mins, \(remainingSecs) secs"
}回到 ViewController,先宣告以下屬性:
var originMarker: GMSMarker! var destinationMarker: GMSMarker! var routePolyline: GMSPolyline!
前兩個標記用來指示起點與終點,routePolyline 則是代表路線的折線。
現在在 createRoute(_:) 這個 IBAction 中,我們會顯示一個帶有兩個輸入框的警告控制器:第一個填起點,第二個填終點。取得這兩個值後建立路線——呼叫 Directions API,並依回傳結果設計路線、加上標記。
@IBAction func createRoute(sender: AnyObject) {
let addressAlert = UIAlertController(title: "Create Route", message: "Connect locations with a route:", preferredStyle: UIAlertControllerStyle.Alert)
addressAlert.addTextFieldWithConfigurationHandler { (textField) -> Void in
textField.placeholder = "Origin?"
}
addressAlert.addTextFieldWithConfigurationHandler { (textField) -> Void in
textField.placeholder = "Destination?"
}
let createRouteAction = UIAlertAction(title: "Create Route", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
let origin = (addressAlert.textFields![0] as UITextField).text as String
let destination = (addressAlert.textFields![1] as UITextField).text as String
self.mapTasks.getDirections(origin, destination: destination, waypoints: nil, travelMode: nil, completionHandler: { (status, success) -> Void in
if success {
self.configureMapAndMarkersForRoute()
self.drawRoute()
self.displayRouteInfo()
} else {
println(status)
}
})
}
let closeAction = UIAlertAction(title: "Close", style: UIAlertActionStyle.Cancel) { (alertAction) -> Void in }
addressAlert.addAction(createRouteAction)
addressAlert.addAction(closeAction)
presentViewController(addressAlert, animated: true, completion: nil)
}如你所注意,若路線請求成功,我們會呼叫三個新的自訂方法。用途從命名即可推知,我們逐一實作。
configureMapAndMarkersForRoute() 負責三件事:
把地圖調整到以路線起點為中心。
在起點加上一個標記。
在終點加上一個標記。
func configureMapAndMarkersForRoute() {
viewMap.camera = GMSCameraPosition.cameraWithTarget(mapTasks.originCoordinate, zoom: 9.0)
originMarker = GMSMarker(position: self.mapTasks.originCoordinate)
originMarker.map = self.viewMap
originMarker.icon = GMSMarker.markerImageWithColor(UIColor.greenColor())
originMarker.title = self.mapTasks.originAddress
destinationMarker = GMSMarker(position: self.mapTasks.destinationCoordinate)
destinationMarker.map = self.viewMap
destinationMarker.icon = GMSMarker.markerImageWithColor(UIColor.redColor())
destinationMarker.title = self.mapTasks.destinationAddress
}注意我們替標記設了不同顏色。
drawRoute() 負責在地圖上畫出路線線段。值得一提的是,靠著 GMSPath 與 GMSPolyline 這兩個類別,加上我們在 MapTasks 中取得的路線點,繪製路線變得非常容易。
func drawRoute() {
let route = mapTasks.overviewPolyline["points"] as String
let path: GMSPath = GMSPath(fromEncodedPath: route)
routePolyline = GMSPolyline(path: path)
routePolyline.map = viewMap
}在片段結尾,別忘了把地圖指派給 routePolyline。
displayRouteInfo() 非常簡單,我們只是在螢幕底部的標籤上顯示計算出的距離與時間:
func displayRouteInfo() {
lblInfo.text = mapTasks.totalDistance + "\n" + mapTasks.totalDuration
}就是這樣。我們走了不少新路,但一旦理解它們的含義,管理起來並不難。現在可以再次測試:指定起點與終點,讓路線產生。我必須重申,overview polyline 在某些情況下不如你預期精準,如果這對你來說不夠好,可以考慮實作前面描述的做法——走訪所有 legs 的所有 steps,收集每一步的點,再逐一畫到地圖上。

航路點是位於起點與終點之間的位置,實際上是路線的一部分。目前我們建立的路線沒有任何中途點,本節就來加上這個特性。這次我們不再用警告控制器輸入地址,而是直接觸碰地圖,路線便會重新計算;同時會在觸碰位置放上一個新標記。
記住這個目標,我們要先宣告並初始化兩個新陣列:
var markersArray: Array = [] var waypointsArray: Array = []
第一個陣列持有指向航路點的所有標記;第二個則以字串形式持有航路點。
接著,為了處理地圖上的觸碰並取得確切座標,我們需要使用 GMSMapViewDelegate 協議(存在於 Google Maps SDK 中)的代理方法。先讓類別採用此協議:
class ViewController: UIViewController, CLLocationManagerDelegate, GMSMapViewDelegate {
...
}也必須把 ViewController 設為地圖視圖的 delegate。在 viewDidLoad 中加上簡單一行:
override func viewDidLoad() {
...
viewMap.delegate = self
}來看代理方法,然後我們再討論:
func mapView(mapView: GMSMapView!, didTapAtCoordinate coordinate: CLLocationCoordinate2D) {
if let polyline = routePolyline {
let positionString = String(format: "%f", coordinate.latitude) + "," + String(format: "%f", coordinate.longitude)
waypointsArray.append(positionString)
recreateRoute()
}
}這裡第一個關鍵細節是:確保有這麼一條路線可以讓我們加航路點。這很容易檢查——只要確認路線的折線不是 nil。在此情況下,我們用 coordinate 參數組出一個字串,包含觸碰位置的緯度與經度。請務必確認字串中沒有空白字元,否則向 Directions API 的請求會失敗。字串準備好後,把它加入 waypointsArray,並呼叫全新的自訂方法 recreateRoute()(顧名思義,重新建立路線)。
在重繪包含新航路點的路線之前,我們必須先清除既有的路線。因此先建立一個名為 clearRoute() 的函式,稍後再實作 recreateRoute():
func clearRoute() {
originMarker.map = nil
destinationMarker.map = nil
routePolyline.map = nil
originMarker = nil
destinationMarker = nil
routePolyline = nil
if markersArray.count > 0 {
for marker in markersArray {
marker.map = nil
}
markersArray.removeAll(keepCapacity: false)
}
}如你所見,先前繪製路線的所有物件都設為 nil 並從地圖移除。注意我們也把 markersArray 中現有標記的 map 屬性設為 nil——雖然我們還沒寫把標記加入此陣列的程式碼,但先處理也無妨。
現在可以實作 recreateRoute():
func recreateRoute() {
if let polyline = routePolyline {
clearRoute()
mapTasks.getDirections(mapTasks.originAddress, destination: mapTasks.destinationAddress, waypoints: waypointsArray, travelMode: nil, completionHandler: { (status, success) -> Void in
if success {
self.configureMapAndMarkersForRoute()
self.drawRoute()
self.displayRouteInfo()
} else {
println(status)
}
})
}
}首先確保有一條路線可以清除。接著向 Directions API 發出請求,注意這次我們也傳入了 waypointsArray 參數。若一切正常,就呼叫前一節相同的方法把路線畫出來。
大部分工作已完成,但還有兩項任務。第一,要讓 configureMapAndMarkersForRoute() 具備加上航路點標記的能力:
func configureMapAndMarkersForRoute() {
...
if waypointsArray.count > 0 {
for waypoint in waypointsArray {
let lat: Double = (waypoint.componentsSeparatedByString(",")[0] as NSString).doubleValue
let lng: Double = (waypoint.componentsSeparatedByString(",")[1] as NSString).doubleValue
let marker = GMSMarker(position: CLLocationCoordinate2DMake(lat, lng))
marker.map = viewMap
marker.icon = GMSMarker.markerImageWithColor(UIColor.purpleColor())
markersArray.append(marker)
}
}
}注意我們如何把每個航路點字串拆解成欄位,再將經緯度轉為 double 值,用來初始化新標記。每個航路點對應的標記配置好後,就加入 markersArray。
第二項待辦是更新 MapTasks.swift 中的 getDirections(…) 方法。在方法開頭必須更新 directionsURLString,讓即將發出的請求包含我們需要的航路點。注意,除了傳遞航路點,我們也在查詢中指定了另一個參數,要求在使用航路點時對路線進行優化:
func getDirections(origin: String!, destination: String!, waypoints: Array!, travelMode: AnyObject!, completionHandler: ((status: String, success: Bool) -> Void)) {
if let originLocation = origin {
if let destinationLocation = destination {
var directionsURLString = baseURLDirections + "origin=" + originLocation + "&destination=" + destinationLocation
if let routeWaypoints = waypoints {
directionsURLString += "&waypoints=optimize:true"
for waypoint in routeWaypoints {
directionsURLString += "|" + waypoint
}
}
...
}
}
...
}現在可以再試一次。建立一條路線後,觸碰它周圍任意一點,該位置就會作為航路點加入路線。

建立路線時,Directions API 預設使用開車模式。如前面所說,Google Maps SDK 在 iOS 中支援的行進模式有:
開車
步行
騎自行車
切換行進模式是個有趣的功能,也很適合放進這個範例,本節就來實作。首先要建立一個列舉(enum),包含所有支援的行進模式。在 ViewController.swift 中、類別定義之前加上:
enum TravelModes: Int {
case driving
case walking
case bicycling
}接著在類別中宣告預設行進模式:
var travelMode = TravelModes.driving
為了切換行進模式,我們會用到 changeTravelMode(_:) 這個 IBAction。在方法中建立一個 action sheet,提供所有選項,並依用戶選擇設定對應的行進模式:
@IBAction func changeTravelMode(sender: AnyObject) {
let actionSheet = UIAlertController(title: "Travel Mode", message: "Select travel mode:", preferredStyle: UIAlertControllerStyle.ActionSheet)
let drivingModeAction = UIAlertAction(title: "Driving", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.travelMode = TravelModes.driving
self.recreateRoute()
}
let walkingModeAction = UIAlertAction(title: "Walking", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.travelMode = TravelModes.walking
self.recreateRoute()
}
let bicyclingModeAction = UIAlertAction(title: "Bicycling", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
self.travelMode = TravelModes.bicycling
self.recreateRoute()
}
let closeAction = UIAlertAction(title: "Close", style: UIAlertActionStyle.Cancel) { (alertAction) -> Void in }
actionSheet.addAction(drivingModeAction)
actionSheet.addAction(walkingModeAction)
actionSheet.addAction(bicyclingModeAction)
actionSheet.addAction(closeAction)
presentViewController(actionSheet, animated: true, completion: nil)
}如你所注意,每個 action 都設定了對應的行進模式,並呼叫前一節實作的 recreateRoute()。當然,關閉動作只是取消 action sheet。
以上還不會生效,因為 recreateRoute() 需要更新。目前的實作在呼叫 MapTasks 的 getDirections(…) 時,並未把行進模式傳入,而是設為 nil。來修正:
func recreateRoute() {
if let polyline = routePolyline {
...
mapTasks.getDirections(mapTasks.originAddress, destination: mapTasks.destinationAddress, waypoints: waypointsArray, travelMode: travelMode, completionHandler: { (status, success) -> Void in
...
})
}
}唯一改動的是 travelMode 參數。接著我們也要更新 getDirections(…),讓它考慮行進模式。切到 MapTasks.swift 加入:
func getDirections(origin: String!, destination: String!, waypoints: Array!, travelMode: TravelModes!, completionHandler: ((status: String, success: Bool) -> Void)) {
if let originLocation = origin {
if let destinationLocation = destination {
var directionsURLString = baseURLDirections + "origin=" + originLocation + "&destination=" + destinationLocation
...
if let travel = travelMode {
var travelModeString = ""
switch travelMode.rawValue {
case TravelModes.walking.rawValue:
travelModeString = "walking"
case TravelModes.bicycling.rawValue:
travelModeString = "bicycling"
default:
travelModeString = "driving"
}
directionsURLString += "&mode=" + travelModeString
}
...
}
}
...
}注意:除了加上 if let travel = travelMode { … },我們也需要把 travelMode 的參數型別從 AnyObject! 改為 TravelModes!(我們前面建立的列舉)。
現在夠好了,可以再次測試。切換一下行進模式,觀察路線資訊——特別是旅程時間——如何改變。
範例 App 幾乎完成了。我說「幾乎」,是因為還有兩個細節要補上,才能讓它盡可能正常運作。
第一,在建立新路線之前必須清除既有的路線。因此在 createRoute(_:) 的 createRouteAction 區塊中,要檢查是否已有路線並將它清除:
@IBAction func createRoute(sender: AnyObject) {
...
let createRouteAction = UIAlertAction(title: "Create Route", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
if let polyline = self.routePolyline {
self.clearRoute()
self.waypointsArray.removeAll(keepCapacity: false)
}
...
}
...
}注意:除了清除路線,我們也移除了 waypointsArray 中的所有物件。既然要建一條新路線,就沒有理由保留任何舊航路點。
第二,要再次把行進模式作為參數傳入 IBAction 方法,因為目前我們只把值設為 nil:
@IBAction func createRoute(sender: AnyObject) {
...
let createRouteAction = UIAlertAction(title: "Create Route", style: UIAlertActionStyle.Default) { (alertAction) -> Void in
...
self.mapTasks.getDirections(origin, destination: destination, waypoints: nil, travelMode: self.travelMode, completionHandler: { (status, success) -> Void in
...
})
...
}
...
}完成這兩件事之後,我們的範例 App 就真正完成了。
在本教程的各節中,我們把開發者在用地圖時最重要的任務都走了一遍,使用的都是 iOS 版 Google Maps SDK。如果你打算使用 Google 地圖,前面讀過的所有章節足以把你帶上正確軌道,而且你現在已經有一個可運作的起點。
無庸置疑,Google Maps SDK 還有大量細節無法在一篇文章中涵蓋。但現在你已經掌握了它最基本也最重要的部分,接下來可以投入 Google 文件,查詢任何額外資訊。用地圖是個非常有趣的題目,無論過程中遇到什麼困難,最後它都值得你投入。
如果你正在用、或計畫使用 Google Maps SDK,希望本文提供的資訊對你有幫助。把它當作一份指南,沒有什麼能阻擋你深入其中,充分利用所有 API。
作為參考,完整 Xcode 專案可另行下載。一如既往,歡迎留言分享你對這篇教程的想法。