MapboxStatic

MapboxStatic.swift 让您轻松地将您的 iOS、macOS、tvOS 或 watchOS 应用程序连接到 Mapbox Static Images API 或 Legacy Static Images API。通过同步或异步地使用 Swift 或 Objective-C 数据类型在网络上获取，可以快速生成地图快照 – 一个带有覆盖层的静态地图图像。使用单个 HTTP 请求创建静态地图。覆盖层在服务器端添加。

快照是一个平坦的 PNG 或 JPEG 图像，非常适合在表格或图像视图中使用，用户通知，分享服务，打印文档，或者在您想要快速、自定义地图而不带交互视图开销的任何地方使用。静态地图通过单个 HTTP 请求创建。覆盖层在服务器端添加。

MapboxStatic.swift 与 MapboxDirections.swift，MapboxGeocoder.swift，Mapbox Maps SDK for iOS 以及 Mapbox Maps SDK for macOS SDK 相得益彰。如果您已经在 iOS 或 macOS 上使用地图 SDK 进行其他用途，请考虑使用 MGLMapSnapshotter 对象而不是 MapboxStatic.swift 来生成利用缓存和离线包的静态图像。

系统要求

以下包管理器之一
- CocoaPods（如果在 Xcode 12 上使用，则需要 CocoaPods 1.10 或更高版本）
- Carthage 0.19 或更高版本（如果使用 Xcode 12，请使用此脚本而不是 carthage）
- Swift Package Manager 5.3 或更高版本
使用 Xcode 11 或更高版本（如果使用 Swift Package Manager 则为 Xcode 12 或更高版本）
以下操作系统之一
- iOS 10.0 或更高版本
- macOS 10.12.0 或更高版本
- tvOS 10.0 或更高版本
- watchOS 3.0 或更高版本

安装

Carthage

在您的 Carthage Cartfile 中指定以下依赖项

github "mapbox/MapboxStatic.swift" ~> 0.12

CocoaPods

在您的 CocoaPods Podfile 中

pod 'MapboxStatic.swift', '~> 0.12'

Swift Package Manager

要使用 Swift Package Manager 安装 MapboxStatic，将以下软件包添加到您的 Package.swift 文件中的 dependencies

.package(url: "https://github.com/mapbox/MapboxStatic.swift.git", from: "0.12.0"),

然后 import MapboxStatic 或 @import MapboxStatic;.

此仓库包含用 Swift 编写的 iOS 应用程序示例，以及 iOS 和 macOS 的 Swift playgrounds。要运行它们，您需要使用 Carthage 0.19 或更高版本来安装依赖项。在 MapboxStatic.xcworkspace 中打开 playgrounds。更多示例请见 Mapbox API 文档.

使用

您可以从Mapbox托管样式或原始的瓦片集生成快照。使用样式可以提供更多视觉选项，如旋转，而使用瓦片集可以提供多种图像格式选择。如果您正在处理矢量数据，请使用样式；如果您正在处理单一的栅格图像源，您可能想使用瓦片集。

要从样式生成快照，您需要其样式URL。您可以选择Mapbox设计样式或在自己的Mapbox Studio中设计样式。您可以使用同一样式在iOS或MacOS的Mapbox Maps SDK中。

要从瓦片集生成快照，您需要一个地图ID。您可以选择Mapbox维护的瓦片集或将其上传到Mapbox Studio。

为了使用此库，您需要一个带有启用styles:tiles范围的访问令牌。您可以在行内指定访问令牌或通过设置应用程序的Info.plist文件中的MGLMapboxAccessToken键来设置。

以下示例分别以Swift（标记为main.swift）和Objective-C（标记为main.m）形式提供。有关更多详情，请参阅MapboxStatic.swift API引用。

基础

主静态地图类在Swift中为Snapshot，在Objective-C中为MBSnapshot。要创建基本的快照，创建一个SnapshotOptions对象，指定快照相机（视图点）和点大小

// main.swift
import MapboxStatic

let camera = SnapshotCamera(
    lookingAtCenter: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    zoomLevel: 12)
let options = SnapshotOptions(
    styleURL: URL(string: "<#your mapbox: style URL#>")!,
    camera: camera,
    size: CGSize(width: 200, height: 200))
let snapshot = Snapshot(
    options: options,
    accessToken: "<#your access token#>")

// main.m
@import MapboxStatic;

NSURL *styleURL = [NSURL URLWithString:@"<#your mapbox: style URL#>"];
MBSnapshotCamera *camera = [MBSnapshotCamera cameraLookingAtCenterCoordinate:CLLocationCoordinate2DMake(45.52, -122.681944)
                                                                   zoomLevel:12];
MBSnapshotOptions *options = [[MBSnapshotOptions alloc] initWithStyleURL:styleURL
                                                                  camera:camera
                                                                    size:CGSizeMake(200, 200)];
MBSnapshot *snapshot = [[MBSnapshot alloc] initWithOptions:options
                                               accessToken:@"<#your access token#>"];

然后，您可以同步检索图像（阻塞调用线程）

// main.swift
imageView.image = snapshot.image

// main.m
imageView.image = snapshot.image;

或者，您可以在获取图像后传递一个完成处理程序来更新UI线程

// main.swift
snapshot.image { (image, error) in
    imageView.image = image
}

// main.m
[snapshot imageWithCompletionHandler:^(UIImage * _Nullable image, NSError * _Nullable error) {
    imageView.image = image;
}];

如果您使用自己的HTTP库或例程，也可以检索快照的URL属性。

// main.swift
let imageURL = snapshot.url

// main.m
NSURL *imageURL = snapshot.url;

要创建基本的经典快照，创建一个ClassicSnapshotOptions或MBClassicSnapshotOptions对象，指定中心坐标、缩略级别和点大小

// main.swift
let options = ClassicSnapshotOptions(
    mapIdentifiers: ["<#your map ID#>"],
    centerCoordinate: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    zoomLevel: 13,
    size: CGSize(width: 300, height: 200))
let snapshot = Snapshot(
    options: options,
    accessToken: "<#your access token#>")
imageView.image = snapshot.image

// main.m
MBSnapshotOptions *options = [[MBClassicSnapshotOptions alloc] initWithMapIdentifiers:@[@"<#your map ID#>"]
                                                                     centerCoordinate:CLLocationCoordinate2DMake(45.52, -122.681944)
                                                                            zoomLevel:13
                                                                                 size:CGSizeMake(200, 200)];
MBSnapshot *snapshot = [[MBSnapshot alloc] initWithOptions:options accessToken:@"<#your access token#>"];
imageView.image = snapshot.image;

叠加层

叠加层是事物变得有趣的地方！您可以添加Maki标记、自定义标记图像、GeoJSON几何形状，甚至用纯坐标构成的路径。

您可以将叠加层添加到SnapshotOptions或MBSnapshotOptions对象中的overlays字段。以下是添加了各种叠加层后我们的快照的一些版本。

标记器

// main.swift
let markerOverlay = Marker(
    coordinate: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    size: .medium,
    iconName: "cafe"
)
markerOverlay.color = .brown

// main.m
MBMarker *markerOverlay = [[MBMarker alloc] initWithCoordinate:CLLocationCoordinate2DMake(45.52, -122.681944)
                                                          size:MBMarkerSizeMedium
                                                      iconName:@"cafe"];
#if TARGET_OS_IOS || TARGET_OS_TV || TARGET_OS_WATCH
    markerOverlay.color = [UIColor brownColor];
#elif TARGET_OS_MAC
    markerOverlay.color = [NSColor brownColor];
#endif

自定义标记器

// main.swift
let customMarker = CustomMarker(
    coordinate: CLLocationCoordinate2D(latitude: 45.522, longitude: -122.69),
    url: URL(string: "https://www.mapbox.com/help/img/screenshots/rocket.png")!
)

// main.m
NSURL *url = [NSURL URLWithString:@"https://www.mapbox.com/help/img/screenshots/rocket.png"];
MBCustomMarker *customMarker = [[MBCustomMarker alloc] initWithCoordinate:CLLocationCoordinate2DMake(45.522, -122.69)
                                                                      url:url];

GeoJSON

// main.swift
let geoJSONOverlay: GeoJSON

do {
    let geoJSONURL = URL(string: "http://git.io/vCv9U")!
    let geoJSONString = try String(contentsOf: geoJSONURL, encoding: .utf8)
    geoJSONOverlay = GeoJSON(objectString: geoJSONString)
}

// main.m
NSURL *geoJSONURL = [NSURL URLWithString:@"http://git.io/vCv9U"];
NSString *geoJSONString = [[NSString alloc] initWithContentsOfURL:geoJSONURL
                                                         encoding:NSUTF8StringEncoding
                                                            error:NULL];
MBGeoJSON *geoJSONOverlay = [[MBGeoJSON alloc] initWithObjectString:geoJSONString];

路径

// main.swift
let path = Path(
    coordinates: [
        CLLocationCoordinate2D(
            latitude: 45.52475063103141, longitude: -122.68209457397461
        ),
        CLLocationCoordinate2D(
            latitude: 45.52451009822193, longitude: -122.67488479614258
        ),
        CLLocationCoordinate2D(
            latitude: 45.51681250530043, longitude: -122.67608642578126
        ),
        CLLocationCoordinate2D(
            latitude: 45.51693278828882, longitude: -122.68999099731445
        ),
        CLLocationCoordinate2D(
            latitude: 45.520300607576864, longitude: -122.68964767456055
        ),
        CLLocationCoordinate2D(
            latitude: 45.52475063103141, longitude: -122.68209457397461
        )
    ]
)
path.strokeWidth = 2
path.strokeColor = .black
#if os(macOS)
    path.fillColor = NSColor.red.withAlphaComponent(0.25)
#else
    path.fillColor = UIColor.red.withAlphaComponent(0.25)
#endif

// main.m
CLLocationCoordinate2D coordinates[] = {
    CLLocationCoordinate2DMake(45.52475063103141, -122.68209457397461),
    CLLocationCoordinate2DMake(45.52451009822193, -122.67488479614258),
    CLLocationCoordinate2DMake(45.51681250530043, -122.67608642578126),
    CLLocationCoordinate2DMake(45.51693278828882, -122.68999099731445),
    CLLocationCoordinate2DMake(45.520300607576864, -122.68964767456055),
    CLLocationCoordinate2DMake(45.52475063103141, -122.68209457397461),
};
MBPath *path = [[MBPath alloc] initWithCoordinates:coordinates
                                             count:sizeof(coordinates) / sizeof(coordinates[0])];
path.strokeWidth = 2;
#if TARGET_OS_IOS || TARGET_OS_TV || TARGET_OS_WATCH
    path.strokeColor = [UIColor blackColor];
    path.fillColor = [[UIColor redColor] colorWithAlphaComponent:0.25];
#elif TARGET_OS_MAC
    path.strokeColor = [NSColor blackColor];
    path.fillColor = [[NSColor redColor] colorWithAlphaComponent:0.25];
#endif

其他选项

旋转和倾斜

要旋转和倾斜快照，设置其相机的朝向和俯仰角

// main.swift
let camera = SnapshotCamera(
    lookingAtCenter: CLLocationCoordinate2D(latitude: 45.52, longitude: -122.681944),
    zoomLevel: 13)
camera.heading = 45
camera.pitch = 60
let options = SnapshotOptions(
    styleURL: URL(string: "<#your mapbox: style URL#>")!,
    camera: camera,
    size: CGSize(width: 200, height: 200))
let snapshot = Snapshot(
    options: options,
    accessToken: "<#your access token#>")

// main.m
NSURL *styleURL = [NSURL URLWithString:@"<#your mapbox: style URL#>"];
MBSnapshotCamera *camera = [MBSnapshotCamera cameraLookingAtCenterCoordinate:CLLocationCoordinate2DMake(45.52, -122.681944)
                                                                   zoomLevel:13];
camera.heading = 45;
camera.pitch = 60;
MBSnapshotOptions *options = [[MBSnapshotOptions alloc] initWithStyleURL:styleURL
                                                                  camera:camera
                                                                    size:CGSizeMake(200, 200)];
MBSnapshot *snapshot = [[MBSnapshot alloc] initWithOptions:options
                                               accessToken:@"<#your access token#>"];

自动调整功能

如果你正在给快照添加叠加层，省略中心坐标和缩放级别以自动计算最佳的显示效果。

// main.swift

let options = SnapshotOptions(
    styleURL: URL(string: "<#your mapbox: style URL#>")!,
    size: CGSize(width: 500, height: 300))
options.overlays = [path, geojsonOverlay, markerOverlay, customMarker]

// main.m
NSURL *styleURL = [NSURL URLWithString:@"<#your mapbox: style URL#>"];
MBSnapshotOptions *options = [[MBClassicSnapshotOptions alloc] initWithStyleURL:styleURL
                                                                           size:CGSizeMake(500, 300)];
options.overlays = @[path, geojsonOverlay, markerOverlay, customMarker];

独立标记

使用MarkerOptions类来获取独立标记图像，这在您尝试自行将图像叠加到地图上时非常有用。

// main.swift
let options = MarkerOptions(
    size: .medium,
    iconName: "cafe")
options.color = .brown
let snapshot = Snapshot(
    options: options,
    accessToken: "<#your access token#>")

// main.m
MBMarkerOptions *options = [[MBMarkerOptions alloc] initWithSize:MBMarkerSizeMedium
                                                        iconName:@"cafe"];
#if TARGET_OS_IOS || TARGET_OS_TV || TARGET_OS_WATCH
    options.color = [UIColor brownColor];
#elif TARGET_OS_MAC
    options.color = [NSColor brownColor];
#endif
MBSnapshot *snapshot = [[MBSnapshot alloc] initWithOptions:options
                                               accessToken:@"<#your access token#>"];

文件格式和质量

在创建经典快照时，您还可以指定PNG或JPEG图像格式以及各种节省带宽的图像质量。

归属

请确保在您的应用中正确地归属您的地图。您还可以了解更多关于Mapbox地图数据来源的信息。

测试

要运行包含的单元测试，您需要使用0.19或更高版本的Carthage来安装依赖项。

carthage bootstrap
打开MapboxStatic.xcodeproj
转到产品 ‣ 测试。

MapboxStatic.swift 0.12.0

MapboxStatic.swift 0.12.0

MapboxStatic.swift 0.12.0

MapboxStatic

系统要求

安装

Carthage

CocoaPods

Swift Package Manager

使用

基础

叠加层

标记器

自定义标记器

GeoJSON

路径

其他选项

旋转和倾斜

自动调整功能

独立标记

文件格式和质量

归属

测试