Lightdash Map 图表完全指南在 Charts-as-Code 中配置 scatter、area 与 heatmap 地图可视化【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash本篇指南以 map-chart-reference.md 为骨架系统讲解如何在 Lightdash 的图表即代码charts-as-code体系中用 YAML 定义地图可视化三种位置类型散点 / 区域 / 热力图、四种地图底图USA / world / europe / custom、全部配置属性与四套可直接套用的完整示例。读完你可以把经纬度、州名/国名、自定义 GeoJSON 区域三类地理数据以代码方式一键部署成交互式地图图表并理解其背后的 Leaflet 渲染与 GeoJSON 代理机制。地图图表概览三种位置类型与四种地图区域地图图表type: map通过locationType决定地理位置数据如何呈现通过mapType决定使用哪一套预置地理边界。Location Type说明最佳适用场景scatter在经纬度坐标上绘制点气泡门店位置、客户地址area区域按指标着色choropleth 等值区域图按州/国家的销售额对比heatmap点密度热力可视化活动热点分布Map Type说明位置匹配方式USA美国地图州名或州代码world世界地图国家名或 ISO 代码europe欧洲国家地图国家名或 ISO 代码custom自定义 GeoJSON 区域自定义属性键需要说明的是从仓库中的 JSON Schema 与 TypeScript 类型看locationType实际上还支持第 4 种取值hexbinH3 六边形分箱聚合见 savedCharts.ts 中的MapChartType枚举mapType四取值与文档一致USA/world/europe/custom。本文以参考文档为准详细介绍前三种并在后文对hexbin作补充说明。所有地图配置都写在 YAML 的chartConfig.config下与metricQuery、spaceSlug等顶层字段配合构成完整的图表文件。Schema 层面的权威定义位于 chart-as-code-1.0.json 的$defs/MapChart、$defs/MapChartConfig、$defs/MapChartLocation与$defs/MapChartType中编写 YAML 时遇到属性疑问可以随时回查。核心配置属性三种位置类型的分工Scatter 散点图必须指定经纬度字段散点图在latitudeFieldId与longitudeFieldId指定的坐标上绘制圆形标记可选sizeFieldId控制气泡大小、valueFieldId控制着色强度config: latitudeFieldId: stores_latitude locationType: scatter longitudeFieldId: stores_longitude sizeFieldId: metric_for_bubble_size # 可选气泡大小 valueFieldId: metric_for_color # 可选着色从实现上看散点数据会被聚合成ScatterPoint列表见 useLeafletMapConfig.ts前端用 react-leaflet 的CircleMarker渲染气泡半径由minBubbleSize/maxBubbleSize限定并使用scaleSqrt平方根缩放见 SimpleMap/index.tsx因此值差异大时气泡面积不会被过度放大。Area 区域图区域名与 GeoJSON 属性匹配区域图将locationFieldId对应的值如州名与 GeoJSON 中geoJsonPropertyKey指定的属性做精确匹配再按valueFieldId的指标着色config: geoJsonPropertyKey: name locationFieldId: orders_state locationType: area valueFieldId: orders_total_sales匹配是大小写敏感的详见文末常见问题这是区域图最常见的坑。仓库内置的us-states.geojson自带name、code、density三个属性见 geojson/README.md所以美国地图直接用geoJsonPropertyKey: name即可。Heatmap 热力图密度叠加层热力图同样需要经纬度字段并通过heatmapConfig子对象控制热点的渲染效果config: heatmapConfig: blur: 15 # 模糊程度 (0-30) opacity: 0.6 # 叠加层透明度 (0.1-1) radius: 25 # 热力点半径 (1-50) latitudeFieldId: events_latitude locationType: heatmap longitudeFieldId: events_longitude valueFieldId: metric_for_intensity # 可选强度前端HeatmapLayer.tsx对这三个参数提供了默认值radius: 25、blur: 10见 HeatmapLayer.tsx参考文档示例中的blur: 15是在默认值之上的加强模糊。热力图能承载远多于散点图的数据量见最佳实践一节且不要求每个点都有对应指标值。自定义 GeoJSONcustom 地图区域当内置的 USA / world / europe 无法覆盖业务区域如邮编、销售分区、自定义行政边界时使用mapType: custom并指定customGeoJsonUrlconfig: customGeoJsonUrl: https://example.com/regions.geojson geoJsonPropertyKey: postal_code # GeoJSON 中用于匹配的属性 locationFieldId: orders_zip_code # 数据字段需与 GeoJSON 属性值一致 locationType: area mapType: custom valueFieldId: orders_total_sales从源码看自定义 GeoJSON 的加载路径有两类见 useLeafletMapConfig.ts外部 URLhttp:///https://开头会先经过后端代理/api/v1/geojson-proxy?url...再取回避免浏览器跨域问题相对路径直接按相对路径加载可指向自托管资源。后端代理 geoJsonProxyController.ts 使用secureFetch做了安全限制仅允许 HTTPS、拒绝访问内网/私有地址、不允许重定向、单文件上限 10MB、超时 30 秒。因此自定义 GeoJSON 的 URL 必须是公网可访问的合法 HTTPS 地址。另外无论内置还是自定义 GeoJSON前端在加载后都会做归一化处理见 SimpleMap/index.tsx若数据是 TopoJSONtype: Topology会先通过topojson-client转换成 GeoJSON若 Feature 缺少name属性会自动用第一个属性键的值补齐保证区域匹配有统一入口。这就是为什么usa内置边界使用 TopoJSON 格式也能无缝工作。视觉设置配色、底图与透明度config: backgroundColor: #ffffff colorOverrides: # 按区域覆盖颜色区域图 California: #ff0000 Texas: #00ff00 colorRange: - #fee2e2 # 低值端支持 2-5 个颜色 - #dc2626 # 高值端 dataLayerOpacity: 0.8 # 数据层透明度 (0-1) noDataColor: #e5e7eb # 区域图无匹配数据的区域颜色 showLegend: true tileBackground: light # none, openstreetmap, light, dark, satellite几点来自实现层的说明colorRange支持 2 到多个十六进制颜色前端通过 createMultiColorScale 构造连续色标数值会先被钳制到数据 min/max 区间再归一化插值tileBackground的完整取值在 Schema 的MapTileBackground中为none/openstreetmap/light/dark/satellite/voyagervoyager 为仓库中新加入的 CARTO 航行者底图各取值对应的瓦片服务可在 useLeafletMapConfig.ts 的getTileConfig中确认卫星图走 Esri World Imagerylight/dark/voyager 走 CARTO 底图服务openstreetmap 走 OSM 官方瓦片Schema 中还定义了darkModeTileBackground用于单独指定暗色主题下的底图未设置时自动使用暗色默认值。Tooltip 设置字段可见性与自定义标签通过fieldConfig以字段 ID 为键控制 tooltip 中展示哪些字段以及显示名称config: fieldConfig: stores_revenue: visible: false # 从 tooltip 中隐藏 stores_store_name: label: Store # 自定义显示标签 visible: true对应的MapFieldConfig类型在 savedCharts.ts 中只有两个可选属性visible是否在 tooltip 中显示与label自定义标签。tooltip 内容在前端由TooltipFieldInfo逐字段拼装隐藏字段不会出现在悬浮卡片中。视图设置初始中心点、缩放与视口记忆config: defaultCenterLat: 39.8283 defaultCenterLon: -98.5795 defaultZoom: 4 saveMapExtent: truesaveMapExtent决定保存图表后是否保留用户缩放/平移过的视口。底层逻辑见 useLeafletMapConfig.ts为当defaultCenterLat与defaultCenterLon同时存在时使用这两个值作为中心点否则退回getMapCenter(mapType)的内置默认中心defaultZoom未设置时退回getMapZoom(mapType)的内置默认缩放。各地图区域的内置默认值如下源码可查证Map Type默认中心 (lat, lng)默认缩放USA[39.8283, -98.5795]4europe[54.526, 15.2551]4world[20, 0]2完整示例一门店位置散点图ScatterchartConfig: config: colorRange: - #dbeafe - #1e40af defaultCenterLat: 39.8283 defaultCenterLon: -98.5795 defaultZoom: 4 latitudeFieldId: stores_latitude locationType: scatter longitudeFieldId: stores_longitude mapType: USA maxBubbleSize: 40 minBubbleSize: 8 showLegend: true sizeFieldId: stores_total_revenue tileBackground: light type: map contentType: chart metricQuery: dimensions: - stores_store_name - stores_city exploreName: stores limit: 500 metrics: - stores_total_revenue name: Store Locations slug: store-locations spaceSlug: sales/maps tableName: stores version: 1要点拆解metricQuery中把stores_store_name、stores_city作为维度、stores_total_revenue作为指标取回供 tooltip 与气泡大小使用limit: 500符合散点图 500-1000 点的性能建议minBubbleSize: 8/maxBubbleSize: 40限定气泡半径区间spaceSlug: sales/maps表示嵌套空间即sales空间下的maps子空间斜杠表示层级详见 SKILL.md。完整示例二按州销售额着色ChoroplethchartConfig: config: colorRange: - #f0f9ff - #2563eb geoJsonPropertyKey: name locationFieldId: orders_state locationType: area mapType: USA noDataColor: #f3f4f6 showLegend: true tileBackground: none valueFieldId: orders_total_sales type: map contentType: chart metricQuery: dimensions: - orders_state exploreName: orders limit: 50 metrics: - orders_total_sales name: Sales by State slug: sales-by-state spaceSlug: sales/maps tableName: orders version: 1要点拆解orders_state的值如 California必须与内置美国地图 GeoJSON 中name属性的值逐字一致tileBackground: none隐藏底图瓦片只显示区域着色适合纯数据聚焦的等值区域图noDataColor用于无匹配数据区域避免出现空白州误导。完整示例三事件密度热力图HeatmapchartConfig: config: colorRange: - #fef9c3 - #f59e0b - #dc2626 defaultCenterLat: 40.7128 defaultCenterLon: -74.0060 defaultZoom: 11 heatmapConfig: blur: 15 opacity: 0.6 radius: 25 latitudeFieldId: events_latitude locationType: heatmap longitudeFieldId: events_longitude showLegend: true tileBackground: dark type: map contentType: chart metricQuery: dimensions: - events_latitude - events_longitude exploreName: events limit: 5000 metrics: [] name: Event Density slug: event-density spaceSlug: analytics tableName: events version: 1要点拆解热力图不需要指标metrics: []密度本身由点的数量体现因此metricQuery.limit可以放到 5000defaultZoom: 11配合纽约市中心的经纬度让初始视口聚焦到城区尺度tileBackground: dark在深色底图上展示暖色热力更醒目注意当未设置valueFieldId时图例不会显示无意义的 1-1 数值区间实现层在 useLeafletMapConfig.ts 做了显式处理。完整示例四自定义 GeoJSON 邮编区域CustomchartConfig: config: colorRange: - #e0f2fe - #0369a1 customGeoJsonUrl: https://example.com/zip-codes.geojson geoJsonPropertyKey: ZCTA5CE10 locationFieldId: orders_zip_code locationType: area mapType: custom noDataColor: #f3f4f6 showLegend: true tileBackground: light valueFieldId: orders_total_sales type: map contentType: chart metricQuery: dimensions: - orders_zip_code exploreName: orders limit: 500 metrics: - orders_total_sales name: Sales by Zip Code slug: sales-by-zip spaceSlug: sales/maps tableName: orders version: 1要点拆解geoJsonPropertyKey: ZCTA5CE10对应美国人口普查邮编区划 GeoJSON 中的属性键orders_zip_code中的邮编字符串必须与 GeoJSON 中该属性的值逐字符匹配该 URL 需要公网 HTTPS 可达见自定义 GeoJSON一节的代理限制。数据要求与匹配规则散点图与热力图纬度字段数值范围 -90 到 90经度字段数值范围 -180 到 180可选用于着色或定径的指标字段。区域图Choropleth位置字段需匹配 GeoJSON 属性USA 地图州名如 California、Texas世界地图国家名或 ISO 3166-1 alpha-3 代码如 USA、GBR欧洲地图国家名或 ISO 代码自定义地图与customGeoJsonUrl中geoJsonPropertyKey属性一致的值用于区域着色的指标字段地址数据必须先经过地理编码geocoding转换为区域标识符再进入地图。内置 GeoJSON 属性键速查Map Type属性键示例值USAnameCalifornia, TexasworldnameUnited States, FranceworldISO3166-1-Alpha-3USA, FRAeuropenameGermany, Francecustom用户自定义匹配你的 GeoJSON 属性内置的us-states.geojson还额外提供code两位州代码与density属性可作其他匹配用途见 geojson/README.md。全部配置属性速查表下表汇总了参考文档与 chart-as-code-1.0.json$defs/MapChart中的全部属性属性类型适用范围说明locationTypescatter|area|heatmap另有hexbinAll位置数据的展示方式mapTypeUSA|world|europe|customAll预定义地图区域latitudeFieldIdstringscatter, heatmap纬度字段longitudeFieldIdstringscatter, heatmap经度字段locationFieldIdstringarea与 GeoJSON 属性匹配的位置字段geoJsonPropertyKeystringarea用于匹配的 GeoJSON 属性键customGeoJsonUrlstringarea (custom)自定义 GeoJSON 文件 URLvalueFieldIdstringAll颜色强度字段sizeFieldIdstringscatter气泡大小字段minBubbleSizenumberscatter最小气泡尺寸maxBubbleSizenumberscatter最大气泡尺寸colorRangestring[]All渐变色2-5 个十六进制值colorOverridesRecordarea按区域覆盖颜色noDataColorstringarea无数据区域颜色backgroundColorstringAll地图背景色tileBackgroundnone|openstreetmap|light|dark|satellite另有voyagerAll底图瓦片图层darkModeTileBackground同tileBackgroundAll暗色模式底图仓库新增dataLayerOpacitynumberAll数据层透明度0-1showLegendbooleanAll显示/隐藏图例heatmapConfig.radiusnumberheatmap热力点半径1-50heatmapConfig.blurnumberheatmap模糊量0-30heatmapConfig.opacitynumberheatmap热力层透明度0.1-1fieldConfigRecordAlltooltip 字段可见性与标签defaultZoomnumberAll初始缩放级别defaultCenterLatnumberAll初始中心纬度defaultCenterLonnumberAll初始中心经度saveMapExtentbooleanAll保存时保留缩放/平移状态补充hexbin 六边形分箱Schema 中的第四种位置类型当前参考文档聚焦 scatter / area / heatmap 三种类型但仓库的 savedCharts.ts 与 Schema 已为locationType: hexbin定义了完整的hexbinConfig配置对象sizingModedynamic分辨率随缩放级别变化默认或fixed固定 H3 分辨率0-15fixedResolution仅在fixed模式下生效的 H3 分辨率valueBasiscount按点数量着色默认或field按valueFieldId聚合值着色aggregationvalueBasis: field时使用的聚合方式sum/avg/min/max默认sumopacity六边形多边形透明度0.1-1showEmptyBins/emptyBinColor是否在可见区域内渲染空分箱轮廓及其填充色。实现上六边形图层在 SimpleMap/hexbin/HexbinLayer.tsx 中按需懒加载最大支持 50,000 个点MAX_HEXBIN_POINTS见 hexbinUtils.ts点过多时会截断取前 N 个。如果你需要处理超大规模点位hexbin 是值得尝试的方向。最佳实践如何选择位置类型Scatter坐标精确、关注单个位置、需要气泡大小编码时使用Area跨区域指标对比、行政区划分析如州、国家维度时使用Heatmap需要表达密度模式、大量点重叠时使用。性能建议Scatter建议控制在 500-1000 点Heatmap可承载 5000 点Area受区域数量限制通常没有问题Hexbin上限约 50,000 点实现层截断阈值。配色原则顺序色阶低到高同色相由浅到深colorRange: [#f0f9ff, #0284c7]发散色阶负到正两种颜色经中性色过渡colorRange: [#dc2626, #f3f4f6, #22c55e]常见问题排查问题解决方案区域不显示数据检查geoJsonPropertyKey与数据精确匹配大小写敏感点不出现确认经纬度合法纬度 -90~90经度 -180~180无颜色显示确保valueFieldId在metricQuery中气泡大小都一样添加值有差异的sizeFieldId自定义 GeoJSON 不加载确认 URL 公网 HTTPS 可访问且返回合法 GeoJSON热力图太淡提高heatmapConfig的opacity最大 1与radius最大 50tooltip 显示多余字段用fieldConfig将不需要的字段设为visible: false部署为代码的工作流地图图表与其它图表一样遵循UI 创建 → 下载 → 编辑 → lint → 上传的内容即代码流程完整命令见 SKILL.mdlightdash download --charts store-locations # 拉取图表为 YAML # 编辑 YAML参考本文的配置示例 lightdash lint # 本地校验 lightdash upload --charts store-locations # 同步回 Lightdash注意 YAML 键需按字母序排列CLI 写入时启用sortKeys上传时对未排序键给出警告contentType: chart为必填顶层字段。指标与维度的定义方式分别见 metrics-reference.md 与 dimensions-reference.md。相关资源Chart Types 总览 — 所有图表类型的选型与通用结构Metrics Reference — 为地图图表的着色/定径创建指标Dimensions Reference — 位置类维度的定义Chart-as-Code Schema —$defs/MapChart权威字段定义地图渲染实现 — Leaflet 渲染、TopoJSON 转换与区域匹配Leaflet 地图配置 Hook — 内置中心点/缩放、底图瓦片配置与 GeoJSON URL 解析GeoJSON 代理 — 外部自定义 GeoJSON 的安全代理限制内置 GeoJSON 数据源说明 — us-states / countries 边界文件与属性清单【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考