Modèles d'intégration Mapbox iOS

Modèles officiels pour intégrer Mapbox Maps SDK v11 sur iOS avec Swift, SwiftUI et UIKit.

Utilisez cette compétence quand :

Installation et configuration de Mapbox Maps SDK pour iOS
Ajout de marqueurs et d'annotations aux cartes
Affichage de la localisation utilisateur et suivi avec la caméra
Ajout de données personnalisées (GeoJSON) aux cartes
Travail avec les styles de carte, la caméra ou l'interaction utilisateur
Gestion des interactions de feature et des appuis

Ressources officielles :

Installation et configuration

Configuration requise

iOS 12+
Xcode 15+
Swift 5.9+
Compte Mapbox gratuit

Étape 1 : Configurer le token d'accès

Ajoutez votre token public à Info.plist :

<key>MBXAccessToken</key>
<string>pk.your_mapbox_token_here</string>

Obtenez votre token : Connectez-vous à mapbox.com

Étape 2 : Ajouter la dépendance Swift Package

File → Add Package Dependencies
Entrez l'URL : https://github.com/mapbox/mapbox-maps-ios.git
Version : « Up to Next Major » à partir de 11.0.0
Vérifiez que quatre dépendances apparaissent : MapboxCommon, MapboxCoreMaps, MapboxMaps, Turf

Alternative : CocoaPods ou téléchargement direct (guide d'installation)

Initialisation de la carte

Modèle SwiftUI (iOS 13+)

Carte basique :

import SwiftUI
import MapboxMaps

struct ContentView: View {
    @State private var viewport: Viewport = .camera(
        center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        zoom: 12
    )

    var body: some View {
        Map(viewport: $viewport)
            .mapStyle(.standard)
    }
}

Avec ornements :

Map(viewport: $viewport)
    .mapStyle(.standard)
    .ornamentOptions(OrnamentOptions(
        scaleBar: .init(visibility: .visible),
        compass: .init(visibility: .adaptive),
        logo: .init(position: .bottomLeading)
    ))

Modèle UIKit

import UIKit
import MapboxMaps

class MapViewController: UIViewController {
    private var mapView: MapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let options = MapInitOptions(
            cameraOptions: CameraOptions(
                center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
                zoom: 12
            )
        )

        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        mapView.mapboxMap.loadStyle(.standard)
    }
}

Ajouter des marqueurs (annotations de points)

Les annotations de points sont le moyen le plus courant de marquer des emplacements sur la carte.

SwiftUI :

Map(viewport: $viewport) {
    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
        .iconImage("custom-marker")
}

UIKit :

// Créez un gestionnaire d'annotations (une fois, réutilisez pour les mises à jour)
var pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// Créez un marqueur
var annotation = PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
annotation.iconAnchor = .bottom

// Ajoutez à la carte
pointAnnotationManager.annotations = [annotation]

Plusieurs marqueurs :

let locations = [
    CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
    CLLocationCoordinate2D(latitude: 37.7849, longitude: -122.4094),
    CLLocationCoordinate2D(latitude: 37.7649, longitude: -122.4294)
]

let annotations = locations.map { coordinate in
    var annotation = PointAnnotation(coordinate: coordinate)
    annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
    return annotation
}

pointAnnotationManager.annotations = annotations

Afficher la localisation utilisateur

Étape 1 : Ajouter la permission de localisation à Info.plist :

<key>NSLocationWhenInUseUsageDescription</key>
<string>Show your location on the map</string>

Étape 2 : Demander les permissions et afficher la localisation :

import CoreLocation

// Demandez les permissions
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

// Affichez le puck de localisation utilisateur
mapView.location.options.puckType = .puck2D()
mapView.location.options.puckBearingEnabled = true

Bonnes pratiques de performance

Réutiliser les gestionnaires d'annotations

// ❌ Ne créez pas de nouveaux gestionnaires à répétition
func updateMarkers() {
    let manager = mapView.annotations.makePointAnnotationManager()
    manager.annotations = markers
}

// ✅ Créez une fois, réutilisez
let pointAnnotationManager: PointAnnotationManager

init() {
    pointAnnotationManager = mapView.annotations.makePointAnnotationManager()
}

func updateMarkers() {
    pointAnnotationManager.annotations = markers
}

Mises à jour d'annotations par lot

// ✅ Mettez à jour tout en même temps
pointAnnotationManager.annotations = newAnnotations

// ❌ Ne mettez pas à jour un par un
for annotation in newAnnotations {
    pointAnnotationManager.annotations.append(annotation)
}

Gestion de la mémoire

// Utilisez weak self dans les fermetures
mapView.gestures.onMapTap.observe { [weak self] context in
    self?.handleTap(context.coordinate)
}.store(in: &cancelables)

// Nettoyez à la destruction
deinit {
    cancelables.forEach { $0.cancel() }
}

Utiliser le style standard

// ✅ Le style standard est optimisé et recommandé
.mapStyle(.standard)

// Utilisez d'autres styles uniquement si nécessaire pour des cas d'usage spécifiques
.mapStyle(.standardSatellite) // Imagerie satellite

Dépannage

La carte ne s'affiche pas

Vérifiez :

✅ MBXAccessToken dans Info.plist
✅ Le token est valide (testez sur mapbox.com)
✅ Framework MapboxMaps importé
✅ MapView ajoutée à la hiérarchie de vues
✅ Frame/contraintes correctement définis

Le style ne se charge pas

mapView.mapboxMap.onStyleLoaded.observe { [weak self] _ in
    print("Style loaded successfully")
    // Ajoutez des couches et des sources ici
}.store(in: &cancelables)

Problèmes de performance

Utilisez le style .standard (recommandé et optimisé)
Limitez les annotations visibles à la zone visible
Réutilisez les gestionnaires d'annotations
Évitez les rechargements fréquents de style
Mettez à jour les annotations par lot

Fichiers de référence

Chargez ces références quand la tâche nécessite des modèles plus approfondis :

references/annotations.md — Annotations Cercle, Polyline, Polygone
references/location-tracking.md — Suivi de caméra utilisateur + Obtenir la localisation actuelle
references/custom-data.md — GeoJSON : Lignes, Polygones, Points, Mise à jour/Suppression
references/camera-styles.md — Contrôle de la caméra + Styles de carte
references/interactions.md — Interactions avec feature, Appuis sur couches personnalisées, Appui long, Gestes

mapbox-ios-patterns