Mapbox Android 集成模式

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

使用此技能的场景：

• - 安装和配置 Android 版 Mapbox Maps SDK
• 在地图上添加标记和注释
• 显示用户位置并通过摄像头进行跟踪
• 向地图添加自定义数据（GeoJSON）
• 处理地图样式、摄像头或用户交互
• 处理要素交互和点击事件

官方资源：

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

安装与设置

系统要求

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

第 1 步：配置访问令牌

创建 app/res/values/mapboxaccesstoken.xml：

xml


accesstoken translatable=false
tools:ignore=UnusedResources>YOURMAPBOXACCESS_TOKEN

获取令牌： 登录 mapbox.com

第 2 步：添加 Maven 仓库

在 settings.gradle.kts 中：

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

第 3 步：添加依赖

在模块 build.gradle.kts 中：

kotlin
android {
defaultConfig {
minSdk = 21
}
}

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

对于 Jetpack Compose：

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

地图初始化

Jetpack Compose 模式

基础地图：

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

带装饰元素：

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

View 系统模式

布局 XML（activity_map.xml）：

xml

xmlns:android=http://schemas.android.com/apk/res/android
android:layoutwidth=matchparent
android:layoutheight=matchparent>

android:id=@+id/mapView
android:layoutwidth=matchparent
android:layoutheight=matchparent />

Activity：

kotlin
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：

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

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

// 创建标记
val pointAnnotation = PointAnnotationOptions()
.withPoint(Point.fromLngLat(-122.4194, 37.7749))
.withIconImage(custom-marker)

pointAnnotationManager.create(pointAnnotation)

多个标记：

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)

显示用户位置

第 1 步：在 AndroidManifest.xml 中添加权限：

xml
FINELOCATION />
COARSELOCATION />

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

kotlin
// 先请求权限（使用 ActivityResultContracts）

// 显示位置图标
mapView.location.updateSettings {
enabled = true
puckBearingEnabled = true
}

性能最佳实践

复用注释管理器

kotlin
// 不要重复创建新的管理器
// val manager = mapView.annotations.createPointAnnotationManager() // 每次调用

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

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

批量更新注释

kotlin
// 一次性创建所有注释
pointAnnotationManager.create(allAnnotations)

// 不要在循环中逐个创建

生命周期管理

kotlin
// 始终调用生命周期方法
override fun onStart() {
super.onStart()
mapView.onStart()
}

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

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

使用标准样式

kotlin
// 标准样式经过优化，推荐使用
Style.STANDARD

// 仅在特定用例需要时使用其他样式
Style.STANDARD_SATELLITE // 卫星影像

故障排除

地图不显示

检查：

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

样式未加载

kotlin
mapView.mapboxMap.subscribeStyleLoaded { _ ->
Log.d(Map, 样式加载成功)
// 在此处