企业官网建设流程全解析

MapLibre React Native v11 是首个仅支持 React Native 新架构的大版本，同时 API 全面向 MapLibre GL JS 对齐。这份指南为初學者逐条讲解从 v10 到 v11 的破坏性变更：组件改名、属性对齐、事件重构与模块升级，并附上避坑速查表，帮你一次改对、平稳完成 Map 地图库升级。

为什么必须迁移：v11 带来了什么

v11 于 2026 年 4 月发布，核心变化有两点：

• 新架构（New Architecture）成为唯一支持项：基于 TurboModule 与 Codegen，地图、相机、数据源、图层等核心组件全部重构成新架构实现，带来更流畅的渲染与更低的事件延迟，并兼容 Reanimated v4。
• API 全面对齐 MapLibre GL JS：如果你同时维护 Web 端地图（maplibre-gl-js），v11 之后两端可以用几乎相同的属性名与事件模式，心智负担大幅降低。

💡 如果还停留在 v9 或更早版本，请先阅读 docs/content/setup/migrations/v10.md，再按本文迁移到 v11。

迁移前置检查：3 个硬性条件

开始动手前，对照 docs/content/setup/getting-started.md 确认环境满足：

安装方式按项目类型选择 Expo 或原生流程，详见 docs/content/setup/expo.md 与 docs/content/setup/react-native.md。

第一步迁移：MapView 改名为 Map

最直观的一步——主组件MapView更名为Map（组件实现在 package/src/components/map/Map.tsx）：

function App() { return <Map mapStyle={MAPLIBRE_DEMO_STYLE} />; }

随之一并发生的变化：

• Android 默认改用GLSurfaceView渲染，与原生 SDK 默认行为一致；如需回退，添加androidView="texture"属性即可。
• localizeLabels、regionWillChangeDebounceTime等属性被移除（防抖逻辑请自行在业务代码中处理）。
• 装饰件 API 统一：用attribution/logo/compass布尔属性开关，配合xxxPosition对象属性（top/bottom/left/right）定位。
• contentInset从数组改为统一的ViewPadding对象：{ top, right, bottom, left }。
• Light组件删除，改为Map上的light属性。

交互属性与命令式方法对齐 GL JS

另外新增getBearing()、getPitch()、getViewState()三个方法，属性文档见 docs/content/components/map.md。

Camera 组件：相机控制 API 重命名

Camera是迁移中改动最集中的组件，核心属性全部换名：

<Camera center={[-122.42, 37.77]} zoom={12} duration={2000} easing="ease" />

其他要点：

• defaultSettings更名为initialViewState，其中bounds改为[west, south, east, north]数组，padding使用ViewPadding对象。
• 跟随用户位置的followUserLocation+followUserMode合并为单个trackUserLocation，取值"default"/"heading"/"course"；原followZoomLevel等属性直接用zoom/bearing/pitch控制。
• 命令式方法：setCamera()→setStop()，moveTo()→jumpTo()，并新增easeTo()。

详见 docs/content/components/camera.md。

数据源迁移：ShapeSource 变为 GeoJSONSource

ShapeSource更名为GeoJSONSource，且url与shape两个属性统一为data——既接受 URL 字符串，也接受 GeoJSON 对象，写法与 Web 端完全一致：

<GeoJSONSource id="my-source" data={geojson} />

命令式方法也有调整：features()更名为getData()；聚类相关方法（getClusterLeaves、getClusterChildren等）参数从 Feature 对象改为clusterId数字，并返回GeoJSON.Feature[]数组；VectorSource的features()更名为querySourceFeatures({ sourceLayer, filter })。文档见 docs/content/components/sources/geo-json-source.md。

8 个图层组件合并为一个 Layer

v10 中的FillLayer、LineLayer、CircleLayer、SymbolLayer、HeatmapLayer、RasterLayer、BackgroundLayer、FillExtrusionLayer全部合并为统一的Layer组件，用type属性区分：

<Layer type="fill" id="parks" source="parks-source" paint={{ "fill-color": "green", "fill-opacity": 0.5 }} layout={{ visibility: "visible" }} />

这是 v11 最实用的升级点：paint和layout采用 Style Spec 的 kebab-case 命名，意味着Maputnik 等样式编辑器导出的 JSON 图层定义可以直接展开（spread）到组件上，Web 与原生端还能共用同一份图层配置，并享受类型安全的自动补全。旧style属性暂时保留，但将在 v12 移除，建议尽早切换。属性改名对照：sourceID→source、sourceLayerID→source-layer、belowLayerID→beforeId、aboveLayerID→afterId。

注释、标注与图片：LayerAnnotation、ViewAnnotation、Images

这一组变更围绕"改名 + 事件模式统一"展开：

• Annotation→LayerAnnotation：coordinates属性更名lngLat；style/icon属性移除，改为在子级放一个type="symbol"的Layer来实现图标。
• PointAnnotation→ViewAnnotation：coordinate更名lngLat；anchor从数值对象改为"top"等字符串；新增offset属性做像素级微调；事件回调onSelected/onDeselected更名onSelect/onDeselect。
• Images组件：images与nativeAssetImages合并为单个images对象；ImageEntry需要远程资源时用{ source: { uri } }结构；onImageMissing等事件的载荷移入event.nativeEvent。

所有事件统一遵循NativeSyntheticEvent模式：业务数据从event顶层移入event.nativeEvent，且 Source 的onPress默认会冒泡到Map，可用event.stopPropagation()阻断。

图片覆盖能力不受影响，官方示例中用ImageSource把气象雷达图叠加到北美地图上（示例源码：examples/shared/src/examples/FillRasterLayer/ImageOverlay.tsx）：

模块升级：定位、离线、静态图与日志

各模块文档：docs/content/modules/location-manager.md、docs/content/modules/offline-manager.md、docs/content/modules/static-map-manager.md、docs/content/modules/log-manager.md。

迁移避坑速查表

迁移时最容易出错的 6 个地方，改代码前先看一遍：

1. ⚠️事件载荷位置：所有onPress、onSelect、onImageMissing的数据都在event.nativeEvent里了，直接解构event会拿到undefined。
2. ⚠️bounds 数组顺序：initialViewState与离线包的bounds统一为[west, south, east, north]，注意是"西南角 → 东北角"，别沿用旧的[[east, north], [west, south]]。
3. ⚠️离线包查找键：getPack/deletePack/invalidatePack现在传pack.id，旧包的name保存在pack.metadata.name中。
4. ⚠️Android 渲染回退：默认换成了GLSurfaceView，若出现兼容性异常，加androidView="texture"回退。
5. ✅图层 JSON 复用：paint/layout支持 kebab-case，直接展开 Maputnik 导出的图层对象即可，这是 v11 的新福利。
6. ✅style属性过渡期：图层旧style属性在 v11 仍可用但已废弃，v12 移除，建议本次一并改掉。

完整逐项变更以官方迁移指南为准：docs/content/setup/migrations/v11.md。

迁移后验证：用官方示例回归测试

改完代码后，建议按下面 3 步收尾：

1. 类型检查：运行 TypeScript 编译，v11 的类型收窄会把漏改的属性名全部暴露出来，这是最快的查漏手段。
2. 跑通示例工程：仓库自带的示例 App（examples/）覆盖了Map、Camera、Layer、GeoJSONSource、离线包、定位等全部场景，可逐一对照你的业务页面。
3. 双端回归事件：重点在 Android 与 iOS 各验证一次点击/长按回调、相机跟随与离线包下载进度，确认nativeEvent载荷取值正确。

至此，你的地图应用就完成了从 v10 到 v11 的升级：组件更名是"体力活"，Layer统一、GL JS API 对齐与nativeEvent事件模式则是"长期饭"——升级一次，两端代码从此一套写法。