repository·main·Indexed 20 days ago
https://github.com/mapbox/mapbox-maps-iosA native library for rendering interactive, customizable maps using Metal, based on the Mapbox Style and Vector Tile specifications. Includes a SwiftUI interface via the MapboxMapsSwiftUI module (currently in development) and tools for API compatibility checking using breaking-api-check.py and swift-api-digester.
The MapboxMapsSwiftUI module provides a SwiftUI interface for the Mapbox Maps SDK, designed to simplify building Mapbox-powered applications using SwiftUI.
⚠️ Caution: This module is currently in development. Its API is not stable, and it is strongly recommended that it not be used in production.
StylePack is used to manage the loading and lifecycle of map styles. It allows you to load style information and assets required to render a map. You can use StylePackLoadOptions to configure the loading process and monitor progress through StylePackLoadProgress.When using the Mapbox Standard style, you can place custom layers into specific, stable locations called slots. This ensures your layers remain correctly positioned even as the basemap evolves.
Available slots:
bottom: Above polygons (land, water, etc.).middle: Above lines (roads) and behind 3D buildings.top: Above POI labels and behind Place/Transit labels.Note: For the Standard style, you can only add layers to these three specific slots (bottom, middle, top) within the basemap.
var layer = LineLayer(id: "line-layer", source: "line-source")
layer.slot = .middle
mapView.mapboxMap.addLayer(layer)The Viewport system controls what part of the map is visible and how the camera behaves relative to specific targets (like a 'puck' or a user location).
Core concepts:
ViewportManager: The central authority for managing viewport states.ViewportState: Represents a specific view configuration. Common states include:FollowPuckViewportState: Automatically follows a moving object (like a user's location).OverviewViewportState: Provides a high-level overview of a specific area.ViewportTransition: Defines how the map moves between different ViewportState configurations (e.g., DefaultViewportTransition or ImmediateViewportTransition).ViewportStatusObserver: Allows you to react to changes in the viewport's status or reason for change (ViewportStatusChangeReason).OrnamentsManager is the primary interface for controlling the visibility and configuration of map ornaments, such as the attribution button, logo, compass, and scale bar. You can use it to customize the appearance and positioning of these UI elements on the map.The Style API allows you to import other styles (like Mapbox Standard) into your main style by reference. This is done by adding an imports section to your Style JSON. Configuration properties for the imported style can then be adjusted at runtime via the StyleManager object.
Key StyleManager methods for managing imports:
styleImports: Returns all imported styles.removeStyleImport(for:): Removes a style import by ID.getStyleImportSchema(for:): Returns the schema for an imported style.getStyleImportConfigProperties(for:): Returns available configuration properties.getStyleImportConfigProperty(for:config:): Gets a specific property.setStyleImportConfigProperties(for:configs:): Sets multiple properties.setStyleImportConfigProperty(for:config:value:): Sets a single property."imports": [
{
"id": "A",
"url": "STYLE_URL_FOR_A",
"config": {
"font": "Montserrat",
"lightPreset": "dusk",
"showPointOfInterestLabels": true,
"showTransitLabels": false,
"showPlaceLabels": true,
"showRoadLabels": false
}
}
]Because Mapbox Map renders content in Metal, standard map features like symbols, lines, and polygons do not support the native visionOS hoverEffect (eye-tracking visual feedback).
To provide interactive elements that respond to user gaze, use View Annotations instead of standard point annotations. View annotations allow you to place SwiftUI views on the map that can utilize .hoverEffect().
Map {
// Standard point annotations handle gestures but lack eye-tracking feedback
PointAnnotation(coordinate: coordinate1)
.onTapGesture {
print("point annotation tapped")
}
// View annotations allow for visual eye-tracking feedback via SwiftUI modifiers
MapViewAnnotation(coordinate: coordinate2) {
Circle()
.fill(.blue)
.hoverEffect()
.onTapGesture {
print("view annotation tapped")
}
}
}Camera animations allow for smooth transitions between different camera states (position, zoom, bearing, pitch).
Key components include:
CameraAnimationsManager: Manages the lifecycle of camera animations.CameraAnimator: The interface for controlling animations.FlyToCameraAnimator: A specific animator used to 'fly' the camera to a new location.CameraTransition: Defines the movement from one state to another.TimingCurve: Controls the pacing of the animation (e.g., easing).AnimationCompletion: A callback mechanism to handle logic once an animation finishes.TileStore is the primary interface for managing tile data, including downloading, caching, and retrieving tiles. It works in conjunction with TileRegion to manage specific geographic areas and TilesetDescriptor to define which tilesets are being accessed. You can monitor progress using TileRegionLoadProgress and observe changes via TileStoreObserver.When customizing ornaments, you use several supporting types to define their behavior:
OrnamentOptions: A configuration object used to set properties for various ornaments.OrnamentPosition: Defines where an ornament is placed on the map (e.g., corners).OrnamentVisibility: Controls whether an ornament is visible or hidden.AttributionButtonOptions, CompassViewOptions, LogoViewOptions, and ScaleBarViewOptions: Specific configuration objects for individual ornament types.