主题与布局

本指南：运行时切换 TSS 样式、调节日/夜与文字缩放，并配置地图内容偏移、UI 遮挡避让、比例尺与版权边距。

功能介绍

地图的视觉样式与屏幕布局由两个控制器分工管理：

控制器	职责
ThemeController	TSS 样式切换、文字缩放、日/夜过渡
LayoutController	地图内容偏移、UI 遮挡区域（Obstructed Region）、比例尺与版权边距

初始化时可通过 MapViewInitConfig.viewOptions（ViewOptions）指定默认 TSS 路径、日/夜模式与最大倾角；运行时在 onReady 之后通过上述两个控制器动态调整。

获取入口：

val theme = mapView.getThemeController() ?: return
val layout = mapView.getLayoutController() ?: return

TSS 预设路径、日/夜配色机制与 OEM 换肤流程详见 地图配色方案。本文聚焦 API 用法。

核心接口一览

ThemeController

方法	说明
loadStyleSheet(stylePath)	运行时加载 TSS 样式文件
setTextScale(scale)	文字缩放（0.5 ~ 2.0，默认 1.0）
setTimeOfDay(timeOfDay)	日/夜过渡（0 白天 → 1 夜间）
getTimeOfDay()	获取当前日/夜值

ViewOptions（初始化）

参数	类型	默认	说明
maxDeclination	Float	51f	最大相机倾角（0 俯视 ~ 70 贴地）
dayNightMode	Int?	null	初始日/夜模式；null 使用系统默认
stylePath	String?	null	初始 TSS 路径；null 使用引擎默认样式

LayoutController

方法	说明
setVerticalOffset(offset)	设置垂直偏移，归一化区间 [-1.0, 1.0]（0.0 居中，-1.0 底部，1.0 顶部；越界自动 clamp）
setHorizontalOffset(offset)	设置水平偏移，归一化区间 [-1.0, 1.0]（0.0 居中，-1.0 左侧，1.0 右侧；越界自动 clamp）
setOffsets(horizontal, vertical)	同时设置水平与垂直偏移（归一化区间 [-1.0, 1.0]）
addObstructedRegion(x, y, width, height)	添加遮挡区域（像素坐标）
addObstructedRegion(rect)	添加遮挡区域（Rect 形式）
removeObstructedRegion(id)	移除指定遮挡区域
removeAllObstructedRegions()	移除全部遮挡区域
setMapScaleBarMargin(horizontal, vertical)	比例尺边距（基准：右下角）
setCopyrightMargin(horizontal, vertical)	版权文字边距（基准：左下角，单位像素）

---

接口详细说明

1. loadStyleSheet — 运行时切换 TSS 样式

在地图已就绪后，动态加载另一套 TSS（Theme Style Sheet）样式文件，切换整套地图配色（道路、水域、POI、路线等）。

fun loadStyleSheet(
    stylePath: String
)

参数	类型	说明
stylePath	String	TSS 文件路径；支持 assets 相对路径或设备绝对路径（调试用）

TSS 路径规范：

规则	说明
文件格式	仅支持 .tss
资源位置	Android assets 下 configuration/global/mapdisplay/
默认路径	styles/default/newstyle.tss
多视图	如 styles/cluster/newstyle.tss、styles/hud/newstyle.tss
路径写法	相对于 mapdisplay 目录，不要 带 configuration/global/mapdisplay 前缀
调试	支持设备绝对路径（如 /sdcard/download/styles/hud_warm.tss），仅调试用

示例代码：

// 切换到 Cluster 仪表盘样式
theme.loadStyleSheet("styles/cluster/newstyle.tss")

// 切换到带 waypoint 配色的默认样式
theme.loadStyleSheet("styles/default/newstyle-waypoint.tss")

---

2. setTextScale — 文字缩放

调整地图上道路名称、标注等文字的整体缩放比例。

fun setTextScale(
    scale: Float
)

参数	类型	说明
scale	Float	缩放比例；默认 1.0f，有效范围 0.5 ~ 2.0

示例代码：

theme.setTextScale(1.2f)  // 放大 20%
theme.setTextScale(0.8f)  // 缩小 20%

---

3. setTimeOfDay / getTimeOfDay — 日/夜过渡

控制地图的日/夜明暗过渡。0 为白天，1 为夜间，中间值为渐变过渡（如黄昏效果）。

接口方法	参数 / 返回值	类型	说明
setTimeOfDay(timeOfDay)	timeOfDay	Float	0.0 白天，1.0 夜间，中间值平滑过渡
setTimeOfDay(timeOfDay)	返回值	Boolean	true 设置成功；false 设置失败
getTimeOfDay()	返回值	Float	当前日/夜值

示例代码：

// 切换到夜间
theme.setTimeOfDay(1.0f)

// 黄昏过渡（偏夜间）
theme.setTimeOfDay(0.8f)

// 读取当前值
val current = theme.getTimeOfDay()

ViewOptions.dayNightMode 用于 初始化 时设定日/夜；setTimeOfDay 用于 运行时 动态调节。两者可同时存在，建议业务层统一策略，避免冲突。详见 地图配色方案。

---

4. ViewOptions — 初始化配置

在 MapViewInitConfig 创建时通过 viewOptions 传入，一次性设定默认样式、日/夜与最大倾角。

参数	类型	默认	说明
maxDeclination	Float	51f	最大相机倾角；0 为完全俯视（2D），70 为最大贴地视角
dayNightMode	Int?	null	初始日/夜；null 使用系统默认；可用 DayNightMode.DAY / DayNightMode.NIGHT
stylePath	String?	null	初始 TSS 路径；null 使用引擎默认 styles/default/newstyle.tss

示例代码：

val config = MapViewInitConfig(
    context = context,
    listener = readyListener,
    viewOptions = ViewOptions(
        maxDeclination = 51f,
        dayNightMode = DayNightMode.NIGHT,
        stylePath = "styles/default/newstyle-waypoint.tss"
    )
)
mapView.initialize(config)

---

5. setVerticalOffset / setHorizontalOffset / setOffsets — 地图内容偏移

将地图内容的渲染中心在屏幕上做水平 / 垂直偏移，常用于 CVP 不在屏幕正中 的 HMI 布局（如底部有大面板，需要把地图中心上移）。

偏移量采用 归一化区间 [-1.0, 1.0]（非像素）：

• 垂直偏移：0.0 居中，-1.0 底部，1.0 顶部
• 水平偏移：0.0 居中，-1.0 左侧，1.0 右侧
• 超出区间的值会被自动 clamp 到边界值

  fun setVerticalOffset(
      offset: Double
  )
  

参数	类型	说明
offset	Double	垂直偏移量（归一化 [-1.0, 1.0]）
fun setHorizontalOffset( offset: Double )

参数	类型	说明
offset	Double	水平偏移量（归一化 [-1.0, 1.0]）
fun setOffsets(horizontalOffset: Double, verticalOffset: Double)

参数	类型	说明
horizontalOffset	Double	水平偏移量（归一化 [-1.0, 1.0]）
verticalOffset	Double	垂直偏移量（归一化 [-1.0, 1.0]）

示例代码：

// 地图中心上移（偏向顶部）
layout.setVerticalOffset(0.35)

// 地图中心右移（偏向右侧）
layout.setHorizontalOffset(0.2)

// 或同时设置
layout.setOffsets(horizontalOffset = 0.2, verticalOffset = 0.35)

// 恢复默认（无偏移）
layout.setOffsets(0.0, 0.0)

重要：CameraController.showRegionForRoutes / showRegionForModelInstance 在 offset 非零时行为可能异常，调用前建议先将 offset 置为 0。详见 显示模式与视角。

---

6. addObstructedRegion — 添加 UI 遮挡区域

在地图上标记一块 不可绘制地图内容的矩形区域（Obstructed Region），引擎会自动避让，不在该区域渲染 POI、路名等内容。适用于 HMI 面板、浮层、底部 Dock 等遮挡地图 UI 的场景。

fun addObstructedRegion(x: Int, y: Int, width: Int, height: Int): Long?

参数	类型	说明
x	Int	遮挡区域左上角 x（像素，相对 MapView）
y	Int	遮挡区域左上角 y（像素）
width	Int	遮挡区域宽度（像素）
height	Int	遮挡区域高度（像素）
返回值	Long?	遮挡区域 ID；失败返回 null

重载：Rect 形式

fun addObstructedRegion(rect: Rect): Long?

参数	类型	说明
rect	android.graphics.Rect	以 Rect 表达的遮挡区域

示例代码：

// 为底部 200px 高的导航栏留出遮挡区域
val bottomBarId = layout.addObstructedRegion(
  x = 0,
  y = mapView.height - 200,
  width = mapView.width,
  height = 200
) ?: return

// 使用 Rect 形式（等效）
val rect = Rect(0, mapView.height - 200, mapView.width, mapView.height)
val id = layout.addObstructedRegion(rect)

// HMI 面板收起时移除
layout.removeObstructedRegion(bottomBarId)

---

7. removeObstructedRegion / removeAllObstructedRegions — 移除遮挡区域

fun removeObstructedRegion(id: Long): Boolean
fun removeAllObstructedRegions(): Boolean

方法	参数	返回值	说明
removeObstructedRegion	id: Long	Boolean	移除指定遮挡区域
removeAllObstructedRegions	—	Boolean	移除全部遮挡区域

示例代码：

layout.removeObstructedRegion(bottomBarId)
layout.removeAllObstructedRegions()

---

8. setMapScaleBarMargin — 比例尺边距

调整 比例尺 控件相对 MapView 右下角 的边距。需先通过 FeaturesController.scaleBar().setEnabled() 开启比例尺。

fun setMapScaleBarMargin(horizontalMargin: Double, verticalMargin: Double)

参数	类型	说明
horizontalMargin	Double	相对右边缘的水平边距（像素）
verticalMargin	Double	相对底边缘的垂直边距（像素）

示例代码：

mapView.getFeaturesController()?.scaleBar()?.setEnabled()
layout.setMapScaleBarMargin(horizontalMargin = 16.0, verticalMargin = 80.0)

---

9. setCopyrightMargin — 版权信息边距

调整 版权文字 相对 MapView 左下角 的边距。需先通过 FeaturesController.copyright().setEnabled() 开启版权显示。

fun setCopyrightMargin(horizontalMargin: Double, verticalMargin: Double)

参数	类型	说明
horizontalMargin	Double	相对左边缘的水平边距（像素）
verticalMargin	Double	相对底边缘的垂直边距（像素）

示例代码：

mapView.getFeaturesController()?.copyright()?.setEnabled()
layout.setCopyrightMargin(horizontalMargin = 16.0, verticalMargin = 24.0)

---

完整示例：HMI 底部面板布局

以下示例展示常见的 HMI 集成场景：底部有导航面板，需要偏移地图中心、添加遮挡区域，并调整比例尺与版权位置。

mapView.setOnReadyListener {
    val theme = mapView.getThemeController() ?: return@setOnReadyListener
    val layout = mapView.getLayoutController() ?: return@setOnReadyListener
    val features = mapView.getFeaturesController() ?: return@setOnReadyListener

    // 1) 样式与日夜
    theme.loadStyleSheet("styles/default/newstyle.tss")
    theme.setTimeOfDay(0.0f)

    // 2) 开启比例尺与版权
    features.scaleBar().setEnabled()
    features.copyright().setEnabled()

    // 3) 底部 200px 面板：偏移 + 遮挡
    val panelHeight = 200
    // 按面板高度折算为归一化偏移（向上偏移为正值）
    val verticalOffset = (panelHeight.toDouble() / mapView.height.toDouble()).coerceIn(0.0, 1.0)
    layout.setVerticalOffset(verticalOffset)
    layout.addObstructedRegion(0, mapView.height - panelHeight, mapView.width, panelHeight)

    // 4) 调整控件边距，避开面板
    layout.setMapScaleBarMargin(16.0, (panelHeight + 16).toDouble())
    layout.setCopyrightMargin(16.0, (panelHeight + 16).toDouble())
}

注意事项

• ThemeController 与 LayoutController 须在 MapView.onReady 之后使用。
• TSS 文件须已打包进 assets（configuration/global/mapdisplay/styles/）或引擎资源配置路径。
• loadStyleSheet 切换样式时可能有短暂加载过程，建议在非关键交互时段切换。
• setTimeOfDay 与 ViewOptions.dayNightMode 建议由业务层统一管理，避免初始化与运行时策略冲突。
• 调用 showRegionForRoutes 等相机 API 前，建议将 layout offset 归零。
• 遮挡区域坐标以 MapView 左上角 为原点，单位为像素；屏幕旋转或 MapView 尺寸变化时需重新计算。

相关指南

• 地图配色方案
• 地图特性（比例尺 / 版权开关）
• 显示模式与视角（offset 与路线全览）
• 快速开始
• 指南首页