Skip to content

地图特性

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

功能介绍

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

获取入口： 

1
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 的特性： 

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

各 Feature 详解

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

1. traffic — 路况

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

效果示意：

路况

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

示例代码： 

1
features.traffic().setEnabled()

2. freeFlowTraffic — 自由流路况

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

效果示意：

自由流路况

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

示例代码： 

1
features.freeFlowTraffic().setEnabled()

3. landmarks — 地标

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

效果示意：

地标

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

示例代码： 

1
features.landmarks().setEnabled()

4. buildings — 建筑物

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

效果示意：

3D 建筑物

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

示例代码： 

1
features.buildings().setEnabled()

5. terrain — 三维地形

启用 三维地形 渲染，地图会呈现山脉、丘陵等地形起伏。与 satelliteMap() 不宜同时开启，避免渲染冲突。

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

示例代码： 

1
features.terrain().setEnabled()

地形数据需提前通过 MapContent / 本地数据安装配置，参见 数据下载。

6. globe — 地球仪模式

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

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

示例代码： 

1
features.globe().setEnabled()

7. fourWDRoad — 四驱道路

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

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

示例代码： 

1
features.fourWDRoad().setEnabled()

8. roadNames — 道路名称

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

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

示例代码： 

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

9. satelliteMap — 卫星底图

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

效果示意：

卫星底图

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

示例代码： 

1
features.satelliteMap().setEnabled()

与 terrain() 不宜同时开启；切换时建议先关闭另一方。

10. compass — 指南针

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

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

示例代码： 

1
features.compass().setEnabled()

11. scaleBar — 比例尺

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

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

示例代码： 

1
features.scaleBar().setEnabled()

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

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

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

示例代码： 

1
features.copyright().setEnabled()

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

13. adiLine — ADI 引导线

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

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

示例代码： 

1
2
3
4
5
6
7
8
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() — — 清除全部面包屑

示例代码： 

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

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

15. turnBubbles — 转弯气泡

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

效果示意：

转弯气泡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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）

示例代码： 

1
2
3
4
5
6
7
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

示例代码： 

1
2
3
if (BuildConfig.DEBUG) {
    features.showFps().setEnabled()
}

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

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

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

示例代码： 

1
2
3
if (BuildConfig.DEBUG) {
    features.dpiDebug().setEnabled()
}

特性互斥与依赖

规则 说明
satelliteMap + terrain 不宜同时开启，避免渲染冲突；切换时先关闭另一方
satelliteMap 需在 SDK 初始化时配置 API Key 与缓存，详见 卫星图
turnBubbles 需导航事件提供 route / leg / step / TurnType，详见 转弯气泡
showFps / dpiDebug 仅调试用途，量产请关闭

注意事项

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

相关指南