地图特性

本指南：通过 FeaturesController 开关路况、建筑、地形、指南针、卫星图等地图可视化特性。

功能介绍

FeaturesController 提供地图各 可视化特性（Feature） 的开关。大多数特性通过通用 Feature 接口的 setEnabled() / setDisabled() 控制；少数特性（如 ADI 引导线、面包屑、转弯气泡）提供专用接口。

获取入口：

val features = mapView.getFeaturesController() ?: return

核心接口一览

分类	方法	返回类型	默认状态	说明
路况	traffic()	Feature	关闭	拥堵路况着色
路况	freeFlowTraffic()	Feature	关闭	自由流路况
地图内容	landmarks()	Feature	—	地标建筑
地图内容	buildings()	Feature	—	3D 建筑物
地图内容	terrain()	Feature	—	三维地形
地图内容	globe()	Feature	—	地球仪模式
地图内容	fourWDRoad()	Feature	—	四驱道路标识
地图内容	roadNames()	Feature	开启	道路名称标注
地图内容	satelliteMap()	Feature	关闭	卫星底图
UI 控件	compass()	Feature	—	指南针
UI 控件	scaleBar()	Feature	—	比例尺
UI 控件	copyright()	Feature	—	版权信息
导航相关	adiLine()	AdiFeature	—	ADI 引导线
导航相关	breadcrumbs()	BreadcrumbsFeature	—	轨迹面包屑
导航相关	turnBubbles()	TurnBubbleFeature	—	转弯气泡
调试	showFps()	Feature	关闭	FPS 显示（仅调试）
调试	dpiDebug()	Feature	关闭	DPI 调试（仅调试）

Feature 通用开关

适用于上表中返回 Feature 的特性：

features.traffic().setEnabled()   // 开启
features.traffic().setDisabled()  // 关闭

---

各 Feature 详解

以下按功能分类逐一介绍。

---

1. traffic — 路况

在地图上按拥堵程度对道路进行着色，帮助用户了解前方交通状况。适用于浏览模式或导航前预览路况。

效果示意：

接口	说明
features.traffic().setEnabled()	开启路况显示
features.traffic().setDisabled()	关闭路况显示

示例代码：

features.traffic().setEnabled()

---

2. freeFlowTraffic — 自由流路况

显示道路的 自由流 路况信息，与 traffic() 的拥堵着色互补，用于展示非拥堵状态下的道路通行情况。

效果示意：

接口	说明
features.freeFlowTraffic().setEnabled()	开启自由流路况
features.freeFlowTraffic().setDisabled()	关闭自由流路况

示例代码：

features.freeFlowTraffic().setEnabled()

---

3. landmarks — 地标

在地图上显示知名地标建筑（如标志性塔楼、大型建筑等），增强地图辨识度。

效果示意：

接口	说明
features.landmarks().setEnabled()	显示地标
features.landmarks().setDisabled()	隐藏地标

示例代码：

features.landmarks().setEnabled()

---

4. buildings — 建筑物

在地图上渲染 3D 建筑物 模型，提升城市区域的立体感和空间感。通常在 zoom 较高时效果更明显。

效果示意：

接口	说明
features.buildings().setEnabled()	显示 3D 建筑
features.buildings().setDisabled()	隐藏 3D 建筑

示例代码：

features.buildings().setEnabled()

---

5. terrain — 三维地形

启用 三维地形 渲染，地图会呈现山脉、丘陵等地形起伏；可与 satelliteMap() 同时启用，两个 Feature 互不排斥。完整说明见 三维地形。

效果示意：

接口	说明
features.terrain().setEnabled()	开启三维地形
features.terrain().setDisabled()	关闭三维地形

示例代码：

features.terrain().setEnabled()

高程数据支持 在线（Streaming）下载，不强制预装本地地图包；预装/混合方案亦可使用本地数据。详见 三维地形 与 Streaming 数据下载。

---

6. globe — 地球仪模式

以 地球仪 视角展示地图，在低缩放级别下呈现球形地球效果，适合全球浏览场景。

接口	说明
features.globe().setEnabled()	开启地球仪模式
features.globe().setDisabled()	关闭地球仪模式

示例代码：

features.globe().setEnabled()

---

7. fourWDRoad — 四驱道路

在地图上标识 四驱（4WD）可通行道路，适用于越野导航或特殊路况场景。

接口	说明
features.fourWDRoad().setEnabled()	显示四驱道路
features.fourWDRoad().setDisabled()	隐藏四驱道路

示例代码：

features.fourWDRoad().setEnabled()

---

8. roadNames — 道路名称

控制地图上 道路名称标注 的显示与隐藏。该特性 默认开启。

接口	说明
features.roadNames().setEnabled()	显示道路名称（默认）
features.roadNames().setDisabled()	隐藏道路名称

示例代码：

// 隐藏道路名称（如极简地图模式）
features.roadNames().setDisabled()

---

9. satelliteMap — 卫星底图

将底图切换为 卫星影像，替代默认矢量地图。该特性 默认关闭。启用前需完成卫星图初始化配置（API Key、缓存空间等），详见 卫星图。

效果示意：

接口	说明
features.satelliteMap().setEnabled()	切换为卫星底图
features.satelliteMap().setDisabled()	恢复矢量底图

示例代码：

features.satelliteMap().setEnabled()

可与 terrain() 同时启用，两个 Feature 可并存，详见 三维地形。

---

10. compass — 指南针

在地图上显示 指南针 控件，指示当前地图朝向（北向）。

接口	说明
features.compass().setEnabled()	显示指南针
features.compass().setDisabled()	隐藏指南针

示例代码：

features.compass().setEnabled()

---

11. scaleBar — 比例尺

在地图上显示 比例尺 控件，根据当前缩放级别动态显示距离刻度。

接口	说明
features.scaleBar().setEnabled()	显示比例尺
features.scaleBar().setDisabled()	隐藏比例尺

示例代码：

features.scaleBar().setEnabled()

比例尺边距可通过 LayoutController.setMapScaleBarMargin(...) 调整，详见 主题与布局。

---

12. copyright — 版权信息

在地图上显示 地图数据版权信息（如 HERE 等数据供应商标识）。

接口	说明
features.copyright().setEnabled()	显示版权信息
features.copyright().setDisabled()	隐藏版权信息

示例代码：

features.copyright().setEnabled()

版权信息边距可通过 LayoutController.setCopyrightMargin(...) 调整，详见 主题与布局。

---

13. adiLine — ADI 引导线

ADI（As-the-Driver-Intends）引导线：从当前车辆位置到指定终点绘制一条 直线引导线，常用于目的地预览或简易导航引导。

接口	参数	类型	说明
adiLine().setEnabled(endPoint)	endPoint	Location	引导线终点（经纬度）
adiLine().setDisabled()	—	—	关闭引导线

示例代码：

val destination = Location("").apply {
    latitude = 37.7749
    longitude = -122.4194
}
features.adiLine().setEnabled(destination)

// 到达目的地预览结束
features.adiLine().setDisabled()

---

14. breadcrumbs — 轨迹面包屑

在地图上绘制车辆 历史行驶轨迹（面包屑），由业务方传入定位点列表。适用于轨迹回放、越野记录等场景。

接口	参数	类型	说明
breadcrumbs().AddBreadcrumbs(points)	points	List<Location?>	历史轨迹点列表
breadcrumbs().ClearBreadcrumbs()	—	—	清除全部面包屑

示例代码：

// 持续追加轨迹点
val historyPoints: List<Location> = locationTracker.getHistory()
features.breadcrumbs().AddBreadcrumbs(historyPoints)

// 结束记录 / 切换行程时清除
features.breadcrumbs().ClearBreadcrumbs()

---

15. turnBubbles — 转弯气泡

在路线步骤附近展示 转向箭头 与 下一道路名，由导航事件驱动。详细用法见 转弯气泡。

效果示意：

fun enableTurnBubble(
    routeId: String,
    legIndex: Int,
    stepIndex: Int,
    turnBubbleType: TurnType,
    nextStreetName: String?
)

fun disableTurnBubble(routeId: String, legIndex: Int, stepIndex: Int)

fun disableAllTurnBubbles()

参数	类型	说明
routeId	String	当前导航路线 ID
legIndex	Int	路线 leg 索引
stepIndex	Int	leg 内 step 索引
turnBubbleType	TurnType	转弯类型（仅 enableTurnBubble）
nextStreetName	String?	下一道路名（仅 enableTurnBubble）

示例代码：

features.turnBubbles().enableTurnBubble(
    routeId = navRouteId,
    legIndex = 0,
    stepIndex = 2,
    turnBubbleType = TurnType.LEFT,
    nextStreetName = "Main St"
)

---

16. showFps — FPS 显示（仅调试）

在地图上叠加引擎 实时帧率（FPS） 信息，仅用于开发调试，量产版本请关闭。

接口	说明
features.showFps().setEnabled()	显示 FPS
features.showFps().setDisabled()	隐藏 FPS

示例代码：

if (BuildConfig.DEBUG) {
    features.showFps().setEnabled()
}

---

17. dpiDebug — DPI 调试（仅调试）

开启 DPI 调试 叠加层，仅用于开发调试，量产版本请关闭。

接口	说明
features.dpiDebug().setEnabled()	开启 DPI 调试
features.dpiDebug().setDisabled()	关闭 DPI 调试

示例代码：

if (BuildConfig.DEBUG) {
    features.dpiDebug().setEnabled()
}

---

特性互斥与依赖

规则	说明
satelliteMap + terrain	可同时启用，两个 Feature 可并存；开启卫星图时需完成卫星图初始化
satelliteMap	需在 SDK 初始化时配置 API Key 与缓存，详见 卫星图
turnBubbles	需导航事件提供 route / leg / step / TurnType，详见 转弯气泡
showFps / dpiDebug	仅调试用途，量产请关闭

注意事项

• 所有特性开关可在 MapView.onReady 之后随时调用。
• roadNames() 默认开启；若 HMI 需要极简地图，可主动 setDisabled()。
• satelliteMap() 默认关闭；启用前请确认卫星图模块已正确初始化。

相关指南

• 地图配色方案
• 转弯气泡
• 卫星图
• 主题与布局
• 快速开始
• 指南首页