前端UI组件【免费下载链接】react-map-glReact friendly API wrapper around MapboxGL JS项目地址https://gitcode.com/gh_mirrors/re/react-map-gl点击查看免费下载本文基于仓库内的官方升级指南 docs/upgrade-guide.md 编写覆盖 react-map-gl 从 v1 到 v8.0 的全部重大变更模块入口拆分react-map-gl/mapbox、react-map-gl/maplibre、react-map-gl/mapbox-legacy、TypeScript 类型重命名、Map组件 props 重构、MapController/overlay 组件移除等。结合当前仓库主包版本为 8.1.0-alpha.2见 modules/main/package.json的源码与测试实现帮助你在跨版本升级时精确定位每一步需要修改的代码并理解每项变更背后的实现原因。升级到 v8.0v8 是一次以“按地图引擎拆分入口”为核心的版本升级时需要处理三件事替换导入入口、放弃 maplibre-gl3 支持、重命名 TypeScript 类型。替换导入入口所有从react-map-gl根路径的导入必须替换为以下入口之一搭配mapbox-gl3.5.0从react-map-gl/mapbox导入搭配mapbox-gl3.5.0从react-map-gl/mapbox-legacy导入使用 MapLibre 的用户从react-map-gl/maplibre导入该入口自 v7.1 引入见下文这一拆分在仓库的包配置中可以直接验证。modules/main/package.json 的exports字段只暴露三个子路径没有任何根入口exports: { ./mapbox: {...}, ./maplibre: {...}, ./mapbox-legacy: {...} }三个入口的实现都是极薄的转发层modules/main/src/mapbox.tsexport * from vis.gl/react-mapboxmodules/main/src/maplibre.tsexport * from vis.gl/react-maplibremodules/main/src/mapbox-legacy/index.ts独立导出Map、Marker、Popup、各控件与useControl/useMap并附带mapbox-legacy专属的类型与工具模块从源码结构看mapbox与mapbox-legacy对应 monorepo 中两个独立的实现包modules/react-mapbox与modules/main/src/mapbox-legacy前者基于 mapbox-gl v3 系列的 API 编写后者保留对旧版 mapbox-gl 的兼容。这也解释了为什么需要按mapbox-gl版本选择入口——两条代码路径对底层库的假设并不相同。不再支持 maplibre-gl3maplibre-gl3已被移除支持MapLibre 用户需要升级到 maplibre-gl v4。TypeScript 类型重命名v8 将部分自定义类型重命名与底层地图库的官方类型名对齐旧名称新名称MapStyleStyleSpecificationFogFogSpecificationLightLightSpecificationTerrainTerrainSpecificationProjectionProjectionSpecification*Layer*LayerSpecification*SourceRaw*SourceSpecification两条入口的类型来源可以在源码中对照确认react-map-gl/mapbox路径直接 re-export mapbox-gl 的官方类型名见 modules/react-mapbox/src/types/style-spec.tsStyleSpecification、LightSpecification、FogSpecification、TerrainSpecification、ProjectionSpecification等全部来自mapbox-glreact-map-gl/mapbox-legacy路径则用export type {...} from mapbox-gl把官方短名映射为*Specification名称见 modules/main/src/mapbox-legacy/types/style-spec.ts例如Style as StyleSpecification、Light as LightSpecification、Fog as FogSpecification、AnySourceData as SourceSpecification等与上表的重命名规则一一对应如果项目中通过import type {MapStyle, CircleLayer} from react-map-gl/mapbox之类的写法引用了旧类型升级到 v8 后需要按上表逐一替换为新名称。MapLibre移除RTLTextPlugin默认值为了与 MapLibre 的默认行为对齐v8 移除了原先从 mapbox.com 默认加载的RTLTextPlugin该插件用于支持阿拉伯语、希伯来语等从右向左书写的文本。如果希望保留旧版行为需要显式指定pluginUrl或从其他来源提供插件Map RTLTextPluginhttps://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js /源码层面这一差异非常清晰Mapbox 入口的 modules/react-mapbox/src/utils/set-globals.ts 中RTLTextPlugin的解构默认值仍是指向 mapbox.com 的插件 URL即 Mapbox 用户不传该 prop 时插件会自动加载MapLibre 入口的 modules/react-maplibre/src/utils/set-globals.ts 中则没有任何默认值只有当你传入RTLTextPlugin字符串 URL或{pluginUrl, lazy}对象形式时才会调用mapLib.setRTLTextPlugin(...)因此 v8 升级时对 MapLibre 项目的一个必查项就是如果界面需要 RTL 文本支持确认Map上显式传入了RTLTextPlugin。升级到 v7.1v7.1 最大的变化是为 MapLibre 用户提供了独立的模块入口react-map-gl/maplibre。MapLibre 用户改用新入口maplibre-gl用户不再需要安装mapbox-gl或任何占位包作为依赖。把导入切换到react-map-gl/maplibre后组件不再需要mapLibprop并使用maplibre-gl自己定义的类型import Map from react-map-gl; import maplibregl from maplibre-gl; function App() { return Map mapLib{maplibregl} style{MAP_STYLE} maplibreLogo // 这会产生 TypeScript 错误因为 Mapbox 的 options 中没有这个定义 /; }import Map from react-map-gl/maplibre; // - 注意更新后的导入 function App() { return Map // mapLib 默认为 import(maplibre-gl) style{MAP_STYLE} maplibreLogo /; }v7.0 时代mapLib写法存在的一个典型痛点是类型系统无法区分底层引擎maplibreLogo这类 MapLibre 专属选项在 Mapbox 类型定义中不存在只能靠as any或忽略报错。独立入口让react-map-gl/maplibre的MapProps直接基于maplibre-gl的类型问题自然消失。清理占位依赖如果按照旧版文档建议从占位包如npm:empty-npm-package^1.0.0安装了mapbox-gl应将其从 package.json 中移除。主包现在把mapbox-gl与maplibre-gl都声明为可选的 peer dependencypeerDependenciesMeta中optional: true见 modules/main/package.json你只需安装自己实际使用的那个地图库。其他 v7.1 变更types/mapbox-gl的依赖版本约束已放宽。如果以mapbox-gl作为底层库建议在 package.json 中显式列出与mapbox-gl主版本一致v1 或 v2的types/mapbox-gl。该包已不再是非 Mapbox 代码路径的必需依赖未来版本还可能被进一步降级为可选 peer dependency。如果你把Map组件作为 deck.gldeck.glContextProvider的子节点使用需要把deck.gl升级到8.9.18。升级到 v7.0v7 是 react-map-gl 的一次完全重写重新设计为更快、更轻量、完全类型化行为与暴露的 API 尽量与所包装的地图库保持一致并最大化与第三方插件的兼容性。如果你的代码依赖 v5/v6需要按下述章节逐项修改。重要如果你在使用 react-map-gl 的控件Marker、Popup、NavigationControl等配合 deck.gl 的ContextProvider请不要升级到 v7——旧方案在 v7 中不再工作。该用例的支持正在迁移到一个不依赖 mapbox 的新项目。依赖变更需要在你的 package.json 中添加mapbox-gl或兼容的 fork。react-map-gl不再在 dependencies 中固定某个地图渲染器你可以自由选择 Mapbox v1、v2 或 MapLibre。viewport-mercator-projectmath.gl/web-mercator的别名不再是依赖。如需要仍可以自行安装它作为视口数学工具但已非必需。模块导出移除移除项替代方案InteractiveMap、StaticMap统一导入MapsetRTLTextPlugin使用Map组件的RTLTextPluginprop默认启用MapController原生 handlers。v7 移除了自己的用户输入处理实现改为直接透传 mapbox-gl 的内置交互处理器MapContext、useMapControl新 APIuseMap与useControlHTMLOverlay、CanvasOverlay、SVGOverlay参考仓库示例 examples/mapbox/custom-overlay 与 examples/maplibre/custom-overlay 自行实现类似控件LinearInterpolator、FlyToInterpolator使用map.easeTo()与map.flyTo()参考示例 examples/mapbox/viewport-animation关于MapController的移除值得展开v7 不再维护一套自定义的输入处理逻辑而是让Map组件的 props 直接映射到地图库的原生 handler。从源码看modules/react-mapbox/src/mapbox/mapbox.ts 中的handlerNames列表scrollZoom、boxZoom、dragRotate、dragPan、keyboard、doubleClickZoom、touchZoomRotate、touchPitch就是被支持透传的交互开关默认全部启用见 modules/react-mapbox/src/mapbox/mapbox.ts 中_updateHandlers对nextProps[propName] ?? true的处理。如果你此前用自定义MapController做过特殊输入处理建议先对照原生 handler 的选项评估可行性。Map 组件 props 变更完整的 props 文档见 docs/api-reference/mapbox/map.md核心变更如下重命名的 props与底层库对齐旧 prop新 propmapboxApiAccessTokenmapboxAccessTokenmapboxApiUrlbaseApiUrlpreventStyleDiffing默认falsestyleDiffing默认true注意preventStyleDiffing→styleDiffing不仅是改名语义取反默认值从“不 diff”变成了“diff 开启”。源码中可以确认styleDiffing默认值为truemodules/react-mapbox/src/mapbox/mapbox.ts 的类型注释default true以及 modules/react-mapbox/src/mapbox/mapbox.ts 中const {mapStyle DEFAULT_STYLE, styleDiffing true} nextProps的解构默认值。默认值变更mapStyle现在必须显式指定。默认值从mapbox://styles/mapbox/light-v9变为空样式。源码中的空样式定义为{version: 8, sources: {}, layers: []}modules/react-mapbox/src/mapbox/mapbox.ts也就是说升级后如果不传mapStyle地图将是一张没有瓦片、没有图层的空白画布。移除的 propswidth、height、visible这三个 prop 被移除尺寸与可见性应通过styleCSS控制。onViewportChange、onViewStateChange、onInteractionStateChangev7 支持两种模式——把Map当作非受控组件使用配合新的initialViewStateprop或者在需要外部管理相机状态例如 Redux时改用onMove回调同步状态。相关模式见 docs/get-started/state-management.md。所有transition*props改用map.easeTo()与map.flyTo()参考示例 examples/mapbox/viewport-animation。mapOptions原生Map类的几乎所有选项现在都直接作为 props 暴露。onHover改用onMouseMove或onMouseEnter。所有交互回调的事件参数格式都发生了变化详情见文档。getCursor作为让Map与原生组件行为一致的一部分被移除。设置光标请使用cursorprop动态改变光标的做法参考示例 examples/mapbox/custom-cursor。touchAction与eventRecognizerOptions改用cooperativeGesturesprop。其他组件所有capture*props 被移除。所有*labelprops 被移除改用Map的localeprop。所有地图控件的 props 现在严格对齐 mapbox-gl 的对应控件。这一方向让 react-map-gl 删去了大量自定义代码使组件对从原生库迁移过来的开发者更可预测。如果你的应用依赖某个已不再支持的旧特性建议在项目讨论区Discussion发起讨论维护者会逐案评估。升级到 v5.3 / v6.1MapContext成为正式 API。实验性的_MapContext导出将在未来版本移除。react-virtualized-auto-sizer不再是依赖。地图控制器的惯性inertia默认开启。要恢复之前版本的行为通过 interaction options 显式关闭const CONTROLLER_OPTS { dragPan: {inertia: 0}, dragRotate: {inertia: 0}, touchZoom: {inertia: 0} }; MapGL {...CONTROLLER_OPTS} ... /Source与Layer组件不再通过ref暴露命令式方法——这是向函数式组件迁移的一部分符合最新 React 推荐的写法如果你曾调用sourceRef.getSource()可替换为mapRef().getMap().getSource(sourceId)如果你曾调用layerRef.getLayer()可替换为mapRef().getMap().getLayer(layerId)升级到 v6有效的 Mapbox access token 现在始终必需不再支持无 token 运行。InteractiveMap的maxPitch默认值从60改为85。这一默认值在 v7 的重写中延续了下来当前源码的DEFAULT_SETTINGS里同样是maxPitch: 85modules/react-mapbox/src/mapbox/mapbox.ts。mapbox-glv2 引入了构建系统的破坏性变更把 mapbox-gl v2 纳入转译transpile范围可能导致生产构建崩溃报错信息为m is not defined。通用解法是在构建工具中把mapbox-gl排除在转译之外例如 webpack 的transpileDependencies/ babel 的exclude配置。升级到 v4onChangeViewport被移除改用onViewportChange。Immutable.js不再是依赖。导出项experimental.MapControls被移除改用MapController。InteractiveMap的mapControlsprop 重命名为controller。移除对图层样式中已废弃interactive属性的支持。请改用interactiveLayerIdsprop 指定哪些图层可点击——这一机制在 v7 中同样存在interactiveLayerIds仍是Map的 prop源码中用于过滤queryRenderedFeatures的查询范围modules/react-mapbox/src/mapbox/mapbox.ts、modules/react-mapbox/src/mapbox/mapbox.ts。升级到 v3.2最新版 mapbox-gl 要求始终包含样式表stylesheet。样式引入方式见 docs/get-started/get-started.md。Immutable.js 不再是硬依赖并将在下一个主版本中移除。如果你的应用中有直接 import immutable建议在应用依赖中显式列出。升级到 v3v3 是 react-map-gl 的一次主版本大升级。虽然变更与移除的功能大多经历了温和的废弃deprecation过程但仍有若干无法避免的破坏性变更。版本要求构建react-map-gl 的 Node 版本要求为 v6.4.0由 mapbox-gl JS v0.38.0 引入。使用预构建版本没有此限制。MapGL 组件两个地图组件v3 将 Map 组件拆分为StaticMap与InteractiveMap。InteractiveMap是默认导出设计上尽可能兼容 v2 的默认组件。onChangeViewport回调现在包含width和height传给onChangeViewport回调的viewport参数现在包含width与height。如果应用代码把viewport与width/height组合使用可能需要更新——请检查依赖该行为的渲染代码// BAD: width 和 height 会被 viewport 对象中的值覆盖 ReactMapGL width{500} height{400} {...viewport} / // GOOD: width 和 height 会覆盖 viewport 中的值 ReactMapGL {...viewport} width{500} height{400} /Overlays部分 Overlay 移入示例使用频率较低的 overlayDraggablePointsOverlay、ChoroplethOverlay、ScatterplotOverlay被移到 examples 中。大多数用户现在使用 mapbox 样式或 deck.gl 图层移除这些 overlay 可以为多数用不到它们的用户减小库体积。如果仍在用直接把 overlay 源文件复制进你的应用即可。Overlay 必须是 Map 的子节点overlay 现在必须渲染为react-map-gl主组件的子节点才能自动与地图视口同步。fitBounds工具函数fitBounds工具函数移到了 math.gl 库viewport-mercator-project包。调用方式变为import WebMercatorViewport from viewport-mercator-project; const viewport new WebMercatorViewport({width: 600, height: 400}); const bound viewport.fitBounds( [[-73.9876, 40.7661], [-72.9876, 41.7661]], {padding: 20, offset: [0, -40]} ); // bounds: instance of WebMercatorViewport // {longitude: -73.48760000000007, latitude: 41.268014439447484, zoom: 7.209231188444142}废弃的 props以下 React props 开始进入废弃流程。这些旧props仍可用控制台会有警告但很可能在下一个主版本中移除建议尽快改用新props旧 Prop新 ProponChangeViewport(viewport)onViewportChange(viewport)onHoverFeatures(features)onHover(event)onClickFeatures(features)onClick(event)perspectiveEnabled默认falsedragRotate默认true升级到 v2v2 与 v1 API 兼容。但如果仍在使用 v1请确认先完成以下升级Node 版本升到v4或更高React 版本升到15.4或更高背景mapbox-gl0.31.0 引入了对 Node v4 的硬依赖。升级到 v1从 0.6.x 升级Overlay 导入方式变化地图 overlay 组件HTMLOverlay、CanvasOverlay、SVGOverlay等改为具名导出named exports不再需要通过相对源路径导入// v1.0 import MapGL, {SVGOverlay} from react-map-gl; // v0.6 import MapGL from react-map-gl; import SVGOverlay from react-map-gl/src/api-reference/svg-overlay;地图状态变化onViewportChanged报告的地图状态现在包含额外字段——不仅跟踪透视模式需要的pitch与bearing还包含投影如何被用户改变的瞬态信息。这些信息必须在下次渲染时传回 react-map-gl 组件。为简化和面向未来建议每当状态变化时把整个mapState存入应用 store然后整体传回组件而不是分别跟踪longitude、latitude、zoom等单个字段。版本迁移速查表版本核心变更关键动作v8.0按引擎拆分模块入口maplibre-gl3 停止支持导入改为react-map-gl/mapbox/mapbox-legacy/maplibreMapLibre 显式传RTLTextPlugin重命名 TS 类型v7.1新增react-map-gl/maplibre入口MapLibre 用户移除mapLibprop 与占位mapbox-gl依赖deck.gl 用户升级8.9.18v7.0完全重写移除MapController/InteractiveMap/overlay 组件props 重命名mapboxAccessToken、baseApiUrl、styleDiffingmapStyle必须显式指定视口改为initialViewState/onMove模式v6.1 / v5.3MapContext正式化惯性默认开启关闭惯性需显式传 interaction optionsSource/Layerref 命令式方法改用map实例方法v6token 始终必需maxPitch默认 85处理 mapbox-gl v2 构建转译问题v4interactiveLayerIds取代图层interactive属性MapControls改名为MapControllerv3.2mapbox-gl 样式表强制引入显式依赖 Immutable.js如用到v3拆分为StaticMap/InteractiveMapfitBounds移入 math.gloverlay 必须作为 Map 子节点废弃 props 迁移v2API 兼容 v1Node 4React 15.4v1overlay 改为具名导出整体保存并回传mapState升级操作建议先确定目标入口根据底层地图库及版本确定使用react-map-gl/mapbox、react-map-gl/mapbox-legacy还是react-map-gl/maplibre这是 v8 升级的第一决策点仓库中 modules/react-mapbox、modules/react-maplibre 与 modules/main/src/mapbox-legacy 分别对应三条实现路径可作为对照阅读的起点。按依赖关系自底向上迁移先处理Map组件props 重命名、mapStyle显式化、视口模式选择再处理Source/Layer最后处理各控件组件——因为控件 props 在 v7 起严格对齐原生库Map不先改好控件层容易连环报错。用类型检查兜底v7 起项目完全类型化升级后跑一遍 TypeScript 编译类型重命名v8与 props 移除v7的大多数问题会直接以编译错误形式暴露出来例如 v7 示例中maplibreLogo在 Mapbox 类型下的报错就是典型案例。关注仓库示例examples/mapbox与examples/maplibre目录下的 custom-overlay、viewport-animation、custom-cursor 等示例覆盖了 v7 移除项的主要替代方案可直接作为迁移参照。赞分享前端UI组件【免费下载链接】react-map-glReact friendly API wrapper around MapboxGL JS项目地址https://gitcode.com/gh_mirrors/re/react-map-gl点击查看免费下载相关推荐react-map-gl 升级指南从旧版本平滑迁移到最新版react map gl 升级指南从旧版本平滑迁移到最新版 前言 react map gl 是一个基于 Mapbox GL JS 的 React 地图组件库前端UI组件Dinero.js版本迁移从v1到v2的完整升级指南Dinero.js版本迁移从v1到v2的完整升级指南 Dinero.js v2带来了重大架构变革为JavaScript和TypeScript中的货币操作提供金融科技Switchyard 失败压力测试指南如何在 429、500 与截断流场景下验证 LLM 路由韧性Switchyard 失败压力测试指南如何在 429、500 与截断流场景下验证 LLM 路由韧性 Switchyard 是一款让 LLM 应用跨模型、跨服务人工智能大模型LLM 网关模型路由上一篇3行代码搞定多模态数据抓取YOSO-ai让文字/图片/语音采集自动化下一篇突破嵌入式存储瓶颈FlatBuffers本地化数据方案实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考