Mapbox Android Patterns

作者 mapboxaab3a6fef5c6无许可证80 个星标收录于 2026年10月8日更新于 2026年10月8日仓库7天前更新

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and featureset interactions. Based on official Mapbox documentation.

仅含说明Software Development

AI 生成的概览

在 Android 应用中集成 Mapbox Maps SDK v11 的参考模式，涵盖 Kotlin、Jetpack Compose 与 View 体系。

功能: 提供 Mapbox Maps SDK v11 在 Android 上的集成指导与代码模式，涵盖安装、访问令牌与清单配置、地图初始化、标记与注记、用户位置显示、自定义 GeoJSON 数据、样式、相机控制以及要素交互。还包含性能实践与故障排查步骤。参考文件提供 Compose、注记、位置跟踪、自定义数据、相机与样式、交互等更详细的模式。
适用场景: 适用于开发或维护内嵌 Mapbox 地图的 Android 应用，并需要具体配置或使用模式时。也适合添加标记、显示用户位置、加载自定义数据或处理地图点击与手势。
运行要求: Android SDK 21+、Kotlin 或 Java、Android Studio，以及带访问令牌的 Mapbox 账户。应用需要 Mapbox Maven 仓库、com.mapbox.maps:android 依赖（Compose 还需 maps-compose）以及 INTERNET 权限；定位功能还需位置权限。仅为说明文档，不含脚本。

Mapbox Android Integration Patterns

Official patterns for integrating Mapbox Maps SDK v11 on Android with Kotlin, Jetpack Compose, and View system.

Use this skill when:

Installing and configuring Mapbox Maps SDK for Android
Adding markers and annotations to maps
Showing user location and tracking with camera
Adding custom data (GeoJSON) to maps
Working with map styles, camera, or user interaction
Handling feature interactions and taps

Official Resources:

Installation & Setup

Requirements

Android SDK 21+
Kotlin or Java
Android Studio
Free Mapbox account

Step 1: Configure Access Token

Create app/res/values/mapbox_access_token.xml:

xml

<?xml version="1.0" encoding="utf-8"?><resources xmlns:tools="http://schemas.android.com/tools">    <string name="mapbox_access_token" translatable="false"        tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string></resources>

<?xml version="1.0" encoding="utf-8"?><resources xmlns:tools="http://schemas.android.com/tools">    <string name="mapbox_access_token" translatable="false"        tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string></resources>

Get your token: Sign in at mapbox.com

Step 1b: Internet permission (required)

Maps need network access. Include this in AndroidManifest.xml — agents often omit it and only list location permissions later:

Step 2: Add Maven Repository

In settings.gradle.kts:

kotlin

dependencyResolutionManagement {    repositories {        google()        mavenCentral()        maven {            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")        }    }}

dependencyResolutionManagement {    repositories {        google()        mavenCentral()        maven {            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")        }    }}

Step 3: Add Dependency

In module build.gradle.kts:

kotlin

android {    defaultConfig {        minSdk = 21    }}
dependencies {    implementation("com.mapbox.maps:android:11.18.1")}

android {    defaultConfig {        minSdk = 21    }}
dependencies {    implementation("com.mapbox.maps:android:11.18.1")}

For Jetpack Compose:

kotlin

dependencies {    implementation("com.mapbox.maps:android:11.18.1")    implementation("com.mapbox.extension:maps-compose:11.18.1")}

dependencies {    implementation("com.mapbox.maps:android:11.18.1")    implementation("com.mapbox.extension:maps-compose:11.18.1")}

Map Initialization

Jetpack Compose Pattern

Basic map:

kotlin

import androidx.compose.runtime.*import androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.ui.Modifierimport com.mapbox.maps.extension.compose.*import com.mapbox.maps.Styleimport com.mapbox.geojson.Point
@Composablefun MapScreen() {    MapboxMap(        modifier = Modifier.fillMaxSize()    ) {        // Initialize camera via MapEffect (Style.STANDARD loads by default)        MapEffect(Unit) { mapView ->            // Set initial camera position            mapView.mapboxMap.setCamera(                CameraOptions.Builder()                    .center(Point.fromLngLat(-122.4194, 37.7749))                    .zoom(12.0)                    .build()            )        }    }}

import androidx.compose.runtime.*import androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.ui.Modifierimport com.mapbox.maps.extension.compose.*import com.mapbox.maps.Styleimport com.mapbox.geojson.Point
@Composablefun MapScreen() {    MapboxMap(        modifier = Modifier.fillMaxSize()    ) {        // Initialize camera via MapEffect (Style.STANDARD loads by default)        MapEffect(Unit) { mapView ->            // Set initial camera position            mapView.mapboxMap.setCamera(                CameraOptions.Builder()                    .center(Point.fromLngLat(-122.4194, 37.7749))                    .zoom(12.0)                    .build()            )        }    }}

With ornaments:

kotlin

MapboxMap(    modifier = Modifier.fillMaxSize(),    scaleBar = {        ScaleBar(            enabled = true,            position = Alignment.BottomStart        )    },    compass = {        Compass(enabled = true)    }) {    // Style.STANDARD loads by default}

MapboxMap(    modifier = Modifier.fillMaxSize(),    scaleBar = {        ScaleBar(            enabled = true,            position = Alignment.BottomStart        )    },    compass = {        Compass(enabled = true)    }) {    // Style.STANDARD loads by default}

View System Pattern

Layout XML (activity_map.xml):

xml

<?xml version="1.0" encoding="utf-8"?><androidx.constraintlayout.widget.ConstraintLayout    xmlns:android="http://schemas.android.com/apk/res/android"    android:layout_width="match_parent"    android:layout_height="match_parent">
    <com.mapbox.maps.MapView        android:id="@+id/mapView"        android:layout_width="match_parent"        android:layout_height="match_parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

<?xml version="1.0" encoding="utf-8"?><androidx.constraintlayout.widget.ConstraintLayout    xmlns:android="http://schemas.android.com/apk/res/android"    android:layout_width="match_parent"    android:layout_height="match_parent">
    <com.mapbox.maps.MapView        android:id="@+id/mapView"        android:layout_width="match_parent"        android:layout_height="match_parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

Activity:

kotlin

import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport com.mapbox.maps.MapViewimport com.mapbox.maps.Styleimport com.mapbox.geojson.Point
class MapActivity : AppCompatActivity() {    private lateinit var mapView: MapView
    override fun onCreate(savedInstanceState: Bundle?) {        super.onCreate(savedInstanceState)        setContentView(R.layout.activity_map)
        mapView = findViewById(R.id.mapView)
        mapView.mapboxMap.setCamera(            CameraOptions.Builder()                .center(Point.fromLngLat(-122.4194, 37.7749))                .zoom(12.0)                .build()        )
        mapView.mapboxMap.loadStyle(Style.STANDARD)    }
    override fun onStart() {        super.onStart()        mapView.onStart()    }
    override fun onStop() {        super.onStop()        mapView.onStop()    }
    override fun onDestroy() {        super.onDestroy()        mapView.onDestroy()    }}

import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport com.mapbox.maps.MapViewimport com.mapbox.maps.Styleimport com.mapbox.geojson.Point
class MapActivity : AppCompatActivity() {    private lateinit var mapView: MapView
    override fun onCreate(savedInstanceState: Bundle?) {        super.onCreate(savedInstanceState)        setContentView(R.layout.activity_map)
        mapView = findViewById(R.id.mapView)
        mapView.mapboxMap.setCamera(            CameraOptions.Builder()                .center(Point.fromLngLat(-122.4194, 37.7749))                .zoom(12.0)                .build()        )
        mapView.mapboxMap.loadStyle(Style.STANDARD)    }
    override fun onStart() {        super.onStart()        mapView.onStart()    }
    override fun onStop() {        super.onStop()        mapView.onStop()    }
    override fun onDestroy() {        super.onDestroy()        mapView.onDestroy()    }}

Add Markers (Point Annotations)

Point annotations are the most common way to mark locations on the map.

Jetpack Compose:

kotlin

MapboxMap(modifier = Modifier.fillMaxSize()) {    MapEffect(Unit) { mapView ->        // Load style first        mapView.mapboxMap.loadStyle(Style.STANDARD)
        // Create annotation manager and add markers        val annotationManager = mapView.annotations.createPointAnnotationManager()        val pointAnnotation = PointAnnotationOptions()            .withPoint(Point.fromLngLat(-122.4194, 37.7749))            .withIconImage("custom-marker")        annotationManager.create(pointAnnotation)    }}
// Note: Compose doesn't have declarative PointAnnotation component// Markers must be added imperatively via MapEffect

MapboxMap(modifier = Modifier.fillMaxSize()) {    MapEffect(Unit) { mapView ->        // Load style first        mapView.mapboxMap.loadStyle(Style.STANDARD)
        // Create annotation manager and add markers        val annotationManager = mapView.annotations.createPointAnnotationManager()        val pointAnnotation = PointAnnotationOptions()            .withPoint(Point.fromLngLat(-122.4194, 37.7749))            .withIconImage("custom-marker")        annotationManager.create(pointAnnotation)    }}
// Note: Compose doesn't have declarative PointAnnotation component// Markers must be added imperatively via MapEffect

View System:

kotlin

// Create annotation manager (once, reuse for updates)val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
// Create markerval pointAnnotation = PointAnnotationOptions()    .withPoint(Point.fromLngLat(-122.4194, 37.7749))    .withIconImage("custom-marker")
pointAnnotationManager.create(pointAnnotation)

// Create annotation manager (once, reuse for updates)val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
// Create markerval pointAnnotation = PointAnnotationOptions()    .withPoint(Point.fromLngLat(-122.4194, 37.7749))    .withIconImage("custom-marker")
pointAnnotationManager.create(pointAnnotation)

Multiple markers:

kotlin

val locations = listOf(    Point.fromLngLat(-122.4194, 37.7749),    Point.fromLngLat(-122.4094, 37.7849),    Point.fromLngLat(-122.4294, 37.7649))
val annotations = locations.map { point ->    PointAnnotationOptions()        .withPoint(point)        .withIconImage("marker")}
pointAnnotationManager.create(annotations)

val locations = listOf(    Point.fromLngLat(-122.4194, 37.7749),    Point.fromLngLat(-122.4094, 37.7849),    Point.fromLngLat(-122.4294, 37.7649))
val annotations = locations.map { point ->    PointAnnotationOptions()        .withPoint(point)        .withIconImage("marker")}
pointAnnotationManager.create(annotations)

Show User Location (Display)

Step 1: Add permissions to AndroidManifest.xml:

xml

<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Step 2: Request permissions and show location:

kotlin

// Request permissions first (use ActivityResultContracts)
// Show location puckmapView.location.updateSettings {    enabled = true    puckBearingEnabled = true}

// Request permissions first (use ActivityResultContracts)
// Show location puckmapView.location.updateSettings {    enabled = true    puckBearingEnabled = true}

Performance Best Practices

Reuse Annotation Managers

kotlin

// Don't create new managers repeatedly// val manager = mapView.annotations.createPointAnnotationManager() // each call
// Create once, reuseval pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
fun updateMarkers() {    pointAnnotationManager.deleteAll()    pointAnnotationManager.create(markers)}

// Don't create new managers repeatedly// val manager = mapView.annotations.createPointAnnotationManager() // each call
// Create once, reuseval pointAnnotationManager = mapView.annotations.createPointAnnotationManager()
fun updateMarkers() {    pointAnnotationManager.deleteAll()    pointAnnotationManager.create(markers)}

Batch Annotation Updates

kotlin

// Create all at oncepointAnnotationManager.create(allAnnotations)
// Don't create one by one in a loop

// Create all at oncepointAnnotationManager.create(allAnnotations)
// Don't create one by one in a loop

Lifecycle Management

kotlin

// Always call lifecycle methodsoverride fun onStart() {    super.onStart()    mapView.onStart()}
override fun onStop() {    super.onStop()    mapView.onStop()}
override fun onDestroy() {    super.onDestroy()    mapView.onDestroy()}

// Always call lifecycle methodsoverride fun onStart() {    super.onStart()    mapView.onStart()}
override fun onStop() {    super.onStop()    mapView.onStop()}
override fun onDestroy() {    super.onDestroy()    mapView.onDestroy()}

Use Standard Style

kotlin

// Standard style is optimized and recommendedStyle.STANDARD
// Use other styles only when needed for specific use casesStyle.STANDARD_SATELLITE // Satellite imagery

// Standard style is optimized and recommendedStyle.STANDARD
// Use other styles only when needed for specific use casesStyle.STANDARD_SATELLITE // Satellite imagery

Troubleshooting

Map Not Displaying

Check:

Token in mapbox_access_token.xml
Token is valid (test at mapbox.com)
Maven repository configured
Dependency added correctly
Internet permission in manifest

Style Not Loading

kotlin

mapView.mapboxMap.subscribeStyleLoaded { _ ->    Log.d("Map", "Style loaded successfully")    // Add layers and sources here}

mapView.mapboxMap.subscribeStyleLoaded { _ ->    Log.d("Map", "Style loaded successfully")    // Add layers and sources here}

Performance Issues

Use Style.STANDARD (recommended and optimized)
Limit visible annotations to viewport
Reuse annotation managers
Avoid frequent style reloads
Call lifecycle methods (onStart, onStop, onDestroy)
Batch annotation updates

Reference Files

Load these references when you need detailed patterns for specific topics:

references/compose.md -- Jetpack Compose: dependencies, token setup, MapboxMap, annotations with click, GeoJSON, MapEffect
references/annotations.md -- Circle, Polyline, and Polygon annotation patterns
references/location-tracking.md -- Camera follow user location + get current location once
references/custom-data.md -- GeoJSON sources and layers: lines, polygons, points, update/remove
references/camera-styles.md -- Camera control (set, animate, fit) + map styles (built-in and custom)
references/interactions.md -- Featureset interactions, custom layer taps, long press, gestures

Additional Resources

来源与署名

来源：mapbox/mapbox-agent-skills位于skills/mapbox-android-patterns提交aab3a6f

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Mapbox Android Patterns

Mapbox Android Integration Patterns

Installation & Setup

Requirements

Step 1: Configure Access Token

Step 1b: Internet permission (required)

Step 2: Add Maven Repository

Step 3: Add Dependency

Map Initialization

Jetpack Compose Pattern

View System Pattern

Add Markers (Point Annotations)

Show User Location (Display)

Performance Best Practices

Reuse Annotation Managers

Batch Annotation Updates

Lifecycle Management

Use Standard Style

Troubleshooting

Map Not Displaying

Style Not Loading

Performance Issues

Reference Files

Additional Resources

来源与署名

更多来自 mapbox/mapbox-agent-skills 的技能

Mapbox Web Performance Patterns

Mapbox Style Quality

Mapbox Mcp Devkit Patterns

Mapbox Location Grounding

Mapbox Ios Patterns

Mapbox Geospatial Operations

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api