云端地图样式设置的 JSON 参考

请选择平台： Android iOS JavaScript 网络服务

借助云端地图样式设置的 JSON 架构，您可以使用 JSON 自定义地图，就像通过样式编辑器界面进行自定义一样。本文档介绍了 JSON 架构以及如何进行 JSON 样式声明。

下载 JSON 架构

如需了解如何在样式编辑器中使用 JSON 编辑地图样式，或如何 导入和导出地图样式，请参阅 使用 JSON 设置云端地图样式设置。

查看 JSON 样式声明示例

以下 JSON 样式声明设置了背景颜色，然后定义了地图注点、公园、水体地图项的样式，并隐藏了餐饮场所的标签。


{
  "variant": "light",
  "styles": [
    {
      "id": "natural.land",
      "geometry": {
        "fillColor": "#f7e3f7"
      }
    },
    {
      "id": "natural.water",
      "geometry": {
        "fillColor": "#d4b2ff"
      },
      "label": {
        "textFillColor": "#3d2163",
        "textStrokeColor": "#f0e1ff"
      }
    },
    {
      "id": "pointOfInterest",
      "label": {
        "pinFillColor": "#e0349a",
        "textFillColor": "#a11e6e",
        "textStrokeColor": "#ffd9f0"
      }
    },
    {
      "id": "pointOfInterest.emergency.hospital",
      "geometry": {
        "fillColor": "#ffe3e3"
      }
    },
    {
      "id": "pointOfInterest.foodAndDrink",
      "label": {
        "visible": false
      }
    },
    {
      "id": "pointOfInterest.recreation.park",
      "geometry": {
        "fillColor": "#f9b9d2"
      }
    }
  ]
}

JSON 对象

JSON 样式声明包含一个顶层对象和一个样式规则数组。

  • 顶层属性 （可选）- 全局样式设置，例如 backgroundColor 和 variant。
  • styles - 样式规则对象数组，可以包含以下内容：
    • id - 为此样式修改选择的地图项 （例如 pointOfInterest.recreation.park）。
    • geometry （可选）- 地图项的几何元素以及要应用的样式规则（例如 fillColor）。
    • label （可选）- 地图项的文本或图钉标签以及要应用的样式规则（例如 textStrokeColor）。

顶层属性

下表中的属性适用于整个地图样式。

属性 类型 说明 示例

backgroundColor

 字符串 使用 #RRGGBB 十六进制 字符串自定义地图应用的背景颜色。此设置不支持更改不透明度。 "#002211"

variant

"light"|"dark" 指定浅色模式或深色模式。如果未指定，则默认值为“light”。 "light"

monochrome

布尔值 如需启用单色模式，请使用 true 来显示地图的灰色版本。

true

metadata

对象 样式定义中包含的任意键值数据。您可以使用 此字段来包含与样式相关的非样式内容。此 数据不会发送给地图客户端，例如 Maps JavaScript SDK。

{"author": "me", "date": "2026-04-27"}

样式规则对象

本部分介绍了用于定义 styles 数组中的样式规则对象的属性，以自定义地图项。每个样式规则对象都必须包含以下内容：

  • id 属性。
  • geometry 或 label 元素，并定义了关联的样式器属性。

id（地图项）

id 属性用于指定要设置样式的地图项。属性名称是样式编辑器中地图项名称的驼峰式版本。

地图项构成类别树。如果指定父级地图项类型， 例如 pointOfInterest，则您为父地图项指定的所有样式均会应用到其所有子地图项，例如 pointOfInterest.retail 和 pointOfInterest.lodging。 如需了解详情，请参阅地图项层次结构。

可用 id 属性列表

可用的 id 属性如下所示：

  • pointOfInterest
  • pointOfInterest.emergency
  • pointOfInterest.emergency.fire
  • pointOfInterest.emergency.hospital
  • pointOfInterest.emergency.pharmacy
  • pointOfInterest.emergency.police
  • pointOfInterest.entertainment
  • pointOfInterest.entertainment.arts
  • pointOfInterest.entertainment.casino
  • pointOfInterest.entertainment.cinema
  • pointOfInterest.entertainment.historic
  • pointOfInterest.entertainment.museum
  • pointOfInterest.entertainment.themePark
  • pointOfInterest.entertainment.touristAttraction
  • pointOfInterest.foodAndDrink
  • pointOfInterest.foodAndDrink.bar
  • pointOfInterest.foodAndDrink.cafe
  • pointOfInterest.foodAndDrink.restaurant
  • pointOfInterest.foodAndDrink.winery
  • pointOfInterest.landmark
  • pointOfInterest.lodging
  • pointOfInterest.recreation
  • pointOfInterest.recreation.beach
  • pointOfInterest.recreation.boating
  • pointOfInterest.recreation.fishing
  • pointOfInterest.recreation.golfCourse
  • pointOfInterest.recreation.hotSpring
  • pointOfInterest.recreation.natureReserve
  • pointOfInterest.recreation.park
  • pointOfInterest.recreation.peak
  • pointOfInterest.recreation.sportsComplex
  • pointOfInterest.recreation.sportsField
  • pointOfInterest.recreation.trailhead
  • pointOfInterest.recreation.zoo
  • pointOfInterest.retail
  • pointOfInterest.retail.grocery
  • pointOfInterest.retail.shopping
  • pointOfInterest.service
  • pointOfInterest.service.atm
  • pointOfInterest.service.bank
  • pointOfInterest.service.carRental
  • pointOfInterest.service.evCharging
  • pointOfInterest.service.gasStation
  • pointOfInterest.service.parkingLot
  • pointOfInterest.service.postOffice
  • pointOfInterest.service.restStop
  • pointOfInterest.service.restroom
  • pointOfInterest.transit
  • pointOfInterest.transit.airport
  • pointOfInterest.other
  • pointOfInterest.other.bridge
  • pointOfInterest.other.cemetery
  • pointOfInterest.other.government
  • pointOfInterest.other.library
  • pointOfInterest.other.military
  • pointOfInterest.other.placeOfWorship
  • pointOfInterest.other.school
  • pointOfInterest.other.townSquare
  • political
  • political.countryOrRegion
  • political.border
  • political.reservation
  • political.stateOrProvince
  • political.city
  • political.sublocality
  • political.neighborhood
  • political.landParcel
  • infrastructure
  • infrastructure.building
  • infrastructure.building.commercial
  • infrastructure.businessCorridor
  • infrastructure.roadNetwork
  • infrastructure.roadNetwork.noTraffic
  • infrastructure.roadNetwork.noTraffic.pedestrianMall
  • infrastructure.roadNetwork.noTraffic.trail
  • infrastructure.roadNetwork.noTraffic.trail.paved
  • infrastructure.roadNetwork.noTraffic.trail.unpaved
  • infrastructure.roadNetwork.parkingAisle
  • infrastructure.roadNetwork.ramp
  • infrastructure.roadNetwork.road
  • infrastructure.roadNetwork.road.arterial
  • infrastructure.roadNetwork.road.highway
  • infrastructure.roadNetwork.road.local
  • infrastructure.roadNetwork.road.noOutlet
  • infrastructure.roadNetwork.roadShield
  • infrastructure.roadNetwork.roadSign
  • infrastructure.roadNetwork.roadDetail
  • infrastructure.roadNetwork.roadDetail.surface
  • infrastructure.roadNetwork.roadDetail.crosswalk
  • infrastructure.roadNetwork.roadDetail.sidewalk
  • infrastructure.roadNetwork.roadDetail.intersection
  • infrastructure.railwayTrack
  • infrastructure.railwayTrack.commercial
  • infrastructure.railwayTrack.commuter
  • infrastructure.transitStation
  • infrastructure.transitStation.bicycleShare
  • infrastructure.transitStation.busStation
  • infrastructure.transitStation.ferryTerminal
  • infrastructure.transitStation.funicularStation
  • infrastructure.transitStation.gondolaStation
  • infrastructure.transitStation.monorail
  • infrastructure.transitStation.railStation
  • infrastructure.transitStation.railStation.subwayStation
  • infrastructure.transitStation.railStation.tramStation
  • infrastructure.urbanArea
  • natural
  • natural.continent
  • natural.archipelago
  • natural.island
  • natural.land
  • natural.land.landCover
  • natural.land.landCover.crops
  • natural.land.landCover.dryCrops
  • natural.land.landCover.forest
  • natural.land.landCover.ice
  • natural.land.landCover.sand
  • natural.land.landCover.shrub
  • natural.land.landCover.tundra
  • natural.water
  • natural.water.ocean
  • natural.water.lake
  • natural.water.river
  • natural.water.other
  • natural.base

元素

元素是地图项的细分。例如，在地图上，道路不仅包含图形线条（geometry），还包括指示其名称的文本（label）。

可用元素如下所示（但请注意，特定地图项可能不支持任何元素，也可能支持部分或全部元素）：

  • geometry：选择指定地图项的所有几何元素（例如多边形、多段线）。
  • label：选择指定地图项的所有标签元素（例如文本、图钉）。

样式器

样式器用于为地图项的每个元素定义样式规则。

例如，对于建筑物平面图，您可以按如下方式为每个元素设置样式：

建筑物的 geometry 样式器示例 建筑物的 label 样式器示例
是否在地图上隐藏或显示建筑物平面图多边形。 是否隐藏或显示建筑物标签。
多边形填充颜色和不透明度。 文本填充颜色和不透明度。
边框颜色、不透明度和宽度。 文本描边颜色和不透明度。

本部分介绍了可用于 geometry 和 label 元素的不同样式选项。

geometry 样式器

下表列出了所有可用的几何样式器。

样式器 类型 说明

visible

布尔值 如需隐藏地图项的多边形或多段线，请设置为 false。

fillColor

字符串 使用 RGB 十六进制字符串自定义多边形或多段线的颜色。

fillOpacity

float 自定义多边形或多段线的不透明度，其中 0 表示透明，1 表示不透明。

strokeColor

字符串 使用 RGB 十六进制字符串自定义轮廓的颜色。

strokeOpacity

float 自定义轮廓的不透明度，其中 0 表示透明，1 表示不透明。

strokeWeight

float 自定义轮廓的粗细，范围为 0 到 8。

如需了解详情，请参阅 多边形和多段线。

label 样式器

下表列出了所有可用的标签样式器。

样式器 类型 说明

visible

布尔值 如需隐藏地图项的标签，请设置为 false。

textFillColor

字符串 使用 RGB 十六进制字符串自定义文本标签的颜色。

textFillOpacity

float 自定义文本标签的不透明度，其中 0 表示透明，1 表示不透明。

textStrokeColor

字符串 使用 RGB 十六进制字符串自定义轮廓的颜色。

textStrokeOpacity

float 自定义轮廓的不透明度，其中 0 表示透明，1 表示不透明。

textStrokeWeight

float 自定义轮廓的粗细，范围为 0 到 8。

pinFillColor

字符串 使用 RGB 十六进制字符串自定义图钉颜色。

pinGlyphColor

字符串 使用 RGB 十六进制字符串自定义图钉内字形（图标）的颜色。

pinOutlineColor

字符串 使用 RGB 十六进制字符串自定义图钉轮廓的颜色。

如需了解详情，请参阅 图标和文本标签。

Keyzoom

您可以为所有 Keyzoom 级别设置单个地图项样式，也可以为不同的 Keyzoom 级别指定不同的样式。如果您仅提供一种样式，则该样式将用于从 z0 开始的所有 Keyzoom 级别。如果您为不同的 Keyzoom 级别提供样式，则该样式将从该缩放级别开始应用，直到您定义的下一个缩放级别为止。

如需为样式设置 Keyzoom 级别，请在样式器属性中定义 Keyzoom 级别（从 z0 到 z22），然后进行样式器自定义。

在以下示例中，水的颜色在 keyzoom 级别 0-5 时为黑色，在 keyzoom 级别 6-11 时为深灰色，在 keyzoom 级别 12 及更高时为浅灰色。

{
  "id": "natural.water",
  "geometry": {
    "fillColor": {
      "z0": "#000000",
      "z6": "#666666",
      "z12": "#cccccc"
    }
  }
}

如需了解详情，请参阅样式缩放级别。

限制

您可以使用 JSON 为 Google Cloud 控制台中的几乎所有内容设置样式，但地图设置 菜单中的以下选项除外：

这些地图级选项需要重新提取图块数据才能正确呈现，这对于某些应用场景来说可能并不理想。

对于这些选项，您必须在 地图设置 菜单中选择您的偏好设置。

由于这些选项未包含在导出的样式中，因此在导入样式时，必须在 Google Cloud 控制台中重新选择这些选项。