mapbox-android-patterns

Mapbox Android 集成模式

在 Android 上使用 Kotlin、Jetpack Compose 和 View 系统集成 Mapbox Maps SDK v11 的官方模式。

在以下情况下使用此技能：

• 安装和配置 Mapbox Maps SDK for Android
• 在地图上添加标记和注释
• 显示用户位置并使用相机跟踪
• 向地图添加自定义数据（GeoJSON）
• 使用地图样式、相机或用户交互
• 处理要素交互和点击

官方资源：

• Android 地图指南
• API 参考
• 示例应用

---

安装与设置

要求

• Android SDK 21+
• Kotlin 或 Java
• Android Studio
• 免费的 Mapbox 账户

第 1 步：配置访问令牌

创建 app/res/values/mapbox_access_token.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>

获取令牌： 在 mapbox.com 登录

第 1b 步：网络权限（必需）

地图需要网络访问权限。在 AndroidManifest.xml 中加入以下内容——Agent 经常会遗漏这一项，之后只列出位置权限：

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

第 2 步：添加 Maven 仓库

在 settings.gradle.kts 中：

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

第 3 步：添加依赖项

在模块的 build.gradle.kts 中：

android {
    defaultConfig {
        minSdk = 21
    }
}

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

用于 Jetpack Compose：

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

---

地图初始化

Jetpack Compose 模式

基本地图：

import androidx.compose.runtime.*
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.maps.extension.compose.*
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

@Composable
fun 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()
            )
        }
    }
}

带装饰元素：

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

View 系统模式

布局 XML（activity_map.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>

Activity：

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.mapbox.maps.MapView
import com.mapbox.maps.Style
import 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()
    }
}

---

添加标记（点注释）

点注释是地图上标记位置最常用的方式。

Jetpack Compose：

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 系统：

// Create annotation manager (once, reuse for updates)
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

// Create marker
val pointAnnotation = PointAnnotationOptions()
    .withPoint(Point.fromLngLat(-122.4194, 37.7749))
    .withIconImage("custom-marker")

pointAnnotationManager.create(pointAnnotation)

多个标记：

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)

---

显示用户位置（显示）

第 1 步：在 AndroidManifest.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" />

第 2 步：请求权限并显示位置：

// Request permissions first (use ActivityResultContracts)

// Show location puck
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

---

性能最佳实践

复用注释管理器

// Don't create new managers repeatedly
// val manager = mapView.annotations.createPointAnnotationManager() // each call

// Create once, reuse
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

fun updateMarkers() {
    pointAnnotationManager.deleteAll()
    pointAnnotationManager.create(markers)
}

批量更新注释

// Create all at once
pointAnnotationManager.create(allAnnotations)

// Don't create one by one in a loop

生命周期管理

// Always call lifecycle methods
override fun onStart() {
    super.onStart()
    mapView.onStart()
}

override fun onStop() {
    super.onStop()
    mapView.onStop()
}

override fun onDestroy() {
    super.onDestroy()
    mapView.onDestroy()
}

使用标准样式

// Standard style is optimized and recommended
Style.STANDARD

// Use other styles only when needed for specific use cases
Style.STANDARD_SATELLITE // Satellite imagery

---

故障排除

地图未显示

检查：

1. mapbox_access_token.xml 中的令牌
2. 令牌是否有效（在 mapbox.com 上测试）
3. 是否已配置 Maven 仓库
4. 是否已正确添加依赖项
5. 清单中是否有网络权限

样式未加载

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

性能问题

• 使用 Style.STANDARD（推荐且经过优化）
• 将可见注释限制在视口范围内
• 复用注释管理器
• 避免频繁重新加载样式
• 调用生命周期方法（onStart、onStop、onDestroy）
• 批量更新注释

---

参考文件

需要了解特定主题的详细模式时，请加载以下参考资料：

• references/compose.md —— Jetpack Compose：依赖项、令牌设置、MapboxMap、带点击功能的注释、GeoJSON、MapEffect
• references/annotations.md —— 圆形、折线和多边形注释模式
• references/location-tracking.md —— 相机跟随用户位置 + 获取一次当前位置
• references/custom-data.md —— GeoJSON 数据源和图层：线、多边形、点、更新/移除
• references/camera-styles.md —— 相机控制（设置、动画、适配）+ 地图样式（内置和自定义）
• references/interactions.md —— 要素集交互、自定义图层点击、长按、手势

---

更多资源

• Android 地图指南
• API 参考
• 交互指南
• Jetpack Compose 指南
• 示例应用
• 迁移指南（v10 -> v11）