MBXMapKit 已停止维护，为了使用 Mapbox 地图，建议您查看 Mapbox iOS SDK 2.0.0 及以上版本。Mapbox 地图的未来是矢量渲染，苹果目前没有迹象表明将在 MapKit 中允许自定义矢量渲染，因此我们建议您使用基于 OpenGL 的 Mapbox iOS SDK 2.0.0。

MBXMapKit 扩展了 Apple 的 MapKit，以便与托管在 Mapbox 上的地图集成，结合了本地地图的性能与与 Mapbox.js 类似的便利性和集成性。使用 MBXMapKit，您的应用程序负责提供和管理它自己的 MKMapView 实例，而 MBXMapKit 提供瓦片覆盖、注释和离线地图下载器，使您能够轻松地在在线和离线状态下显示 Mapbox 地图。

功能

MBXMapKit 添加到 MapKit 中的主要功能包括

• 在线地图：您可以使用 Mapbox 地图 ID 初始化一个光栅瓦片层，MBXMapKit 将处理生成瓦片 URL 和异步加载元数据和标记的细节。使用 MBXMapKit 的异步加载资源的代理回调，您可以选择立即开始渲染您的地图，然后当必要的数据变得可用时，调整可见区域并添加标记以匹配 Mapbox 在线编辑器中配置的地图。

• 离线地图：MBXMapKit 包含一个离线地图下载器，用于管理下载显示所需的所有资源（瓦片、JSON 元数据和标记图标），以便在离线状态下显示请求的地图区域。离线地图下载器提供下载进度更新、用于持久存储多个离线地图区域的内部机制、从磁盘中删除特定离线地图区域的能力，以及将离线地图数据包含在 iCloud 备份中的能力（默认情况下，保留从备份中排除离线地图数据）。

• Mapbox 标记：如果您已经在 Mapbox 在线编辑器 中配置了标记，MBXMapKit 可使您将它们轻松地添加到 MKMapView 上作为 MKShape 注释。您需要在视图控制器的 -[MKMapViewDelegate mapView:viewForAnnotation:] 中包含一些简单的样板代码，以将注释与常规 MKAnnotationView 实例连接（请参阅 iOS 示例应用）。

• 性能缓存：MBXMapKit 使用 NSURLSession 和 NSURLCache 来对必要的瓦片、JSON 元数据和图标进行性能缓存，以加载地图。与 Mapbox iOS SDK 及 MBXMapKit 早期版本相比，这是一个传统的缓存，并非设计用于离线时长期持久存储地图数据。该功能由一个独立的机制提供。

概念

了解 MBXMapKit 的基本概念是，它旨在向苹果的 MapKit 添加功能，而不是取代或封装 MapKit。

您负责管理自己的 MKMapView，MBXMapKit 会保持其原有的地方。MBXMapKit 提供了 MKTileOverlay 和 MKShape 子类，您可以将其添加到您的 MKMapView 中，结合来自其他来源的覆盖和注释。要了解 MBXMapKit 如何使此过程变得相对容易，以及如何配置 MKMapView 以满足不同的视觉目标，请查看 iOS 示例应用中的 视图控制器。

使用 MBXMapKit，性能缓存与持久离线存储之间存在明确的区别。如果 iOS 决定需要通过删除应用缓存目录中的项目来释放磁盘空间，离线地图数据将不受影响。

要求

• iOS 7.0+
• Xcode 5+
• 自动引用计数（ARC）

版本

总的来说，MBXMapKit 遵循 GitHub 的 发布您的软件 文章中描述的约定。

通常我们作为分支开发新功能，然后在准备发布时将它们合并到 master 分支。当官方发布版准备好时，我们将创建带有版本号的标签。您可以在 https://github.com/mapbox/mbxmapkit/releases 上查看版本列表。

安装

要将 MBXMapKit 包含到您的应用中，您需要

1. 将 MBXMapKit 文件夹中所有的 .m 和 .h 文件复制到您的项目中。

2. 确保 .m 文件包含在您的构建目标中（选择项目，选择构建目标，选择 构建阶段 标签，展开 编译源 部分，确保所有 .m 文件都已列出）。

3. 确保您的构建目标启用了地图功能（选择项目，选择构建目标，选择 功能 标签，将开关切换到 开 以启用地图）。

4. 确保您的构建目标链接了 libsqlite3.dylib（选择项目，选择构建目标，选择 构建阶段 标签，展开 链接二进制与库 部分，检查列表）。当您启用地图功能时，MapKit 框架应自动添加，但除非您已经在使用 SQLite 进行其他操作，否则您可能还需要添加 libsqlite3.dylib。

5. 研究 iOS 示例应用中的视图控制器。其目的是要广泛复制粘贴。特别是，查看 -viewDidLoad、-resetMapViewAndRasterOverlayDefaults、-actionSheet:clickedButtonAtIndex:、MBXOfflineMapDownloaderDelegate 回调、-mapView:rendererForOverlay:、-mapView:viewForAnnotation: 以及 MBXRasterTileOverlayDelegate 回调，如果您对如何实现有任何疑问。

6. 提供一些明显的手段来显示任何适用的地图数据版权归属消息。 对于包含 OpenStreetMap 数据的地图，这意味着你需要某种链接到 OSM 版权页面（请参考示例应用中的示例）。更多详细信息请查看 https://www.mapbox.com/help/attribution/ 和 http://www.openstreetmap.org/copyright。

支持

如果你对如何使用 MBXMapKit 有疑问，或者遇到了问题，这里提供了我们的一些建议。

1. 阅读整个 README，检查 MBXMapKit 头文件中的文档，并看看你想要做的事是否与示例应用中的任何内容相似。

2. 在网上搜索你遇到的问题或错误消息。这可以帮助你区分 MBXMapKit 专用问题与 MKMapKit 更普遍的问题，并可能带你到相关 GitHub 问题和 StackOverflow 问题。在很多情况下，有关使用 MKMapKit 的文档和博客文章也适用于 MBXMapKit。

3. 熟悉 Mapbox.com 上的文档和开发者资源（帮助、指南和 开发者）。

4. 查看 GitHub 上的 MBXMapKit 问题。

5. 查看 StackOverflow 上的 Mapbox 问题。

6. 如果上述所有方法都不能解决问题，你可以在 GitHub 上提交 问题，在 StackOverflow 上提问，或者 联系 Mapbox 支持部门。

示例应用

示例应用旨在展示 MBXMapKit 的全部功能，并展示配置 MKMapView 的不同方法。我们还发现它在测试 API 实施过程中的响应性和视觉跳变非常有用。

快速浏览

1. 启动示例应用。

2. 点击右下角的信息按钮，将显示一个包含多个地图配置和查看归属对话框选项的动作表。

3. 尝试不同的地图配置，然后查阅 MBXViewController.m 中的《-resetMapViewAndRasterOverlayDefaults》和《-actionSheet:clickedButtonAtIndex:，以理解发生了什么。基本思路是：当地图配置切换时，通过移除覆盖和标记将 MKMapView 恢复到一个已知状态，然后为新配置添加新的覆盖和标记。

4. 注意，世界基础层，无 Apple 地图 包括位于加利福尼亚州圣克鲁兹的多个橙色游泳标记。呼出文本来自地图的 features.json 文件，该文件由 Mapbox API 加载，图标也从 Mapbox API 加载，这些图标在从 features.json 中解析所需的规格之后。地图中心坐标和缩放比例来自地图的元数据 JSON（即，your-map-id.json）。通过视图控制器的 MBXRasterTileOverlayDelegate 回调实现将标记、居中和缩放应用于地图。

5. 注意，离线地图下载器 在屏幕中央提供了一个视图，包含控制开始、取消、暂停和恢复下载离线地图区域的控件。要选择要下载的区域，只需在点击开始按钮之前调整可见地图区域即可。下载活动时，你应该在屏幕底部看到进度指示器。如果你切换到其他地图，进度指示器将保持在屏幕上。如果你在下载完成之前关闭应用程序，重启应用程序时应恢复。

6. 请注意，在切换到离线地图查看器时，离线地图查看器将显示您最近完全下载的离线地图区域。注意，即使启用了飞行模式，离线地图也包含标记、初始居中和初始缩放。还有一个按钮，用于确认删除所有存储的地图。虽然示例应用程序只显示最近下载的离线地图，但API设计是为了您可以列出所有可用的离线地图并使用您想要的任何地图。

平台

MBXMapKit官方支持iOS 7.0及以上版本。虽然iOS是主要关注点，但我们还想保持对OS X的友好（需要MapKit，因此从10.9及以上版本），这意味着您可能会注意到在UIImage/NSImage等位置存在的#if TARGET_OS_IPHONE实例，并且可能这些功能中的部分OS X端可能存在问题。

如果您遇到与OS X相关的问题，并希望向GitHub提交问题或拉取请求，这将受到欢迎并被感激。特别是，如果您正在开发一个需要Mapbox.js之外的内容（例如离线地图）的OS X应用程序，我们非常希望了解相关信息。

相关内容

查看概述指南，获取详细信息的概述。

您还可能对Mapbox iOS SDK感兴趣，它是从头开始重写的代码，旨在替代而非扩展Apple的MapKit。如果您总是希望MapKit是开源的以便完全自定义，Mapbox iOS SDK是您的好选择。