# Mapbox Android 集成模式将 Android 上的 Mapbox Maps SDK v11 与 Kotlin、Jetpack Compose 和 View 系统集成的官方模式。 **在以下情况下使用此技能：** * 安装和配置适用于 Android 的 Mapbox 地图 SDK * 在地图上添加标记和注释 * 通过摄像头显示用户位置和跟踪 * 将自定义数据（GeoJSON）添加到地图中 * 使用地图样式、相机或用户交互 * 处理功能交互和点击 **官方资源：** * [Android 地图指南]() * [API 参考]() * [示例应用程序]() ** ** ## 安装和设置 ### 要求 * 安卓 SDK 21+ * Kotlin 或 Java * 安卓工作室 * 免费 Mapbox 帐户 ### 第 1 步：配置访问令牌创建`app/res/values/mapbox_access_token.xml`： <资源 xmlns:tools="http://schemas.android.com/tools"> <字符串名称=“mapbox_access_token”翻译=“假” 工具：ignore =“UnusedResources”>您的_MAPBOX_ACCESS_TOKEN **获取您的令牌：** 登录 [mapbox.com]() ### 步骤 2：添加 Maven 存储库在“settings.gradle.kts”中：依赖解析管理 { 存储库{ 谷歌() mavenCentral() 行家{ url = uri("https://api.mapbox.com/downloads/v2/releases/maven") } } } ### 第 3 步：添加依赖项在模块“build.gradle.kts”中：安卓{ 默认配置{ 最小SDK = 21 } } 依赖项{ 实现（“com.mapbox.maps：android：11.18.1”） } **对于 Jetpack Compose：** 依赖项{ 实现（“com.mapbox.maps：android：11.18.1”）实现（“com.mapbox.extension：maps-compose：11.18.1”） } ** ** ## 地图初始化 ### Jetpack 撰写模式 **基本地图：** 导入 androidx.compose.runtime.* 导入 androidx.compose.foundation.layout.fillMaxSize 导入 androidx.compose.ui.Modifier 导入 com.mapbox.maps.extension.compose.* 导入 com.mapbox.maps.Style 导入 com.mapbox.geojson.Point @可组合有趣的地图屏幕（）{ 地图框地图( 修饰符 = Modifier.fillMaxSize() ）{ // 通过MapEffect初始化相机（默认加载Style.STANDARD）地图效果（单位）{ 地图视图-> // 设置初始相机位置 mapView.mapboxMap.setCamera( CameraOptions.Builder() .center(Point.fromLngLat(-122.4194, 37.7749)) .缩放(12.0) .build() ） } } } **带饰品：** 地图框地图( 修改器 = Modifier.fillMaxSize(), 比例尺 = { 比例尺（启用=真，位置 = Alignment.BottomStart ） }, 指南针={ 指南针（启用= true） } ）{ // Style.STANDARD 默认加载 } ### 查看系统模式 **布局 XML (activity_map.xml)：** **活动：** 导入 android.os.Bundle 导入 androidx.appcompat.app.AppCompatActivity 导入 com.mapbox.maps.MapView 导入 com.mapbox.maps.Style 导入 com.mapbox.geojson.Point 类 MapActivity : AppCompatActivity() { private Lateinit var mapView: MapView 覆盖 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)) .缩放(12.0) .build() ） mapView.mapboxMap.loadStyle(Style.STANDARD) } 重写 fun onStart() { super.onStart() 地图视图.onStart() } 重写 fun onStop() { super.onStop() 地图视图.onStop() } 重写 fun onDestroy() { super.onDestroy() mapView.onDestroy() } } ** ** ## 添加标记（注释） ### 点注释（标记）点注释是在地图上标记位置的最常见方法。 **Jetpack 撰写：** MapboxMap(修改器 = Modifier.fillMaxSize()) { 地图效果（单位）{ 地图视图-> // 首先加载样式 mapView.mapboxMap.loadStyle(Style.STANDARD) // 创建注释管理器并添加标记 val 注释管理器 = mapView.annotations.createPointAnnotationManager() val pointAnnotation = PointAnnotationOptions() .withPoint(Point.fromLngLat(-122.4194, 37.7749)) .withIconImage("自定义标记") 注释管理器.create(pointAnnotation) } } // 注意：Compose 没有声明性 PointAnnotation 组件 // 必须通过 MapEffect 强制添加标记 **查看系统：** // 创建注释管理器（一次，重用更新） val pointAnnotationManager = mapView.annotations.createPointAnnotationManager() // 创建标记 val pointAnnotation = PointAnnotationOptions() .withPoint(Point.fromLngLat(-122.4194, 37.7749)) .withIconImage("自定义标记") pointAnnotationManager.create(pointAnnotation) **多个标记：** val 位置 = listOf( 点.fromLngLat(-122.4194, 37.7749), 点.fromLngLat(-122.4094, 37.7849), 点.fromLngLat(-122.4294, 37.7649) ） val 注释 = Locations.map { 点 -> 点注释选项() .withPoint(点) .withIconImage("标记") } pointAnnotationManager.create(注释) ### 圆圈注释 val CircleAnnotationManager = mapView.annotations.createCircleAnnotationManager() val 圆 = CircleAnnotationOptions() .withPoint(Point.fromLngLat(-122.4194, 37.7749)) .withCircleRadius(10.0) .withCircleColor("#FF0000") CircleAnnotationManager.create(圆) ### 折线注释 val polylineAnnotationManager = mapView.annotations.createPolylineAnnotationManager() val 折线 = PolylineAnnotationOptions() .withPoints(listOf(point1, point2, point3)) .withLineColor("#0000FF") .withLineWidth(4.0) polylineAnnotationManager.create(折线) ### 多边形注释 val PolygonAnnotationManager = mapView.annotations.createPolygonAnnotationManager() valpoints = listOf(listOf(coord1, coord2, coord3, coord1)) // 闭合多边形 val 多边形 = PolygonAnnotationOptions() .withPoints(点) .withFillColor("#0000FF") .withFillOpacity(0.5) PolygonAnnotationManager.create(多边形) ** ** ## 显示用户位置 ### 显示用户位置 **第1步：向AndroidManifest.xml添加权限：**

**第 2 步：请求权限并显示位置：** // 首先请求权限（使用ActivityResultContracts） // 显示位置圆盘 mapView.location.updateSettings { 启用=真 puckBearingEnabled = true } ### 相机跟随用户位置要使相机在用户移动时跟随用户的位置：类 MapActivity : AppCompatActivity() { private Lateinit var mapView: MapView 覆盖 fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_map) mapView = findViewById(R.id.mapView) mapView.mapboxMap.loadStyle(Style.STANDARD) 设置位置跟踪() } 私人乐趣 setupLocationTracking() { // 首先请求权限（使用ActivityResultContracts） // 显示用户位置 mapView.location.updateSettings { 启用=真 puckBearingEnabled = true } // 使用摄像头跟踪用户位置 mapView.location.addOnIndicatorPositionChangedListener { 点 -> mapView.camera.easeTo( CameraOptions.Builder() .center(点) .缩放(15.0) .螺距(45.0) .build(), MapAnimationOptions.Builder() .持续时间(1000) .build() ） } // 可选：也遵循方位（方向） mapView.location.addOnIndicatorBearingChangedListener { 轴承 -> mapView.camera.easeTo( CameraOptions.Builder() .轴承(轴承) .build(), MapAnimationOptions.Builder() .持续时间(1000) .build() ） } } 重写 fun onStart() { super.onStart() 地图视图.onStart() } 重写 fun onStop() { super.onStop() 地图视图.onStop() } 重写 fun onDestroy() { super.onDestroy() mapView.onDestroy() } } ### 获取当前位置一次 mapView.location.getLastLocation { 位置 -> 位置？.让{ val point = Point.fromLngLat(it.经度, it.纬度) mapView.camera.easeTo( CameraOptions.Builder() .center(点) .缩放(14.0) .build() ） } } ** ** ## 添加自定义数据 (GeoJSON) 使用 GeoJSON 源和图层将您自己的数据添加到地图中。 ### 添加线路（路线、路径） // 创建线的坐标 val 路线坐标 = listOf( 点.fromLngLat(-122.4194, 37.7749), 点.fromLngLat(-122.4094, 37.7849), 点.fromLngLat(-122.3994, 37.7949) ） // 创建 GeoJSON 源 val geoJsonSource = geoJsonSource("路线源") { 几何（LineString.fromLngLats（路线坐标）） } mapView.mapboxMap.style?.addSource(geoJsonSource) // 创建线层 val lineLayer = lineLayer("路由层", "路由源") { 线条颜色(颜色.蓝色) 线宽(4.0) lineCap(LineCap.ROUND) lineJoin(LineJoin.ROUND) } mapView.mapboxMap.style?.addLayer(lineLayer) ### 添加多边形（区域） val 多边形坐标 = listOf( listOf(coord1, coord2, coord3, coord1) // 闭合多边形） val geoJsonSource = geoJsonSource("区域源") { 几何（多边形.fromLngLats（多边形坐标）） } mapView.mapboxMap.style?.addSource(geoJsonSource) val fillLayer = fillLayer("区域填充", "区域源") { fillColor(Color.parseColor("#0000FF")) 填充不透明度(0.3) fillOutlineColor(Color.parseColor("#0000FF")) } mapView.mapboxMap.style?.addLayer(fillLayer) ### 从 GeoJSON 添加点 val geojsonString = """ { "type": "特征集合", “特点”：[ { “类型”：“特征”， "几何": {"类型": "点", "坐标": [-122.4194, 37.7749]}, "属性": {"名称": "位置 1"} }, { “类型”：“特征”， "几何": {"类型": "点", "坐标": [-122.4094, 37.7849]}, "属性": {"名称": "位置 2"} } ] } ”“” val geoJsonSource = geoJsonSource("点源") { 数据（geojson字符串） } mapView.mapboxMap.style?.addSource(geoJsonSource) val symbolLayer = symbolLayer("点层", "点源") { 图标图像（“标记”） textField(Expression.get("名称")) textOffset(listOf(0.0, 1.5)) } mapView.mapboxMap.style?.addLayer(symbolLayer) ### 更新图层属性 mapView.mapboxMap.style?.getLayerAs("route-layer")?.let { 图层 -> 图层.lineColor(颜色.RED) 图层.lineWidth(6.0) } ### 删除图层和源 mapView.mapboxMap.style?.removeStyleLayer("路线层") mapView.mapboxMap.style?.removeStyleSource("路线源") ** ** ## 相机控制 ### 设置相机位置 // 撰写 - 更新相机状态相机状态.position = CameraPosition( 中心 = Point.fromLngLat(-74.0060, 40.7128), 变焦 = 14.0, 轴承 = 90.0，螺距 = 60.0 ） // 视图 - 立即 mapView.mapboxMap.setCamera( CameraOptions.Builder() .center(Point.fromLngLat(-74.0060, 40.7128)) .缩放(14.0) .轴承(90.0) .螺距(60.0) .build() ） ### 动画相机转换 // 飞行动画（戏剧性的弧线） mapView.camera.flyTo( CameraOptions.Builder() .中心（目的地） .缩放(15.0) .build(), MapAnimationOptions.Builder() .持续时间(2000) .build() ） // 缓动动画（平滑） mapView.camera.easeTo( CameraOptions.Builder() .中心（目的地） .缩放(15.0) .build(), MapAnimationOptions.Builder() .持续时间(1000) .build() ） ### 使相机适合坐标 val 坐标 = listOf(coord1, coord2, coord3) val 相机 = mapView.mapboxMap.cameraForCoordinates( 坐标，边缘插入(50.0, 50.0, 50.0, 50.0), 轴承 = 0.0，螺距 = 0.0 ） mapView.camera.easeTo(相机) ** ** ## 地图样式 ### 内置样式 // Compose - 通过 MapEffect 加载样式 MapboxMap(修改器 = Modifier.fillMaxSize()) { 地图效果（单位）{ 地图视图-> // Style.STANDARD 默认加载，只有其他样式才需要显式加载 // mapView.mapboxMap.loadStyle(Style.STREETS) // Mapbox 街道 // mapView.mapboxMap.loadStyle(Style.OUTDOORS) // Mapbox 户外 // mapView.mapboxMap.loadStyle(Style.LIGHT) // Mapbox 灯光 // mapView.mapboxMap.loadStyle(Style.DARK) // Mapbox 深色 // mapView.mapboxMap.loadStyle(Style.STANDARD_SATELLITE) // 卫星图像 // mapView.mapboxMap.loadStyle(Style.SATELLITE_STREETS) // 卫星+街道 } } // 视图 mapView.mapboxMap.loadStyle(Style.STANDARD) mapView.mapboxMap.loadStyle(Style.DARK) ### 自定义样式 URL val customStyleUrl = "mapbox://styles/用户名/style-id" // 撰写 MapboxMap(修改器 = Modifier.fillMaxSize()) { 地图效果（单位）{ 地图视图-> mapView.mapboxMap.loadStyle(customStyleUrl) } } // 视图 mapView.mapboxMap.loadStyle(customStyleUrl) ** ** ## 用户交互和功能点击 ### 功能集交互（推荐）现代交互 API 允许通过类型化功能访问来处理地图功能上的点击。适用于标准样式预定义要素集，例如 POI、建筑物和地点标签。 **查看系统模式：** 导入 com.mapbox.maps.interactions.ClickInteraction 类 MapActivity : AppCompatActivity() { private Lateinit var mapView: MapView 覆盖 fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_map) mapView = findViewById(R.id.mapView) mapView.mapboxMap.loadStyle(Style.STANDARD) 设置功能交互() } 私人乐趣 setupFeatureInteractions() { // 点击 POI 功能 mapView.mapboxMap.addInteraction( ClickInteraction.standardPoi { poi, 上下文 -> Log.d("MapTap", "已点击的 POI: ${poi.name}") true // 停止传播 } ） // 点击建筑物 mapView.mapboxMap.addInteraction( ClickInteraction.standardBuildings { 建筑、上下文 -> Log.d("MapTap", "攻陷建筑") // 突出显示建筑物 mapView.mapboxMap.setFeatureState( 建筑物, 标准建筑状态 { 突出显示（真） } ）真实 } ） } 重写 fun onStart() { super.onStart() 地图视图.onStart() } 重写 fun onStop() { super.onStop() 地图视图.onStop() } 重写 fun onDestroy() { super.onDestroy() mapView.onDestroy() } } **Jetpack 撰写模式：** @可组合有趣的地图屏幕（）{ MapboxMap(修改器 = Modifier.fillMaxSize()) { 地图效果（单位）{ 地图视图-> // 加载标准样式 mapView.mapboxMap.loadStyle(Style.STANDARD) // 使用View系统API添加功能集交互 mapView.mapboxMap.addInteraction( ClickInteraction.standardPoi { poi, 上下文 -> Log.d("MapTap", "已点击的 POI: ${poi.name}") 真实 } ） mapView.mapboxMap.addInteraction( ClickInteraction.standardBuildings { 建筑、上下文 -> Log.d("MapTap", "攻陷建筑") mapView.mapboxMap.setFeatureState( 建筑物, 状态=mapOf（“选择”为true））真实 } ） } } } // 注意：Compose 中的 Featureset 交互使用 MapEffect 来访问 //底层MapView和使用View系统交互API ### 点击自定义图层 ``科特林 mapView.mapboxMap.addInteraction( ClickInteraction.layer("custom-layer-id") { 特征, 上下文 -> Log.d("MapTap", "要素属性：${feature.properties()}") 真实 } ） ### 长按互动导入 com.mapbox.maps.interactions.LongClickInteraction mapView.mapboxMap.addInteraction( LongClickInteraction.standardPoi { poi, 上下文 -> Log.d("MapTap", "长按 POI: ${poi.name}") 真实 } ） ### 处理地图点击（空白） mapView.gestures.addOnMapClickListener { 点 -> Log.d("MapClick", "点击位置：${point.latitude()}, ${point.longitude()}") true // 消费事件 } ### 手势配置 // 禁用特定手势 mapView.gestures.pitchEnabled = false mapView.gestures.rotateEnabled = false // 配置缩放限制 mapView.mapboxMap.setCamera( CameraOptions.Builder() .缩放(12.0) .build() ） ** ** ## 性能最佳实践 ### 重用注释管理器 // ❌不要重复创建新的管理者有趣的更新标记（）{ val manager = mapView.annotations.createPointAnnotationManager() 管理器.创建（标记） } // ✅ 创建一次，重复使用 val pointAnnotationManager = mapView.annotations.createPointAnnotationManager() 有趣的更新标记（）{ pointAnnotationManager.deleteAll() pointAnnotationManager.create(标记) } ### 批量注释更新 // ✅ 一次性创建所有 pointAnnotationManager.create(allAnnotations) // ❌ 不要一一创建 allAnnotations.forEach { 注释 -> pointAnnotationManager.create(注释) } ### 生命周期管理 // 始终调用生命周期方法重写 fun onStart() { super.onStart() 地图视图.onStart() } 重写 fun onStop() { super.onStop() 地图视图.onStop() } 重写 fun onDestroy() { super.onDestroy() mapView.onDestroy() } ### 使用标准样式 // ✅ 标准样式优化推荐风格.标准 // 仅在特定用例需要时才使用其他样式 Style.STANDARD_SATELLITE // 卫星图像 ** ** ## 故障排除 ### 地图未显示 **检查：** 1. ✅ `mapbox_access_token.xml` 中的令牌 2. ✅ Token有效（在mapbox.com测试） 3. ✅ 配置 Maven 存储库 4. ✅ 正确添加依赖 5. ✅ 清单中的互联网权限 ### 样式未加载 mapView.mapboxMap.subscribeStyleLoaded { _ -> Log.d("地图", "样式加载成功") // 在这里添加层和源 } ### 性能问题 * 使用`Style.STANDARD`（推荐和优化） * 将可见注释限制在视口中 * 重用注释管理器 * 避免频繁的样式重新加载 * 调用生命周期方法（onStart、onStop、onDestroy） * 批量注释更新 ** ** ## 其他资源 * [Android 地图指南]() * [API参考]() * [交互指南]() * [Jetpack 撰写指南]() * [示例应用程序]() * [迁移指南 (v10 → v11)]()

Mapbox Android 模式

包含技能