地图配色方案

本指南：先说明地图由哪些元素组成、各自可配置哪些属性；再介绍 TASDK 集成侧 如何修改 TSS、通过 API 加载并调试配色。

功能介绍

地图视觉由 TSS（Theme Style Sheet，主题样式表） 驱动。TSS 是 Atlas 引擎的样式描述文件（.tss），为每个地图元素（layer）绑定颜色、线宽、文字、图标等属性，并支持按 白天/黑夜、缩放级别、俯仰角 插值变化。

地图数据 / 导航业务  →  feature-class、road-type、custom-line-type 等
        ↓
TSS layer<style key>  →  color / width / text-* / icon-* 等属性
        ↓
Atlas 渲染  →  底图、路线、POI、traffic …

TASDK 集成方通过 修改工程 assets 中的 .tss，并用 ViewOptions.stylePath / ThemeController.loadStyleSheet 加载预览实现的效果

一、地图元素与可配置属性

本节按 SDK 默认 TSS 中的样式结构整理，聚焦 底图数据元素 与 导航路线；

1.1 元素如何对应到 TSS

地图上的每一类可见对象，在 TSS 中对应一个 style layer：

1	`layer<layer-type> style-key[filter] { 属性: 值; };`

概念	说明	示例
`layer-type`	几何与渲染类型	`polygon`、`road`、`line`、`traffic-flow`、`poi`、`road-features`、`custom-line`
`style-key`	图层名，与 `layer_order` 一致	`land-color`、`road-primary`、`routes-traffic`
`filter`	数据筛选条件	`[road-type='Motorway']`、`[traffic-level='congested']`
属性值	直接写常量或引用 `@变量`	`color: @color-water;`

变量（@ 开头，如 @color-water、@road-width-primary）定义在 .tss 文件内，layer 通过 @变量名 引用，改一处即可影响多处 layer。

常用 filter key：

filter	用途
`feature-class` / `feature-type`	底图面/线/POI 类型，如 `Place`、`Water`、`Forest`
`road-type` / `road-sub-type`	道路等级、隧道 `Tunnel`等
`traffic-level`	路况：`free_flow`、`congested`、`closed` 等
`custom-line-type`	导航路线类型，如 `route.NAVIGABLE_ROUTE`

TSS 内 [zoom>=N] 与 SDK API 的 zoom level 方向相反：

1	`SDK zoom level = 18 - TSS zoom`

1.2 通用可配置属性

不同 layer-type 支持的属性不同，下表为常见项（完整列表以 newstyle.tss 中实际 layer 为准）。

面元素（layer<polygon>）

属性	说明
`color`	填充色，多引用 `@color-*`
`opacity`	透明度
`outline-color`、`outline-width`	描边（部分 layer）
`simplify-factor`、`simplify-func`	几何简化，影响性能与细节
`wave-speed`、`wave-intensity`、`wave-scale`、`wave-image1/2`、`wave-lighting`	水面波纹（水域）

线 / 道路（layer<line>、layer<road>、layer<custom-line>）

属性	说明
`width`	线宽，多引用 `@road-width-*`、`@route-width`
`color`	线条颜色
`opacity`	透明度
`outline`	是否为外描边 layer
`join`、`cap`	连接与端点样式
`pattern`、`simple-dash-array`	虚线/图案（铁路、边界等）
`offset`	线偏移（交通流）
`along-gradient`、`along-gradient-mode`、`along-gradient-trim`	路线沿长度渐变
`enable-route-eating`、`line-obstacle`	路线与引导元素裁剪
`simplify-factor`、`simplify-func`	几何简化

文字（layer<road-features>、POI、交通事件等）

属性	说明
`text-color`、`text-outline-color`	文字与描边色
`text-size`、`text-font`、`text-opacity`	字号、字体、透明度
`text-outline-width`、`text-placement`、`text-position-offset`	描边宽度、放置方式、偏移
`text-letter-spacing`、`text-max-angle`	字距、沿路最大夹角
`spacing`、`spacing-base`、`display-limit`	标注间距与显示上限
`require-text`	无文字则不渲染

图标（POI、交通事件等）

属性	说明
`icon-image` / `icon-path`	图标资源路径（相对 `mapdisplay` 根）
`icon-tint`、`icon-color`、`icon-size`、`icon-opacity`	着色、尺寸、透明度
`icon-position-offset`、`icon-anchor-position`、`icon-padding`	位置与边距
`priority`、`collision-enabled`、`display-limit`	碰撞优先级与显示限制

控件（UI overlay，如 the-scalebar、compass）

属性	说明
`icon-image`、`icon-color`、`icon-size`	比例尺条形背景/前景（`the-scalebar`）
`icon-anchor-position`、`icon-position-offset`	比例尺条形对齐与偏移（`the-scalebar`）
`text-color`、`text-outline-color`、`text-outline-width`	比例尺文字（`the-scalebar`）与指南针方位字（`compass`）
`text-size`、`text-position-offset`	比例尺与指南针文字大小与位置
`icon-image`、`icon-size`、`icon-placement`	指南针图标资源、尺寸与朝向（`compass`）

全局 settings（newstyle.tss 顶部）

属性	说明
`background-color`	地图背景，默认 `@color-place-land`
`fog-2d` / `fog-3d` / `fog-horizon` 系列	雾化与地平线
`light-color`、`light-intensity`、`light-elevation-deg`、`light-rotation-deg`	全局光照
`shadow-enabled`、`shadow-color`	阴影开关与颜色

动态表达式（变量定义中常用）：

函数	用途
`animated(key, [a: v1, b: v2])`	按 `time-of-day`、`zoom`、`declination` 连续插值
`stepped(key, [...])`	阶梯切换，常用于日/夜图标路径
`gradient(linear/reflected, [...])`	线/面渐变
`mix(#a, #b, 70%)`	颜色混合

日/夜典型写法：

@color-water-day:   #8DCDEB;
@color-water-night: #344467;
@color-water: animated(time-of-day, [0: @color-water-day, 1: @color-water-night]);

1.3 底图元素一览

底图来自地图数据，按几何类型分为以下几类（style key 为定制时的查找入口）。

地面与水域（polygon）

style key	地图元素	主要变量
`land-color`	陆地底色	`@color-place-land`
`island-color`	岛屿	`@color-place-island`
`waterway-color`、`natural-water`	洋/海、湖泊	`@color-water`、`@color-waterways-ocean`
`natural-bay`、`riverbank-color`、`canal-color`	海湾、河岸、运河	`@color-natural-bay`、`@color-waterways-river-bank`
`natural-glacier`、`landuse-reservoir`	冰川、水库	`@color-natural-glacier`、`@color-landuse-reservoir`

自然地物与土地使用（polygon）

style key	地图元素	主要变量
`beach-color`、`sand-color`	沙滩、沙地	`@color-natural-beach`
`national-park-color`	国家公园	`@color-boundary-national-park`
`leisure-color`	公园/高尔夫/体育中心	`@color-leisure-*`
`forest-color`、`military-color`、`landuse-color`	森林、军事区、工业/墓地等	`@color-landuse-*`
`tourism-color`、`parking-color`	旅游区、停车场	`@color-tourism`、`@color-amenity-parking`

设施与建筑（polygon / line）

style key	地图元素	主要变量
`aeroway-aerodrome`、`aeroway-runway`、`aeroway-runway-line`	机场、跑道	`@color-aeroway-*`
`amenities-hospital`、`amenities-university`、`amenities-color`	医院、大学、油站/银行等	`@color-amenity-*`
`buildings-color`、`shops-mall`	建筑、商场	`@color-building-*`、`@color-shop-mall`

道路网络（road）

每条道路通常有 主体 + 描边 两个 layer，隧道通过 [road-sub-type="Tunnel"] 覆盖颜色。

等级	style key（主体 / 描边）	颜色变量
高速	`road-motorway` / `road-motorway-outline`	`@color-road-motorway`
国道	`road-trunk` / `road-trunk-outline`	`@color-road-trunk`
一级～三级	`road-primary` … `road-tertiary`（含 link）	`@color-road-primary` 等
城市道路	`road-street`、`road-residential`、`road-service`	`@color-road-street`
其他	`road-ferry`、`road-path`、`road-pedestrian` 等	对应 `@color-road-*`
隧道	各道路 layer + Tunnel filter	`@color-road-tunnel`

宽度与透明度：在 TSS 中搜索 @road-width-base、@road-grow-*、@road-zoom-*、@road-opacity-* 等变量修改。

道路名称与路牌（road-features）

style key	可配置项
`road-labels`	`@text-color-road-`、`@text-size-road-`、`@spacing-road-label`
`road-badges`	道路编号盾牌，依赖 `badges.csv`
`oneway-arrows`	单行箭头图案与颜色

边界、水系线、轨道（line）

style key	地图元素	主要变量
`line-borders`、`line-borders-disputed`	行政/争议边界	`@color-line-country-border` 等
`lines-water`	河流、运河线	`@color-line-river`、`@color-line-canal`
`line-rails`、`line-subway`（含 pattern）	铁路、地铁	`@color-line-rail`、`@color-line-subway`

线宽：@line-width-base、@line-grow-*、@line-zoom-* → @line-width-*。

底图 POI 与地名

style key	说明	主要变量
`pois-all`	地图数据 POI（油站、医院等）	`@icon-path-`、`@icon-tint-`、`@text-color-`、`@priority-poi-`
`points-text`	国家/州/市/镇地名	`@text-color-place-`、`@priority-point-text-`

地图控件（overlay）

style key	说明	常见可配项
`the-scalebar`	比例尺控件样式（需先启用 `FeaturesController.scaleBar()`）	`icon-image`、`icon-color`、`icon-size`、`icon-position-offset`、`text-color`、`text-size`、`text-outline-color`
`compass`	指南针控件样式（需先启用 `FeaturesController.compass()`）	`icon-image`（主）、`icon-size`、`icon-placement`、`text-color`、`text-outline-color`、`text-size`、`text-position-offset`

the-scalebar、compass 属于 UI 控件样式，不依赖底图数据筛选条件（如 feature-class / road-type）。开启/关闭分别由 FeaturesController.scaleBar()、FeaturesController.compass() 控制。

交通流与交通事件

类型	style key 模式	可配置项
交通流	`traffic-motorway`、`traffic-primary` … + `traffic-outline-*`	路况色 `@color-traffic-free` … `@color-traffic-closed`；宽度 `@traffic-width-*`
交通事件	`traffic-incidents`	事件图标/文字色、`@icon-size-traffic-incidents`

1.4 路线元素一览

导航路线使用 layer<custom-line>，由 SDK RouteLine 传入 custom-line-type 匹配样式。

style key	用途
`navigable-route` / `navigable-route-outline`	可导航主路线
`waypoint-route` / `waypoint-route-outline`	概览、途经点、候选路线
`routes` / `routes-outline`	多方案 A/B/C、超出范围
`routes-traffic` / `routes-traffic-outline`	带路况分段的活跃路线
`routes-inactive`、`routes-traffic-inactive`	非活跃路线
`route-trace`、`route-alternative`、`ongoing-route`、`routes-glow`、`breadcrumb`	轨迹、备选、进行中、光晕、面包屑

custom-line-type	对应 layer
`route.NAVIGABLE_ROUTE`	`navigable-route`
`route.OVERVIEW_ROUTE_A/B/C`、`route.routeA/B/C`	`routes`
`active_route_1`	`routes`（活跃渐变）
`route.FREE_FLOW_EDGE` … `route.CLOSED_EDGE`	`routes-traffic`
`route.OUT_OF_RANGE`	`routes`（`@color-route-out-of-range`）

变量类别	代表变量	说明
尺寸	`@route-width`、`@route-outline-width`	线宽，随 zoom/俯仰变化
主色	`@color-navigable-route`、`@outline-color-navigable-route`	可导航路线
状态	`@color-route-active`、`@color-route-inactive`、`@color-route-fade`	活跃/非活跃；活跃线常用 `along-gradient`
多方案	`@color-route-A-active` … `@color-route-C-inactive`	配合 `distinguishRouteLegColors(true)`
路况	`@color-traffic-route--active` / `-inactive`	配合 `styleWithTraffic(true)`
其他	`@route-eating`、`@color-route-trace`	裁剪、轨迹色

路线 layer 除 1.2 节中的线属性外，重点使用 along-gradient、enable-route-eating。

二、TASDK 配置与调试

集成侧只需关心三件事：工程里有哪些 TSS → 改哪段 style → 用哪个 API 加载。

assets 中的 .tss  →  文本编辑修改变量 / layer  →  stylePath / loadStyleSheet  →  真机验证

2.1 TSS 资源位置

TASDK 将地图样式与依赖资源放在应用 assets 下，路径固定为：

src/main/assets/configuration/global/mapdisplay/
├── styles/
│   ├── default/newstyle.tss           # 中控默认
│   ├── default/newstyle-waypoint.tss
│   ├── cluster/newstyle.tss           # 仪表盘
│   ├── hud/newstyle.tss
│   └── intersection_view/newstyle.tss
├── textures/、fonts/、pois/ …          # TSS 内 icon-image、@icon-path-* 引用

说明	要点
`stylePath`	相对 `mapdisplay` 根目录的路径，如 `styles/default/newstyle.tss`
依赖资源	换图标时除改 TSS 外，须在 `mapdisplay` 下保留或替换对应图片
多份 TSS	不同屏幕/场景用不同文件，通过 API 切换，无需改引擎配置

集成工程若通过 Gradle 从 SDK 拷贝 Atlas 资源，上述目录结构与 SDK 发行包一致；调试时直接改本工程 assets 内文件即可。

2.2 ThemeController API

应用层通过 ViewOptions 初始化、ThemeController 运行时调整。

能力	API	说明
选择 TSS	`ViewOptions.stylePath` / `loadStyleSheet`	切换整套配色；路径须以 `.tss` 结尾

初始化示例：

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

运行时切换：

mapView.getThemeController()?.apply {
    loadStyleSheet("styles/default/newstyle-waypoint.tss")
    setTimeOfDay(1f)      // 夜间
    setTextScale(1.15f)
}

与路线/标注的关系：

能力	配色来源	集成说明
底图要素	TSS 内 `@color-*` 等变量	改 `.tss` 后 `loadStyleSheet`
路线	TSS + `RouteLine`	`styleWithTraffic(true)` 启用路况色
底图 POI	`pois-all` 变量	改 `@icon-path-*`
业务标注	TSS `styleKey`	见 Annotation
途经点分色	scheme B 变量 + `RouteLine`	`distinguishRouteLegColors(true)`

2.3 预设 TSS 路径

assets/configuration/global/mapdisplay/styles/
├── default/              # 中控默认
│   ├── newstyle.tss
│   ├── newstyle-waypoint.tss
│   └── newstyle-alt.tss
├── cluster/              # 仪表盘
├── hud/                  # HUD
├── hud_warm/             # HUD 暖色
└── intersection_view/    # 路口放大图

方案	`stylePath`	典型用途
默认（中控）	`styles/default/newstyle.tss`	主屏 `TnMapView`
航点强调	`styles/default/newstyle-waypoint.tss`	突出途经点/路线
仪表盘	`styles/cluster/newstyle.tss`	`TnClusterMapView`
HUD	`styles/hud/newstyle.tss`	抬头显示
路口放大图	`styles/intersection_view/newstyle.tss`	`TnIntersectionView`，见路口放大图

多屏可为不同 MapView 指定不同 stylePath，见多屏显示。

2.4 配置与调试流程

配色调试在 TASDK 侧按以下顺序进行：取项目 TSS → 改 style → API 加载验证。

① 获取项目 TSS     →  从 assets/mapdisplay 取出当前使用的 .tss
        ↓
② 修改 style       →  按第一章定位变量 / layer 并改色
        ↓
③ API 加载新 TSS   →  stylePath 或 loadStyleSheet 指向修改后的文件
        ↓
     真机查看效果   →  配合 setTimeOfDay、导航路线等场景复测

步骤 1：获取项目本身的 TSS

地图样式已随应用打在 assets 中。调试前先确认 当前 MapView 实际加载的是哪一份 TSS：

src/main/assets/configuration/global/mapdisplay/
├── styles/default/newstyle.tss          # 中控默认，最常用
├── styles/default/newstyle-waypoint.tss
├── styles/cluster/newstyle.tss
└── textures/、fonts/、pois/ …           # TSS 引用的资源，修改图标时须保留

操作建议：

在 Android Studio 中展开上述 assets 目录，或将 mapdisplay 整目录复制到工作区备份。
对照代码里的 ViewOptions.stylePath / loadStyleSheet(...)，确定基准文件（例如 styles/default/newstyle.tss）。
复制一份为试验文件，避免直接改坏默认包，例如：
styles/default/newstyle-oem.tss
或调试期放到可写目录：/sdcard/download/style/newstyle-oem.tss（须同时保证纹理等依赖路径有效）。

打开 .tss 后，用文本搜索定位要改的 style key（如 road-primary）或变量（如 @color-water），对应关系见 1.3 和 1.4 节。

步骤 2：按需求修改 style

在复制的 TSS 中修改与目标元素相关的变量或 layer 属性。常见改法：

需求	在 TSS 中查找并修改
陆地/背景	`@color-place-land`
水域	`@color-water`、`@color-water-day` / `@color-water-night`
某等级道路	`layer<road> road-primary` 段内的 `color`，或 `@color-road-primary`
路线颜色	`@color-navigable-route`、`@color-route-active` 等
路线线宽	`@route-width`

快速验证时，可先把目标变量改成高对比色（如 #FF0000），保存后加载新路径，确认地图是否变化。

修改 .tss 后，将文件保存到 assets 对应目录（或调试用的 SD 卡路径），进入步骤 3。

步骤 3：通过 TASDK API 加载新 TSS

将修改后的 .tss 放回 assets（或调试用的设备路径），用 相对 mapdisplay 根目录 的路径加载。

初始化时指定（新 MapView 生效）：

MapViewInitConfig(
    viewOptions = ViewOptions(
        stylePath = "styles/default/newstyle-oem.tss"  // 相对 mapdisplay
    )
)

运行时切换（已创建的 MapView 立即生效）：

mapView.getThemeController()?.loadStyleSheet("styles/default/newstyle-oem.tss")

调试包外路径（仅开发阶段，路径须存在且以 .tss 结尾）：

mapView.getThemeController()?.loadStyleSheet("/sdcard/download/style/newstyle-oem.tss")

约束与注意：

路径 必须以 .tss 结尾；文件不存在或路径错误时，loadStyleSheet 可能静默失败，需核对 assets 是否已随 APK 更新、路径是否与 mapdisplay 根一致。

常见问题

现象	排查
改了颜色地图无变化	是否加载了新路径；是否仍用默认 `newstyle.tss`；assets 是否重新打包
图标不显示	`@icon-path-*` 对应文件是否在 `mapdisplay` 下
道路粗细异常	是否只改了颜色未改宽度变量；是否与 traffic/outline 不一致

2.5 常见修改场景速查

在 .tss 中全文搜索变量名即可定位（与 1.3 和 1.4 节对照）：

需求	在 TSS 中搜索并修改
陆地/背景色	`@color-place-land`
水域色	`@color-water`、`@color-water-day`、`@color-water-night`
道路颜色	`@color-road-motorway`、`@color-road-primary` 等
道路粗细	`@road-width-base`、`@road-grow-motorway`、`@road-width-motorway`
路线颜色/粗细	`@color-navigable-route`、`@route-width`；渐变端点 `@color-route-fade`
路况路线色	`@color-traffic-route-free-active` 等
POI 图标	`@icon-path-amenity-fuel` 等，并替换 `mapdisplay` 下对应图片
比例尺（ScaleBar）样式	`the-scalebar` 及其 `icon-color`、`icon-size`、`text-color`、`text-outline-color`、`text-size`
指南针（Compass）样式	`compass` 及其 `icon-image`（主）、`icon-size`、`icon-placement`、`text-color`、`text-outline-color`、`text-size`

集成示例

以下示例串联 2.4 节的配置与调试流程：初始化加载默认 TSS → 在 assets 中修改并加载定制文件 → 按场景切换预设 TSS。

// ① 初始化：指定默认 TSS（路径相对 mapdisplay 根目录）
mapView.initialize(
    MapViewInitConfig(
        context = context,
        listener = object : MapView.OnReadyListener {
            override fun onReady() {
            }
        },
        viewOptions = ViewOptions(
            stylePath = "styles/default/newstyle.tss",
            dayNightMode = DayNightMode.DAY
        )
    )
)

// ② 调试期：修改 assets 内 .tss 后，运行时切换（无需重建 MapView）
fun reloadCustomTheme() {
    mapView.getThemeController()?.loadStyleSheet("styles/default/newstyle-oem.tss")
}

注意事项

仅支持 .tss：stylePath / loadStyleSheet 路径须以 .tss 结尾，否则不生效。