Mapbox iOS SDK 入门操作指南

Mapbox iOS SDK是针对 iOS 系统的矢量地图库。本指南会指导你安装 Mapbox iOS SDK，使用 Xcode 和 storyboards 载入地图、改变地图样式（style）、添加注释（annotation）以及定位用户位置。包括基于 Objective-C 语言和 Swift 语言的操作。

喜大普奔 — 新手免费套餐（free Starter plan） 将包含 50000 个月度用户名额，这些用户在手机端的地图视图数不受限制。

要注意！我们仍在持续完善 Mapbox iOS SDK，该手册的内容也会同步更新。

入门

要开始操作，你需要获取：

• 一个 access token.可在 account page 找到。

• Xcode 和 Apple’s iOS SDK.可以在 Mac App Store 中免费获取。

• Apple Developer Account (可选).可使用个人设备或 Xcode 的 iOS Simulator 代替苹果开发者账户。如需和别人共享该程序，需要付费注册一个账户。

Setting up in Xcode

打开 Xcode，依次点击 File ‣ New ‣ Project 创建新项目。找到 iOS 下的 Application 选项，选择Single View Application模板。

将新项目命名为My First Mapbox App。（根据你的喜好）选择Objective-C或Swift语言，设备选择iPhone。该步骤将引导你创建一个 iPhone 应用程序。如果你想创建一个同时支持 iPhone 和 iPad 的程序，可在设备一栏选择Universal。

点击Next创建本地文件夹，Xcode 会将你所有的文件储存在其中。

设置您的access token

要在你的应用中显示 Mapbox 提供的地图需要将你的 access token添加到该应用程序的 Info.plist 文件中：

1.在Project navigator（左侧边栏中）找到Info.plist选项。 2.选中最开始的“Information Property List”一行，然后点击Editor ‣ Add Item。 3.将新插入行的 Key 设为MGLMapboxAccessToken，并设置访问令牌的 Value。

无论导入多少地图视图到你的应用程序，你只需要在该文件内设置一次访问令牌。访问令牌能确保只有你的程序可以使用你的 Mapbox 账户。

下载并安装Mapbox iOS SDK

创建好 Xcode 项目后，可以开始安装 Mapbox iOS SDK 了。下载最新版作为动态框架，解压下好的文件，将Mapbox.framework拖入项目的Embedded Binaries框中：

确保 Destination 一栏勾选了Copy items if needed。

添加完 Mapbox 框架后，你就可以使用 SDK 中的 所有类（class）和（方法）了。

保持更新

Mapbox iOS SDK 目前最新发布的版本是 v4.7.1.获取更新版本信息可访问 GitHub 发布页面（releases page）、浏览我们的博客、关注我们的 Twitter，或者查收订阅邮件。

注意，由于是手动操作，因此每次更新都需要下载新的 Mapbox iOS SDK 版本并重新拖入 Embedded Binaries。对于需要长时间使用和保存的项目，推荐使用 CocoaPods之类的软件包管理器进行安装。

使用storyboards添加地图

本指南将说明如何使用 Interface Builder storyboard来构建应用程序界面。（你也可以完全使用代码来创建界面。）在 view controller 中选择 view，然后在右侧边栏的 Identity inspector 栏中将类别改为MGLMapView.这一步会将底图（basic map）导入 view controller，然后就可以进行像定制地图样式、设置地图中心以及添加注释等操作了。

现在你已经成功添加了一个地图视图，那么我们来试试看。选择一个 iPhone 型号，然后点击 Build and Run（创建并运行）键。

Simulator（模拟器）会被启动，然后打开你刚刚新建的应用程序：

自定义地图

要改变初始坐标和缩放级别，在 Interface Builder 中选择 Map View，然后打开右侧边栏中的 Attributes inspector 标签。

将 Latitude 设为45.52245， Longitude 设为-122.67773，Zoom Level 设为14。

在 Simulator 中运行你的程序，可以看到中心位于美国俄勒冈州，波特兰市的一幅地图：

修改地图样式

这里的默认样式是 Mapbox Streets。如果你想显示卫星图像应该怎么办呢？可以在 Attributes inspector 中选择不同的 Mapbox style。

将 mapbox://styles/mapbox/satellite-streets-v9 输入Style URL框中。

在 Simulator 中重新运行程序可以看到新应用的Satellite Streets 地图样式：

创建自己的样式

你可以在Mapbox Studio中轻松创建 [由 Mapbox 托管的自定义样式]。在Mapbox GL JS支持的 iOS、安卓和网页应用程序中，Mapbox Studio 创建的地图样式效果很好。

使用Mapbox Studio Classic的样式和地图

尽管你可以 通过自定义样式载入栅格地图，但是用 Mapbox Studio Classic 创建的栅格地图与 Mapbox iOS SDK 不直接兼容。注意， Mapbox iOS SDK 不支持与栅格地图关联的标识、线条和图形。

使用代码添加annotation

通过这个 storyboard，可以为应用程序继续添加与 map view （地图视图）相适宜的控件和页面。接下来，我们来给地图视图添加更多的功能。为此我们需要添加相关代码。从 Interface Builder 切换到 View Controller’s code。在 Project navigator, 中点击 ViewController.m 或 ViewController.swift（取决于你选择的是 Objective-C 语言还是 Swift 语言）显示底层代码。

文件中已有部分代码。添加代码以获取地图视图，并添加注释（或者说marker 标识）。

Connect the map view to an outlet in Interface Builder

首先要用 Interface Builder 添加一个 outlet，以便从代码中获取地图视图。点击 Xcode 窗口右上角的 键切换到 Assistant Editor。在 storyboard canva 上选择 view controller 或是其下任何选项时，另一边的窗口都会显示出 view controller 的代码。

选中地图视图，在 storyboard canva 上点击并按住鼠标左键，拖至 view controller 代码栏。当 view controller 中出现一条蓝色横线时，表示插入有效，然后放开鼠标。我们可以将这个 outlet 命名为mapView。你也可以自己写这行代码，但是选择可视化操作岂不更好？

你会注意到，Xcode 将我们新插入的行标记了一个错误——这是因为我们还没有导入 Mapbox 框架。那么我们继续进行下一部分的操作！

在代码中导入Mapbox framework

Interface Builder 部分已经完成，可以开始着手写代码了。在 view controller 代码顶端导入 Mapbox 框架：

import UIKit
import Mapbox

设置地图视图的 delegate 属性

要配置不同的注释属性，view controller 必须遵守 MGLMapViewDelegate协议：

class ViewController: UIViewController, MGLMapViewDelegate {

然后设置地图视图的delegate属性：

override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
}

明确定义注释内容并将其添加到地图中

一切准备妥当之后，可以一行行地添加注释了。首先，在viewDidLoad方法的末尾创建一个 MGLPointAnnotation对象，并将其指定到局部变量point：

override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
 
let point = MGLPointAnnotation()
}

然后，给这个 point 注释写一个地理坐标：

override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
 
let point = MGLPointAnnotation()
point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
}

注释有title和subtitle属性，会以文本形式显示在视图中，后面就可以看到：

override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
 
let point = MGLPointAnnotation()
point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
point.title = "Voodoo Doughnut"
point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."
}

最后，将注释添加到地图视图中：

override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
 
let point = MGLPointAnnotation()
point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
point.title = "Voodoo Doughnut"
point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."
 
mapView.addAnnotation(point)
}

完整的代码如下所示：

import UIKit
import Mapbox
 
class ViewController: UIViewController, MGLMapViewDelegate {
 
@IBOutlet var mapView: MGLMapView!
 
override func viewDidLoad() {
super.viewDidLoad()
 
mapView.delegate = self
 
let point = MGLPointAnnotation()
point.coordinate = CLLocationCoordinate2D(latitude: 45.52258, longitude: -122.6732)
point.title = "Voodoo Doughnut"
point.subtitle = "22 SW 3rd Avenue Portland Oregon, U.S.A."
 
mapView.addAnnotation(point)
}
 
// Note: You can remove this method, which lets you customize low-memory behavior.
override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
// Dispose of any resources that can be recreated.
}
}

Tapping the annotation

如何让用户在点击注释的时候看到具体内容？需要启用注释的 callout。在viewDidLoad后添加以下方法：

func mapView(mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always try to show a callout when an annotation is tapped.
return true
}
 
// Or, if you’re using Swift 3 in Xcode 8.0, be sure to add an underscore before the method parameters:
func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: MGLAnnotation) -> Bool {
// Always try to show a callout when an annotation is tapped.
return true
}

重新运行代码以测试注释的交互性。

自定义点的annotation

可以通过运行 -mapView:viewForAnnotation:MGLMapViewDelegate(im)mapView:viewForAnnotation:) delegate 方法自定义注释视图。自定义视图注释非常多元化——可轻松做出动画效果，或是在整个地图上拖动注释。可查看 自定义注释视图示例以获取更多信息。

如果只需要小巧的静态图像作为注释，或是要一次性添加大量注释，可使用 -mapView:imageForAnnotation:MGLMapViewDelegate(im)mapView:imageForAnnotation:) 方法，参考 这个示例。

显示用户的位置

在使用应用程序时，用户通常都需要定位当前位置，接下来我们看看如何在地图上添加当前所在的位置。回到 Interface Builder 的 Attributes inspector, 找到 Shows User Location 并设置为 On。

启用位置服务

要在地图中添加用户的位置，需要获取许可，并就如何使用位置数据进行简要说明。

对于 iOS 8 系统及以上的用户，可在Info.plist 文件中设置 NSLocationAlwaysUsageDescription 或 NSLocationWhenInUseUsageDescriptionkey，Info.plist 文件也可以在项目编辑器的 Info 选项卡中找到。

我们建议将位置使用方式描述为：在地图上显示所在位置并帮助改进 OpenStreetMap。

更多关于 iOS 位置许可的信息，可参考 NSHipster 网站上比较全面的描述.

模拟位置

在 Simulator 中运行该应用程序时，你将会看到一个对话框，要求获得使用位置服务的权限：

要到 Simulator 菜单中依次点击 Debug ‣ Location ‣ Custom Location 才能在地图中看到当前位置。将纬度设为45.52258，经度设为-122.6732，这样，可以看到你正位于一个甜甜圈店外。

下一步

你刚刚用 Mapbox 创建了一个小的应用程序。现在你可以创建 Xcode 项目，使用 Storyboard 添加地图视图，更改地图样式，并在地图上添加注释和用户位置。是不是觉得自己很厉害了呀？

如果想要继续用 Mapbox 来开发你的应用程序，我们建议你阅读以下指南：

• Mapbox Telemetry — 让用户能够自主选择退出 Mapbox Telemetry
• Attribution — 在你的应用程序中使用我们的地图数据必须遵守许可条款

我们会同步更新操作指南，帮助您掌握 Mapbox 所有厉害的功能。下面的一些相关资源可以帮助你跟进 Mapbox 的更新动态：

• Mapbox iOS SDK documentation
• Mapbox GL Native on GitHub 可追踪 Mapbox Mobile 的开源项目