Mapbox Android 集成模式

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

适用场景：

• 安装与配置 Mapbox Maps SDK for Android
• 向地图添加标记（Markers）和注释（Annotations）
• 显示用户位置并结合相机（Camera）实现位置追踪
• 向地图添加自定义数据（GeoJSON）
• 操作地图样式（Styles）、相机（Camera）或用户交互行为
• 处理要素（Feature）交互与点击事件

官方资源：

• Android Maps 指南
• API 参考文档
• 示例应用

安装与配置

系统要求

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

步骤 1：配置访问令牌（Access Token）

创建 app/res/values/mapbox_access_token.xml 文件：

    YOUR_MAPBOX_ACCESS_TOKEN

获取您的令牌：请登录 mapbox.com

步骤 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()
    ) {
        // 通过 MapEffect 初始化相机（默认加载 Style.STANDARD）
        MapEffect(Unit) { mapView ->
            // 设置初始相机位置
            mapView.mapboxMap.setCamera(
                CameraOptions.Builder()
                    .center(Point.fromLngLat(-122.4194, 37.7749))
                    .zoom(12.0)
                    .build()
            )
        }
    }
}

启用图例控件（Ornaments）：

MapboxMap(
    modifier = Modifier.fillMaxSize(),
    scaleBar = {
        ScaleBar(
            enabled = true,
            position = Alignment.BottomStart
        )
    },
    compass = {
        Compass(enabled = true)
    }
) {
    // 默认加载 Style.STANDARD
}

View 系统模式

布局 XML（activity_map.xml）：

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()
    }
}

添加标记（点注释，Point Annotations）

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

Jetpack Compose：

MapboxMap(modifier = Modifier.fillMaxSize()) {
    MapEffect(Unit) { mapView ->
        // 先加载样式
        mapView.mapboxMap.loadStyle(Style.STANDARD)

        // 创建注释管理器并添加标记
        val annotationManager = mapView.annotations.createPointAnnotationManager()
        val pointAnnotation = PointAnnotationOptions()
            .withPoint(Point.fromLngLat(-122.4194, 37.7749))
            .withIconImage("custom-marker")
        annotationManager.create(pointAnnotation)
    }
}

// 注意：Compose 当前不提供声明式的 PointAnnotation 组件
// 标记必须通过 MapEffect 以命令式方式添加

View 系统：

// 创建注释管理器（仅需一次，后续可复用）
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

// 创建单个标记
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)

显示用户位置（Display）

步骤 1：在 AndroidManifest.xml 中添加权限声明：

步骤 2：请求权限并启用位置显示：

// 首先请求权限（建议使用 ActivityResultContracts）

// 启用位置指示器（Location Puck）
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

性能最佳实践

复用注释管理器（Annotation Managers）

// ❌ 避免重复创建新管理器
// val manager = mapView.annotations.createPointAnnotationManager() // 每次调用均新建

// ✅ 创建一次，反复复用
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

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

批量更新注释

// ✅ 批量创建全部注释
pointAnnotationManager.create(allAnnotations)

// ❌ 避免在循环中逐个创建

生命周期管理

// 务必调用对应生命周期方法
override fun onStart() {
    super.onStart()
    mapView.onStart()
}

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

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

优先使用标准样式（Standard Style）

// Style.STANDARD 已针对性能优化，为官方推荐样式
Style.STANDARD

// 仅在特定需求下才使用其他样式
Style.STANDARD_SATELLITE // 卫星影像

问题排查

地图未显示

请检查以下项目：

1. mapbox_access_token.xml 中是否已正确配置 Token
2. Token 是否有效（可在 mapbox.com 上验证）
3. Maven 仓库是否已正确配置
4. 依赖项是否已正确添加
5. AndroidManifest.xml 中是否已声明网络权限

样式未加载成功

mapView.mapboxMap.subscribeStyleLoaded { _ ->
    Log.d("Map", "Style loaded successfully")
    // 此处可安全添加图层（Layers）与数据源（Sources）
}

性能问题

• 优先使用 Style.STANDARD（推荐且已优化）
• 限制视口（Viewport）内可见的注释数量
• 复用注释管理器（Annotation Managers）
• 避免频繁重新加载样式
• 务必调用生命周期方法（onStart、onStop、onDestroy）
• 使用批量方式更新注释

参考文件

当您需要特定主题的详细实现模式时，请加载以下参考文件：

• references/annotations.md —— 圆形（Circle）、折线（Polyline）与多边形（Polygon）注释模式
• references/location-tracking.md —— 相机跟随用户位置 + 一次性获取当前位置
• references/custom-data.md —— GeoJSON 数据源与图层：线、面、点，以及更新与移除操作
• references/camera-styles.md —— 相机控制（设置、动画、适配视图） + 地图样式（内置与自定义）
• references/interactions.md —— 要素集（FeatureSet）交互、自定义图层点击、长按、手势等

附加资源

• Android Maps 指南
• API 参考文档
• 交互指南（Interactions Guide）
• Jetpack Compose 指南
• 示例应用
• 迁移指南（v10 → v11）