مرجع JSON برای طراحی نقشه های مبتنی بر ابر

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت، وب سرویس

طرحواره 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 سفارشی کنید. این تنظیم از تغییرات در میزان شفافیت پشتیبانی نمی‌کند. «#۰۰۲۲۱۱»

variant

 «روشن» | «تاریک» حالت روشن یا تاریک را مشخص کنید. اگر مشخص نشود، پیش‌فرض «روشن» است. «نور»

monochrome

 بولی برای فعال کردن حالت تک رنگ، برای نمایش نسخه خاکستری نقشه از true استفاده کنید.

true

metadata

 شیء داده‌های کلید-مقدار دلخواه که در تعریف استایل گنجانده شده‌اند. می‌توانید از این فیلد برای درج محتوای غیرمرتبط با استایل در مورد استایل استفاده کنید. این داده‌ها برای کلاینت‌های نقشه مانند Maps JavaScript SDK ارسال نمی‌شوند.

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

اشیاء قانون سبک

این بخش ویژگی‌هایی را شرح می‌دهد که اشیاء قانون سبک را در آرایه styles تعریف می‌کنند تا ویژگی‌های نقشه را سفارشی کنند. هر شیء قانون سبک باید شامل موارد زیر باشد:

  • ویژگی id .
  • عنصر geometry یا label با ویژگی‌های استایل‌دهنده‌ی مرتبط تعریف شده.

id (ویژگی نقشه)

ویژگی id عارضه نقشه را برای استایل‌دهی مشخص می‌کند. نام‌های ویژگی، نسخه‌های camelcase نام‌های عارضه نقشه در ویرایشگر استایل هستند.

عوارض نقشه یک درخت دسته‌بندی را تشکیل می‌دهند. اگر نوع عارضه والد، مانند 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

 شناور میزان شفافیت چندضلعی یا چندخطی را تنظیم کنید، که در آن ۰ شفاف و ۱ مات است.

strokeColor

 رشته رنگ طرح کلی را با یک رشته هگز RGB سفارشی کنید.

strokeOpacity

 شناور میزان شفافیت طرح کلی را سفارشی کنید، که در آن ۰ شفاف و ۱ مات است.

strokeWeight

 شناور ضخامت طرح کلی را از محدوده ۰ تا ۸ سفارشی کنید.

برای اطلاعات بیشتر، به چندضلعی‌ها و چندخطی‌ها مراجعه کنید.

استایل دهنده‌های label

جدول زیر لیست تمام استایل‌دهنده‌های برچسب موجود را نشان می‌دهد.

استایلر نوع توضیحات

visible

 بولی برای پنهان کردن برچسب یک عارضه نقشه، آن را روی false تنظیم کنید.

textFillColor

 رشته رنگ برچسب متن را با یک رشته هگز RGB سفارشی کنید.

textFillOpacity

 شناور میزان شفافیت برچسب متن را سفارشی کنید، که در آن ۰ شفاف و ۱ مات است.

textStrokeColor

 رشته رنگ طرح کلی را با یک رشته هگز RGB سفارشی کنید.

textStrokeOpacity

 شناور میزان شفافیت طرح کلی را سفارشی کنید، که در آن ۰ شفاف و ۱ مات است.

textStrokeWeight

 شناور ضخامت طرح کلی را از محدوده ۰ تا ۸ سفارشی کنید.

pinFillColor

 رشته رنگ پین را با یک رشته هگز RGB سفارشی کنید.

pinGlyphColor

 رشته رنگ گلیف (آیکون) درون یک پین را با یک رشته هگز RGB سفارشی کنید.

pinOutlineColor

 رشته رنگ طرح کلی پین را با یک رشته هگز RGB سفارشی کنید.

برای اطلاعات بیشتر، به بخش نمادها و برچسب‌های متنی مراجعه کنید.

کی‌زوم‌ها

شما می‌توانید برای یک ویژگی، یک سبک واحد برای تمام سطوح بزرگنمایی کلید تنظیم کنید یا سبک‌های مختلفی را برای سطوح مختلف بزرگنمایی کلید مشخص کنید. اگر فقط یک سبک ارائه دهید، برای تمام سطوح بزرگنمایی کلید از z0 استفاده خواهد شد. اگر سبک‌هایی را برای سطوح مختلف بزرگنمایی کلید ارائه دهید، آن سبک از آن سطح بزرگنمایی تا سطح بزرگنمایی بعدی که تعریف کرده‌اید اعمال می‌شود.

برای تنظیم سطح بزرگنمایی کلید برای یک استایل، در ویژگی styler، سطح بزرگنمایی کلید را از 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 انتخاب شوند.