react-map-gl

react-map-gl (MapLibre)

FixMyBerlin / FMC 项目中 react-map-gl/maplibre 的使用约定。从 react-map-gl/maplibre 导入（不要只从 react-map-gl 导入）。始终导入 maplibre-gl/dist/maplibre-gl.css。

import 'maplibre-gl/dist/maplibre-gl.css'
import { MapProvider, Map, Source, Layer, useMap } from 'react-map-gl/maplibre'

规则

主题	规则
数据源 / 图层	仅在 JSX 中使用 <Source> + <Layer>。应用数据不得调用 map.addSource / map.addLayer（或对应的移除方法）。通过 layout.visibility 或条件渲染控制显示 / 隐藏。
图层结构	平铺排列：每个数据源 ID 使用一个 <Source>，然后将 <Layer> 作为同级元素排列（不要嵌套）。
地图事件	相机、指针、加载和瓦片生命周期事件使用 <Map> 的回调属性。不要使用 useEffect + map.on(…)。useEffect 仅用于加载后将 React 状态同步到地图，或处理没有对应 Map 属性的事件（styleimagemissing）。
地图访问	使用 <MapProvider> 包裹应用地图 UI。通过 <Map id="…"> 设置的 ID，使用 useMap() 获取地图。不要将 ref 传给 <Map> 以供子组件访问。
地图就绪	使用 useMapLoaded()（在 onLoad 中设置）保护 getStyle、queryRenderedFeatures 和 setFeatureState 调用。
调试暴露	在 onLoad 中调用 exposeMainMapForDebugging(event.target)（仅用于开发环境和 Playwright）。Agent / 测试读取 window.__mainMap。
点击	在 interactiveLayerIds 中指定图层 ID；读取 event.features。除非要同步 URL 中的要素，否则不要用 queryRenderedFeatures 进行主要的点击拾取。
要素高亮	Inspector / 表单的状态以 React 为准；通过 setFeatureState（paint）或 React filter 图层设置地图色调。应用新状态前先清除旧状态。
署名	在 <Map> 上设置 attributionControl={false}，并将 <AttributionControl compact> 作为子元素。每个 <Map> 上都设置 RTLTextPlugin={false}。
视口 URL	URL 中使用 zoom/lat/lng，并根据缩放级别调整舍入精度；在 onMoveEnd 中使用 history: 'replace' 写入。
视图状态	使用 URL 提供初始值的非受控 initialViewState；除非需要程序化控制相机，否则不要在 React 中镜像维护 viewState。

应读取的文件

只读取与任务相关的文件。

任务	阅读
添加或检查 <Source> / <Layer>、移除 addSource	declarative-source-layer.md、flat-source-layer.md
显示/隐藏图层	layer-visibility-vs-unmount.md
点击/悬停处理程序、选择 <Map> 回调	map-event-handlers.md、interactive-layer-ids.md
将光标悬停在要素上	cursor-handling.md
子组件/同级组件需要地图实例	map-provider-wrapper.md
加载前调用 getStyle / queryRenderedFeatures	map-loaded-hook.md
Agent/E2E 地图检查	map-debug-exposure.md
选中/悬停要素高亮、setFeatureState	feature-state.md
初始相机、fitBounds、边界	initial-view-state.md
?map= URL 同步	map-url-state.md
署名、区域设置、RTL 文本插件	map-props-attribution-locale.md
缺失或动态图标、styleimagemissing、addImage	map-images.md

所有文件都位于 references/。请搭配以下技能使用：tanstack-router-conventions（?map= 约定）、zustand-state-management（useMapLoaded store）、playwright-skill（E2E 地图辅助工具）。

检查清单

• 不要对应用数据使用 addSource / addLayer / removeSource / removeLayer / setLayoutProperty；使用扁平的 <Source> + <Layer>
• <MapProvider> 作为父组件，使用 useMap()，不要在 <Map> 上使用 ref
• 不要使用 useEffect + map.on 处理移动/点击/悬停；在 onMoveEnd / onMove 上同步视口
• 触及地图的 Effect 必须将 React → 地图同步限制在 mainMap + mapLoaded 条件下
• onLoad 设置地图就绪标记，并调用 exposeMainMapForDebugging
• 每个可拾取图层的 id 都必须包含在 interactiveLayerIds 中；处理程序使用 event.features
• 应用新要素状态前，先清除旧状态；要素必须有 id（矢量数据使用 promoteId）
• attributionControl={false} + 子组件 <AttributionControl>；RTLTextPlugin={false}
• URL：共用 parseMapParam / serializeMapParam；平移/缩放时使用 replace；不要对序列化值使用 encodeURIComponent
• 固定图标使用 useMapImages；动态图标使用 useEffect 中的 styleimagemissing，并通过 off() 清理且添加 hasImage 检查