百度地图开放平台

所有文档

个性化地图编辑器

更新时间: 2026/11/12 10:22

在编辑器里调出来的每个样式,背后都是一份样式配置(JSON)。平时用编辑器点选就够了;需要批量生成、精确复用,或者让 AI 帮你设计样式时,直接读写这份配置更高效。本文是配置的完整规则,开发者可以照着手写,也可以整篇交给 AI 作为生成依据。

两种配置格式
简易配置完整配置

对应编辑器

简易模式

高级模式

标识

顶层写 "mode": "simple"

不写 mode

描述方式

按「背景 / 路网 / 建筑 / 标注」等分组给几个颜色、粗细和开关

按要素分类(如 road.highway)逐条写规则,每个属性都可以按缩放级别取值

适合

快速出一套配色;让 AI 生成风格

精细调整具体要素;按级别控制显隐和粗细

规则

本文第二节

本文第三节,要素分类见《要素与模板》

简易配置可以随时在编辑器中「转为高级模式」,平台会把它展开成等效的完整配置继续编辑;转换后不能再转回简易配置。
选择建议:先用简易配置把整体风格定下来,需要单独改某一类道路、某一类兴趣点,或者按级别控制时,再转为完整配置。

配置在哪里用
场景做法

在编辑器里查看或修改

编辑器「⋮ > 查看配置 JSON」,可以复制,也可以点「编辑」粘贴新的配置后「应用」,应用前会校验

在网页中直接使用

JSAPI 的 map.setMapStyle({styleJson: 配置}),见《在 JSAPI 中使用》

推荐方式

把配置应用到编辑器里发布,用样式 ID 加载。之后修改样式不用改代码

一、通用取值约定

两种配置都遵守以下约定,写错时通常不会报错,只是那一项不生效:

  1. 颜色只写 6 位十六进制 #RRGGBB,大小写均可。不支持 #FFF、#FFFFFF80、rgb()、rgba()、颜色名。

  2. 数值写 JSON 数字,10 而不是 "10"。

  3. 显隐写 JSON 布尔值 true / false,不要写 0 / 1 或字符串。

  4. 基础模板 template 只能是已发布的基础模板,预置有 light(浅色)、dark(深色)、classic(PC 经典)。不写时用平台默认模板(浅色);写了不存在的模板会报错。

  5. 配置里只认文档列出的字段,其他字段会被忽略。

二、简易配置

简易配置用几组颜色、粗细和开关描述一套地图风格,对应编辑器的简易模式。平台会按下面的规则把它自动展开成完整配置,你不需要了解要素分类和缩放级别。适合快速出风格,也最适合让 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 外,所有字段都可以不写,没写的部分保持基础模板的外观。 只想换道路和水系颜色,就只写这两项。

顶层字段
字段类型说明

mode

string

必填,固定为 "simple"

name

string

样式名,只作标识

template

string

基础模板:light / dark / classic 等已发布的基础模板。不写用平台默认模板;写了不存在的模板会报错

background

object

背景,见下文

road

object

路网

building

object

建筑

label

object

标注(全部文字和图标)

poi / transit / administrative / indoor

object

兴趣点 / 公共交通 / 行政区划 / 室内图,只有显隐

saturation

number

整体饱和度

sky

object

天空色

version

string

可省略

简易配置里不能同时写 featureStyles。
每个分组都有 visible:写 false 隐藏这一组,写 true 或不写保持模板默认。

背景 background
字段取值作用

visible

布尔

全部背景:陆地、水系、绿地、人工用地、装饰要素,以及它们的文字和图标

land

#RRGGBB

陆地底色,包括国外区域的底面、裸地、冰川

water

#RRGGBB

海洋、湖泊、河流等全部水面;水岸边线自动比水面略亮

green

#RRGGBB

林地、草地、农田、公园等绿地;边线自动比填充略亮

landuse

#RRGGBB

人工用地:住宅区、工业区、学校、医院、商业、景区等区域面

编辑器里「人工用地」对应的就是 landuse。
路网 road
字段取值作用

visible

布尔

全部道路,含车道线、斑马线等路面细节和道路名

color

#RRGGBB

高速公路、城市快速路、国道、省道、县乡道、其他道路统一用这一个路面色

width

0.5 ~ 2

上述道路的宽度倍率,1 为模板原宽

  • 路沿(道路两侧的描边)自动取「路面色与陆地色各一半」的混合色,让道路和底图自然分开。

  • 车道线、斑马线、护栏等路面细节保持模板颜色。

建筑 building
字段取值作用

visible

布尔

全部建筑物及其文字、图标

color

#RRGGBB

全部建筑统一用这一种颜色,3D 建筑的顶面和侧面同色

标注 label

「标注」指地图上全部的文字和图标:地名、道路名、兴趣点名、站点名,以及兴趣点图标、交通站点图标、道路编号牌等。

字段取值作用

visible

布尔

全部文字和图标

textColor

#RRGGBB

全部文字用这一种颜色。模板里按类别区分的字色(如餐饮橙色、城市名红色)不再保留

iconColor

#RRGGBB

全部图标染成这一种颜色

size

0.5 ~ 2

文字字号和图标大小的倍率,两者一起缩放

  • 文字描边(文字外圈的光晕)自动取陆地色:写了 textColor,或只写了 background.land 时都会这样处理。描边色不能单独设置。

  • 图标染色保留图标原有的明暗,把色相换成 iconColor,白色图案保持白色;多色图标染色后会变成同一色相的深浅。道路编号牌这类带文字的图标也会被染色,注意和 textColor 拉开反差。

只有显隐的分组
分组控制的要素

poi

全部兴趣点,包括它们的文字、图标,以及景区、游乐园等的区域面

transit

公交、地铁、铁路、航空、轮渡的线路、站点及其文字

administrative

行政区划的边界线和地名。中国国界线(含未定国界、南海范围线)始终显示,隐藏时只隐藏省界、国外国界和地名

indoor

室内图

这几个分组只有 visible 一个字段,例如 "poi": { "visible": false }。

整体饱和度 saturation

取值 -100 ~ 100,默认 0:-100 完全去色,0 不变,100 饱和度加倍。

  • 在上面所有颜色生效之后最后应用,所以地图上看到的是调整后的颜色。

  • 作用于道路、水系、绿地等线和面、3D 建筑,以及文字和图标。面的边框、箭头、国界和省界线不受影响。

天空 sky
字段取值作用

color

#RRGGBB

天空顶部颜色;靠近地平线的底部自动取陆地色

不写时使用基础模板预设的天空色。天空只在地图倾斜时看得到,深色风格建议把天空也调暗。

注意事项
  1. 倍率超出 0.5 ~ 2、saturation 超出 -100 ~ 100 时,平台按边界值处理;在编辑器的 JSON 编辑框里应用时会直接提示错误。

  2. 格式不对的字段按没写处理,其他字段照常生效。

  3. 分组写了 visible: false 后,组内其他字段不再影响这一组的外观。例外:background.land 即使背景被隐藏,也仍然用于推导路沿、文字描边和天空底部。

  4. 所有颜色都按原样使用,平台不做对比度兜底。请自己保证反差:文字与陆地、道路与陆地、水系绿地与陆地都不要太接近。

  5. 简易配置不包含默认视野,地图打开时使用默认视角。

三、完整配置

完整配置对应编辑器的高级模式:选一个基础模板,再用 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" }
}
}

这份配置以深色模板为底,把水系改成深蓝,高速公路改成亮蓝,并统一调整了兴趣点的文字颜色。

配置结构
顶层字段
字段类型必填说明

featureStyles

array

是

规则数组。可以是空数组 [],即完全使用模板默认样式

template

string

建议写

基础模板:light / dark / classic 等已发布的基础模板。不写用平台默认模板(浅色);不存在的模板会报错

name

string

否

样式名

version

string

否

可省略,编辑器导出时为 "2.0.0"

config

object

否

天空色和默认视野,见下文

不要写 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 }
}
字段必填说明

id

是

要素分类,如 road.highway,取值见《要素与模板》;all 表示全部要素。区分大小写,同一份配置里不要重复

geometry

否

形状:面、线、3D 面、箭头的颜色、宽度与显隐

label

否

文字:颜色、描边、字号、字重与显隐

icon

否

图标:缩放、染色与显隐

  • geometry、label、icon 至少写一个,都必须是对象;规则里不要有其他字段。

  • 规则只改写它明确写出的属性,其余属性保持模板默认值。

  • 每个属性都可以写固定值,也可以按缩放级别分别取值,见第三节。

天空色与默认视野

config 与 featureStyles 平级,只决定天空外观和地图打开时的初始视角,不影响要素样式。每个字段都可以省略。

"config": {
"sky": { "topColor": "#5285E0", "bottomColor": "#E6F2FF" },
"defaultView": { "center": [116.404, 39.915], "zoom": 12, "pitch": 0, "heading": 0 }
}
字段取值说明

sky.topColor

#RRGGBB

天空顶部颜色

sky.bottomColor

#RRGGBB

天空底部(靠近地平线)颜色,远处的地面也会融入这个颜色

defaultView.center

[经度, 纬度],经度 -180 ~ 180,纬度 -85 ~ 85

初始中心点,默认 [116.404, 39.915](北京)

defaultView.zoom

1 ~ 25

初始缩放级别,默认 12

defaultView.pitch

0 ~ 89

倾斜角(度),0 为正俯视,默认 0

defaultView.heading

0 ~ 360

旋转角(度),0 为正北朝上,默认 0

  • 新建样式时,基础模板预设的天空色会带进样式;模板没有预设时默认为 #5285E0 / #E6F2FF。

  • 天空只在地图倾斜时可见。深色风格建议把两个天空色都调暗。

  • 取值超出范围或格式不对的字段不生效。

样式属性

只有下表中的属性会生效。lineWidth、color、fontColor、fontFamily、opacity、iconColor 等写法不会报错,但不生效。

geometry(形状)
属性取值线面3D 面箭头说明

fillColor

颜色

✓

✓

✓

✓

面的填充色、线体颜色、3D 面颜色(顶面和侧面同色)、箭头颜色

fillOpacity

0 ~ 1

✓

✓

填充透明度

strokeColor

颜色

✓

✓

线的描边色、面的边框色

strokeOpacity

0 ~ 1

✓

✓

描边透明度

width

≥ 0

✓

线体宽度

strokeWidth

≥ 0

✓

✓

线:单侧描边宽度,0 不画描边;面:边框宽度

widthRatio

> 0

✓

线宽倍率,乘在模板线宽上,保留模板在各级别的宽度变化

lightness

-100 ~ 100

✓

✓

✓

亮度,正数变亮、负数变暗

saturation

-100 ~ 100

✓

✓

✓

饱和度,-100 完全去色,100 饱和度加倍

visible

布尔

✓

✓

✓

写 false 隐藏

  • 线的总宽 = width + 2 × strokeWidth。模板中道路线宽在 14 级约为 6 ~ 14,描边宽度常用 0 ~ 2。

  • 线只写 fillColor 时,描边色会跟着变成填充色,描边就看不出来了;面只写 fillColor 时,边框保持模板颜色。所以 fillColor 和 strokeColor 建议成对写。

  • 3D 面能改颜色、亮度、饱和度和显隐,高度不能修改;箭头只能改颜色。

  • 面的 lightness / saturation 只调填充色,线的同时调填充色和描边色,3D 面的顶面和侧面分别调整(保留两者的明暗差)。

label(文字)
属性取值说明

fillColor

颜色

文字颜色

fillOpacity

0 ~ 1

文字透明度

strokeColor

颜色

文字描边(光晕)颜色

strokeOpacity

0 ~ 1

描边透明度

fontSize

数字

字号,模板中为 16 ~ 40,常用 22 ~ 28

fontSizeRatio

> 0

字号倍率,乘在模板字号上,结果取整

fontWeight

0 或 1

0 常规,1 加粗

lightness / saturation

-100 ~ 100

字色和描边色一起调整

visible

布尔

写 false 只隐藏文字

文字描边色一般取与陆地相近的颜色(浅色地图用白色,深色地图用近黑色)。改字色时一起检查描边色,保证文字清楚。

icon(图标)
属性取值说明

scale

> 0

缩放,1 为原始大小,模板中为 0.4 ~ 1

scaleRatio

> 0

缩放倍率,乘在模板缩放上,保留各图标原有的大小差异

tintColor

颜色

染色:保留图标原有的明暗,色相换成这个颜色,白色部分保持白色。多色图标染色后变成同一色相的深浅

lightness / saturation

-100 ~ 100

图标整体亮度 / 饱和度,在染色之后应用

visible

布尔

写 false 只隐藏图标

显隐规则
  • 只有 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 级起显示。

规则合并

多条规则作用于同一个要素时:

  1. 你的规则总是优先于基础模板。

  2. 越具体的规则优先级越高:按 id 的段数比较,all < road < road.highway < road.overlay.lane_line,与规则在数组里的顺序无关。

  3. 具体程度相同时,数组中靠后的规则覆盖靠前的。

  4. 按属性合并:具体规则只覆盖它写出的属性,没写的属性沿用上级规则。

  5. 按级别取值的对象整体替换,不会按级别键逐个合并。

  6. visible 也会继承:上级写了 false,下级要写 true 才能恢复。例如对 road 写 label.visible: false,再对 road.highway 写 label.visible: true,就只保留高速公路的路名。

  7. 室内图只受 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 不生效。每个分类有哪些部分见《要素与模板》。

限制与常见错误(也可作为 AI 输出的检查清单)

以下内容无法通过配置修改:图标图片、图标位置与避让、字体、斜体、文字背景色、3D 建筑的高度、线的端点与纹理。配置只能调整地图已有要素的外观和显隐,不能新增要素。

错误写法结果正确写法

"#F00"、"#FF000080"、"red"、"rgba(255,0,0,.5)"

颜色不生效

"#FF0000",透明度另写 "fillOpacity": 0.5

"lineWidth": 4、"color": "#FFFFFF"、"fontColor": "#FFFFFF"

不生效

"width": 4、"fillColor"、label.fillColor

"width": "10"、"visible": "false"、"visible": 0

不生效

"width": 10、"visible": false

"fontWeight": 700

效果无保证

0 或 1

"id": "Road.Highway"、"id": "highway"

规则不生效

"id": "road.highway"

在 road 上写 fillColor

车道线、人行横道等也被改色

分别写六个道路等级

线只写 fillColor

描边看不出来

同时写 strokeColor

给要素不具有的部分写样式,如 poi.food 的 geometry

不生效

先查《要素与模板》

geometry.visible: false 却想保留文字

文字一起隐藏

分别用 label、icon 的 visible

给国界线、省界线改颜色

不生效

只能控制显隐

{ "z7": "#FFFFFF", "color": "#000000" }、[{ "zoom": 7, "value": "#FFFFFF" }]

分级不生效

{ "z7": "#FFFFFF" }

sky、defaultView 写在顶层

不生效

写在 config 下

缺少 featureStyles 或写成对象

配置无效

写成数组,可以为空

四、校验与调试
  • 在编辑器里校验:「查看配置 JSON > 编辑」,粘贴后点「应用」。格式不对的地方会在下方列出,改好后再应用;应用成功后右侧地图立即显示效果。

  • 用接口校验:把配置 POST 到 https://api.map.baidu.com/custom/v4/mapstyle?ak=你的AK,返回的 data.warnings 里会列出被忽略的字段和不存在的要素分类。

  • 看效果再发布:配置应用到编辑器后只是草稿,确认效果后点「发布」才会对外生效。

上一篇

升级指南

下一篇

要素与模板
本篇文章对您是否有帮助?