Annotation

本指南：在地图上添加、更新与管理 POI 及自定义标注。

功能介绍

标注（Annotation）用于在地图上展示 POI、用户自定义标记、分组气泡等点状内容。通过 AnnotationsController 管理标注的增删改查与图层开关；通过 AnnotationFactory 创建不同类型的标注实例。

支持点击/长按触摸回调，详见 触摸与手势。

效果示意：

核心接口

AnnotationsController

方法	说明
factory(): AnnotationFactory	获取标注工厂
add(annotations: List<Annotation?>)	添加标注
current(): List<Annotation?>	获取当前全部标注
update(annotations: List<Annotation?>)	更新已添加标注
updateState(annotation, state, transitionTime)	更新 TSS 中定义的状态
remove(annotations: List<Annotation?>)	移除指定标注
clear()	清除全部标注（含其他模块添加的）
region(annotations): Camera.Region	计算标注包围区域
actionOnLayer(layer, action)	对整个图层 Enable/Disable

LayerAction：Enable、Disable

Annotation

Type（标注类型）

类型	说明
Flat	平铺在地图上，与北向对齐
ViewerFacing	始终面向相机，3D 世界中随距离缩放
Screen2D	屏幕坐标定位
LatLonToScreen2D	经纬度转屏幕坐标，随地图移动而更新位置

Style（部分常用）

ScreenAnnotationPopup、ScreenAnnotationPopupGrouping、ScreenAnnotationPin 等，控制优先级、聚合与遮挡行为。

Layer（图层）

图层	说明
Default	默认
POI	POI 标注
TrafficIncident	交通事件
UserDefinedFirst ~ UserDefinedLast	用户自定义层级

动态属性

方法	说明
updateFloatValue(key, value)	更新 TSS 浮点属性
updateStringValue(key, value)	更新字符串属性
updateColor(key, color)	更新颜色属性
updateState(state, transitionTime)	更新显示状态

UserGraphic

Annotation.UserGraphic(bitmap, forceCopy = true)

forceCopy = true 时复制 Bitmap，避免外部 recycle 导致崩溃。

AnnotationFactory

通过 annotationsController.factory() 获取，支持：

方法	说明
资源 ID 创建	@DrawableRes 图标
UserGraphic	自定义 Bitmap
POIAnnotationParams	POI 样式与文本
路线相关标注	与导航路线关联的标注

POIAnnotationParams / POIStyle

用于 POI 标注：styleKey、location、text 等，配合 地图显示兴趣点(POI) 使用。

关键参数

• 优先级：Layer 与 Style 决定渲染顺序与是否被车辆/指南针遮挡。
• TSS 状态：updateState 中的 state 字符串须在当前加载的 TSS 文件中存在。
• clear() 影响范围：清除本 MapView 上所有标注，包括其他业务模块添加的。

接口详细说明

1. add — 添加标注

fun add(annotations: List<Annotation?>)

参数	类型	说明
annotations	List<Annotation?>	待添加到地图上的标注集合

---

2. update — 更新标注

fun update(annotations: List<Annotation?>)

参数	类型	说明
annotations	List<Annotation?>	已添加标注的更新集合

---

3. remove — 移除标注

fun remove(annotations: List<Annotation?>)

参数	类型	说明
annotations	List<Annotation?>	需要从地图移除的标注集合

---

4. updateState — 切换 TSS 状态

fun updateState(
    annotation: Annotation,
    state: String,
    transitionTime: Float
)

参数	类型	说明
annotation	Annotation	需要切换状态的标注对象
state	String	TSS 中定义的状态名；不存在时不会得到预期样式
transitionTime	Float	状态切换动画时长，单位秒

---

5. region — 计算标注包围区域

fun region(annotations: List<Annotation?>): Camera.Region

参数	类型	说明
annotations	List<Annotation?>	用于计算包围区域的标注集合
返回值	Camera.Region	可用于 CameraController.showRegion 适配视野

---

6. actionOnLayer — 图层开关

fun actionOnLayer(
    layer: Annotation.Layer,
    action: LayerAction
)

参数	类型	说明
layer	Annotation.Layer	标注图层，影响显示层级与批量开关
action	LayerAction	图层操作，支持 Enable / Disable

---

7. AnnotationFactory.create — 创建标注

自定义 Bitmap：

fun create(userGraphic: Annotation.UserGraphic): Annotation

参数	类型	说明
userGraphic	Annotation.UserGraphic	自定义 Bitmap 图形，可用于业务图标

POI 标注：

fun create(params: POIAnnotationParams): Annotation

参数	类型	说明
params.styleKey	String	TSS 中的标注样式 key
params.location	Location	标注地理位置
params.text	String	标注显示文本

示例代码

val annotationsCtrl = mapView.getAnnotationsController() ?: return
val factory = annotationsCtrl.factory()

// 从 drawable 创建
val annotation = factory.create(R.drawable.ic_poi_marker)
annotation.location = Location("poi").apply {
    latitude = 37.39
    longitude = -122.08
}

annotationsCtrl.add(listOf(annotation))

// 更新状态（TSS 中定义的状态名）
annotationsCtrl.updateState(annotation, "highlighted", transitionTime = 0.3f)

// 禁用某图层
annotationsCtrl.actionOnLayer(Annotation.Layer.POI, AnnotationsController.LayerAction.Disable)

// 适配相机到标注区域
val region = annotationsCtrl.region(listOf(annotation))
mapView.getCameraController()?.showRegion(region)

// 移除
annotationsCtrl.remove(listOf(annotation))

注意事项

• 标注触摸需在 MapView 上注册 AnnotationTouchListener。
• clear() 会清除所有标注，多业务共存时慎用，优先 remove。
• POI 搜索展示的标注也可通过 DynamicPOISearchController 管理，见 地图显示兴趣点(POI)。

相关指南

• Annotation Bubble
• 地图显示兴趣点(POI)
• 触摸与手势
• 地图配色方案
• 指南首页