在编辑器里调出来的每个样式,背后都是一份样式配置(JSON)。平时用编辑器点选就够了;需要批量生成、精确复用,或者让 AI 帮你设计样式时,直接读写这份配置更高效。本文是配置的完整规则,开发者可以照着手写,也可以整篇交给 AI 作为生成依据。
简易配置可以随时在编辑器中「转为高级模式」,平台会把它展开成等效的完整配置继续编辑;转换后不能再转回简易配置。
选择建议:先用简易配置把整体风格定下来,需要单独改某一类道路、某一类兴趣点,或者按级别控制时,再转为完整配置。
两种配置都遵守以下约定,写错时通常不会报错,只是那一项不生效:
颜色只写 6 位十六进制 #RRGGBB,大小写均可。不支持 #FFF、#FFFFFF80、rgb()、rgba()、颜色名。
数值写 JSON 数字,10 而不是 "10"。
显隐写 JSON 布尔值 true / false,不要写 0 / 1 或字符串。
基础模板 template 只能是已发布的基础模板,预置有 light(浅色)、dark(深色)、classic(PC 经典)。不写时用平台默认模板(浅色);写了不存在的模板会报错。
配置里只认文档列出的字段,其他字段会被忽略。
简易配置用几组颜色、粗细和开关描述一套地图风格,对应编辑器的简易模式。平台会按下面的规则把它自动展开成完整配置,你不需要了解要素分类和缩放级别。适合快速出风格,也最适合让 AI 生成。
{"mode": "simple","name": "午夜蓝","template": "dark","background": { "land": "#101C2E", "water": "#0B2644", "green": "#12292E", "landuse": "#132236" },"road": { "color": "#3B7FDB", "width": 1.1 },"building": { "color": "#18283E" },"label": { "textColor": "#8FA7C8", "size": 1 },"poi": { "visible": false },"saturation": -10,"sky": { "color": "#101C2E" }}
除 mode 外,所有字段都可以不写,没写的部分保持基础模板的外观。 只想换道路和水系颜色,就只写这两项。
简易配置里不能同时写 featureStyles。
每个分组都有 visible:写 false 隐藏这一组,写 true 或不写保持模板默认。
路沿(道路两侧的描边)自动取「路面色与陆地色各一半」的混合色,让道路和底图自然分开。
车道线、斑马线、护栏等路面细节保持模板颜色。
「标注」指地图上全部的文字和图标:地名、道路名、兴趣点名、站点名,以及兴趣点图标、交通站点图标、道路编号牌等。
文字描边(文字外圈的光晕)自动取陆地色:写了 textColor,或只写了 background.land 时都会这样处理。描边色不能单独设置。
图标染色保留图标原有的明暗,把色相换成 iconColor,白色图案保持白色;多色图标染色后会变成同一色相的深浅。道路编号牌这类带文字的图标也会被染色,注意和 textColor 拉开反差。
这几个分组只有 visible 一个字段,例如 "poi": { "visible": false }。
取值 -100 ~ 100,默认 0:-100 完全去色,0 不变,100 饱和度加倍。
在上面所有颜色生效之后最后应用,所以地图上看到的是调整后的颜色。
作用于道路、水系、绿地等线和面、3D 建筑,以及文字和图标。面的边框、箭头、国界和省界线不受影响。
不写时使用基础模板预设的天空色。天空只在地图倾斜时看得到,深色风格建议把天空也调暗。
倍率超出 0.5 ~ 2、saturation 超出 -100 ~ 100 时,平台按边界值处理;在编辑器的 JSON 编辑框里应用时会直接提示错误。
格式不对的字段按没写处理,其他字段照常生效。
分组写了 visible: false 后,组内其他字段不再影响这一组的外观。例外:background.land 即使背景被隐藏,也仍然用于推导路沿、文字描边和天空底部。
所有颜色都按原样使用,平台不做对比度兜底。请自己保证反差:文字与陆地、道路与陆地、水系绿地与陆地都不要太接近。
简易配置不包含默认视野,地图打开时使用默认视角。
完整配置对应编辑器的高级模式:选一个基础模板,再用 featureStyles 写几条规则,改写模板中想改的要素。没写到的内容保持模板默认值,只写需要改的规则即可。
{"name": "午夜蓝","template": "dark","featureStyles": [{ "id": "background.landform.water", "geometry": { "fillColor": "#0B2644", "strokeColor": "#0B2644" } },{ "id": "road.highway", "geometry": { "fillColor": "#3B7FDB", "strokeColor": "#0E2442", "strokeWidth": 1 } },{ "id": "poi", "label": { "fillColor": "#6F86A6", "strokeColor": "#101C2E" } }],"config": {"sky": { "topColor": "#101C2E", "bottomColor": "#132236" }}}
这份配置以深色模板为底,把水系改成深蓝,高速公路改成亮蓝,并统一调整了兴趣点的文字颜色。
不要写 mode 字段:"mode": "simple" 表示简易配置。其他未列出的顶层字段会被忽略。
featureStyles 的每一项是一条规则,改写一类要素的样式:
{"id": "road.highway","geometry": { "fillColor": "#3B7FDB", "strokeColor": "#0E2442", "width": 10, "strokeWidth": 1 },"label": { "fillColor": "#9CC2F5", "strokeColor": "#101C2E", "fontSize": 24 },"icon": { "scale": 0.8 }}
geometry、label、icon 至少写一个,都必须是对象;规则里不要有其他字段。
规则只改写它明确写出的属性,其余属性保持模板默认值。
每个属性都可以写固定值,也可以按缩放级别分别取值,见第三节。
config 与 featureStyles 平级,只决定天空外观和地图打开时的初始视角,不影响要素样式。每个字段都可以省略。
"config": {"sky": { "topColor": "#5285E0", "bottomColor": "#E6F2FF" },"defaultView": { "center": [116.404, 39.915], "zoom": 12, "pitch": 0, "heading": 0 }}
新建样式时,基础模板预设的天空色会带进样式;模板没有预设时默认为 #5285E0 / #E6F2FF。
天空只在地图倾斜时可见。深色风格建议把两个天空色都调暗。
取值超出范围或格式不对的字段不生效。
只有下表中的属性会生效。lineWidth、color、fontColor、fontFamily、opacity、iconColor 等写法不会报错,但不生效。
线的总宽 = width + 2 × strokeWidth。模板中道路线宽在 14 级约为 6 ~ 14,描边宽度常用 0 ~ 2。
线只写 fillColor 时,描边色会跟着变成填充色,描边就看不出来了;面只写 fillColor 时,边框保持模板颜色。所以 fillColor 和 strokeColor 建议成对写。
3D 面能改颜色、亮度、饱和度和显隐,高度不能修改;箭头只能改颜色。
面的 lightness / saturation 只调填充色,线的同时调填充色和描边色,3D 面的顶面和侧面分别调整(保留两者的明暗差)。
文字描边色一般取与陆地相近的颜色(浅色地图用白色,深色地图用近黑色)。改字色时一起检查描边色,保证文字清楚。
只有 false 会隐藏;true 用来恢复上级规则隐藏的内容。
label.visible: false 只隐藏文字,icon.visible: false 只隐藏图标。
geometry.visible: false 隐藏整个要素,文字和图标一起隐藏,所以做不到「只留文字、隐藏形状」。
国界线和省界线:administrative.country、administrative.province 的形状只能控制显隐,颜色、宽度等写了也不生效;隐藏时只隐藏线,国名、省名保留。中国国界线(含未定国界、南海范围线)始终显示,不能隐藏。
任何属性(颜色、数值、visible)都可以写成以 z<整数> 为键的对象,让取值随缩放级别变化。级别越大,地图越近(街道细节)。
[{"id": "road.highway","geometry": {"fillColor": { "z6": "#2F6BC4", "z12": "#3B7FDB", "z16": "#4B90EA" },"width": { "z6": 1, "z10": 4, "z14": 10, "z17": 16 },"strokeColor": "#0E2442","strokeWidth": 1}},{ "id": "poi", "label": { "visible": { "z3": false, "z15": true } }, "icon": { "visible": { "z3": false, "z15": true } } }]
取「不超过当前级别的最大键」的值:上例 width 在 12 级取 4,在 15 级取 10。当前级别小于所有键时,取最小键的值。
按阶梯取值,不做平滑过渡;想变化得平缓就多写几个键。
所有键都必须是 z 加整数(如 z7),否则整个对象不生效;不支持数组写法。
第二条规则让兴趣点在 15 级之前隐藏,15 级起显示。
多条规则作用于同一个要素时:
你的规则总是优先于基础模板。
越具体的规则优先级越高:按 id 的段数比较,all < road < road.highway < road.overlay.lane_line,与规则在数组里的顺序无关。
具体程度相同时,数组中靠后的规则覆盖靠前的。
按属性合并:具体规则只覆盖它写出的属性,没写的属性沿用上级规则。
按级别取值的对象整体替换,不会按级别键逐个合并。
visible 也会继承:上级写了 false,下级要写 true 才能恢复。例如对 road 写 label.visible: false,再对 road.highway 写 label.visible: true,就只保留高速公路的路名。
室内图只受 all 和 indoor 下的规则影响。
示例:
[{ "id": "all", "geometry": { "saturation": -40 } },{ "id": "road", "label": { "fillColor": "#333333", "strokeColor": "#FFFFFF" } },{ "id": "road.highway", "geometry": { "fillColor": "#E8590C" }, "label": { "fillColor": "#000000" } }]
高速公路最终:文字颜色 #000000(自身规则),文字描边 #FFFFFF(继承 road),形状颜色是 #E8590C 再降低 40 饱和度(继承 all)。所以 all 上的 lightness / saturation 适合在没写具体颜色时整体调色。
形状、文字、图标是分开的三部分:geometry 只管面、线、3D 面和箭头,label 管文字,icon 管图标。例如兴趣点本身是图标和文字,只写 poi 的 geometry 改不到它们;在 all 上整体降饱和时,要把 geometry、label、icon 三处的 saturation 都写上。
改颜色、宽度写到具体分类上,不要写在大的上级上。 road 还包含车道线、人行横道、护栏等路面细节,改道路颜色请分别写 road.highway、road.expressway、road.national、road.provincial、road.county、road.local 六类;background 还包含停车场、球场、树木等装饰。
上级适合统一改文字、图标和显隐,例如对 poi 统一改字色、对 transit 整体隐藏。
常用入口:陆地底色写 background.landform.land;水系写 background.landform.water(覆盖海洋、湖泊、河流);绿地写 background.landform.green;人工用地写 background.landuse;建筑直接写 building。
只写要素实际具有的部分:例如 poi.food 只有图标和文字,给它写 geometry 不生效。每个分类有哪些部分见《要素与模板》。
以下内容无法通过配置修改:图标图片、图标位置与避让、字体、斜体、文字背景色、3D 建筑的高度、线的端点与纹理。配置只能调整地图已有要素的外观和显隐,不能新增要素。
在编辑器里校验:「查看配置 JSON > 编辑」,粘贴后点「应用」。格式不对的地方会在下方列出,改好后再应用;应用成功后右侧地图立即显示效果。
用接口校验:把配置 POST 到 https://api.map.baidu.com/custom/v4/mapstyle?ak=你的AK,返回的 data.warnings 里会列出被忽略的字段和不存在的要素分类。
看效果再发布:配置应用到编辑器后只是草稿,确认效果后点「发布」才会对外生效。
上一篇
下一篇