移动开发UI组件前端【免费下载链接】react-native-mapsReact Native Mapview component for iOS Android项目地址https://gitcode.com/gh_mirrors/re/react-native-maps点击查看免费下载导读本文是 react-native-maps当前仓库版本 v1.29.5的官方安装与配置手册覆盖从 npm 安装、Expo 插件接入到 iOS 端 Apple Maps / Google Maps 双后端选择、Android 端 Google Maps API Key 注入的完整流程并整理了大量一线开发中常见的故障排查方案。读完本文你将掌握在裸工作流bare workflow与 Expo 托管项目中正确接入地图组件、配置双平台原生依赖的全部操作步骤。一、安装 npm 包react-native-maps 以 npm 包形式分发安装命令非常简单$ npm install react-native-maps # --- 或 --- $ yarn add react-native-maps安装前请确认你的工程满足版本约束。从仓库的 package.json 可以看到该库的 peerDependencies 要求react 18.3.1react-native 0.76.0react-native-web 0.11可选仅 Web 端需要同时engines字段要求node 20.19.4。注意npm install完成后真正的原生地图实现还需要根据平台分别做配置不能直接跑起来。二、平台差异地图后端的选择地图的实际渲染实现完全取决于平台Android只能使用 Google MapsAndroid SDK 端因此你必须先申请一个Android SDK 专用 API Key。iOS可以选择 Google Maps也可以使用系统自带的Apple MapsMapKit实现。当在 iOS 上使用 Google Maps 时你还需要申请iOS SDK 专用 API Key并把 Google Maps 原生库引入构建而基于 Apple Maps 的实现则开箱即用配置更简单代价是会缺少一部分只有 Google Maps 后端才支持的特性如 KML 标记、热力图、聚合标记等。WARNING在使用 Google Maps Platform 的 API 与 SDK 之前你必须先注册 Google Cloud 账号并创建billing account计费账号否则无法启用地图服务。这一平台差异也直接体现在仓库的原生代码结构上iOS 侧同时维护了两套实现Apple Maps 实现位于 ios/AirMapsGoogle Maps 实现位于 ios/AirGoogleMapsAndroid 侧则只有一套基于 Google Maps SDK 的实现位于 android/src/main/java/com/rnmaps/maps。三、Expo 项目接入config plugin如果你使用 Expo可以通过官方提供的 config plugin 一键接入只需把它加入app.json或app.config.js的plugins数组{ expo: { plugins: [react-native-maps] } }Note:该插件仅兼容 react-native-maps 1.22 及以上版本并要求 Expo SDK 版本 53 及以上。如果使用 Google 作为地图提供方还需要在插件参数中为对应平台提供 API Key{ expo: { plugins: [ [ react-native-maps, { iosGoogleMapsApiKey: YOUR_KEY_HERE, androidGoogleMapsApiKey: YOUR_KEY_HERE } ] ] } }插件背后做了什么Expo 插件的实现在仓库的 plugin/src/index.ts它会把 iOS 与 Android 两套修改逻辑串起来iOS 侧plugin/src/ios.ts把iosGoogleMapsApiKey写入Info.plist的GMSApiKey字段当提供了 iOS Key 时自动向 Podfile 注入pod react-native-maps/Google并在 Swift AppDelegate 的didFinishLaunchingWithOptions方法最前面插入GMSServices.provideAPIKey(...)调用配合import GoogleMaps。若未提供 Key则会反过来把已注入的代码移除保持工程干净。Android 侧plugin/src/android.ts在AndroidManifest.xml的application节点下添加名为com.google.android.geo.API_KEY的meta-data条目未提供 Key 时同样会移除该条目。插件的类型定义见 plugin/src/types.ts入口由 app.plugin.js 指向构建产物。这套机制意味着Expo 用户不需要手动改 AppDelegate、Podfile 或 Manifest插件会在expo prebuild时自动完成全部原生配置。四、裸工作流iOS 配置对于 bare workflow裸工作流项目需要按下面的步骤手动配置 iOS 与 Android。4.1 安装 CocoaPods 依赖安装完 npm 包后进入 ios 目录执行$ (cd ios pod install) # --- 或 --- $ npx pod-installpod install会依据仓库根目录的 react-native-maps.podspec 解析依赖。从该文件可以看到podspec 通过default_subspec Maps默认引入 Apple Maps 实现ios/AirMaps并附带一个构建脚本script phase它会检测PODS_ROOT下是否存在GoogleMaps与Google-Maps-iOS-Utils库并据此把HAVE_GOOGLE_MAPS宏写入 ios/AirMaps/RNMapsDefines.h从而在编译期决定启用哪套后端。这也是「Apple Maps 开箱即用、Google Maps 需要显式接入」的底层原因。4.2 启用 Google MapsiOS若要在 iOS 上启用 Google Maps请先获取 Google API Key然后按工程语言修改 AppDelegate。Objective-CAppDelegate.m/AppDelegate.mm #import GoogleMaps/GoogleMaps.h implementation AppDelegate ... (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [GMSServices provideAPIKey:_YOUR_API_KEY_]; // add this line using the api key obtained from Google Console ...注意[GMSServices provideAPIKey]必须是didFinishLaunchingWithOptions方法中的第一个调用。SwiftAppDelegate.swiftReact Native 0.77 及以上版本创建的工程默认使用 Swift 编写的 AppDelegate import GoogleMaps main class AppDelegate: RCTAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? nil ) - Bool { GMSServices.provideAPIKey(_YOUR_API_KEY_) // add this line using the api key obtained from Google Console ... } }同样GMSServices.provideAPIKey必须是该方法的第一个调用。仓库自带的示例工程 example/ios/rnmshowcase/AppDelegate.swift 展示了生产级的写法它从 Info.plist 读取MAPS_API_KEY再调用GMSServices.provideAPIKey(MAPS_API_KEY)避免了把 Key 硬编码在源码中——这是值得推荐的实践。4.3 部署目标与 Podfile 平台版本Google Maps SDK for iOS 要求iOS 14因此请确保Xcode 工程Targets → General → Deployment Info的部署目标 14Podfile 顶部的 platform 声明 14platform :ios, 14仓库示例工程 example/ios/Podfile 中实际使用的是platform :ios, 15.1这与 podspec 中s.platform :ios, 15.1一致。4.4 在 Podfile 中声明 Google Maps 子模块在 Podfile 的use_native_modules!函数上方添加以下内容然后在 ios 目录重新执行pod install# React Native Maps dependencies rn_maps_path ../node_modules/react-native-maps pod react-native-maps/Google, :path rn_maps_path从 react-native-maps.podspec 的s.subspec Google定义可以看出这条声明会引入ios/AirGoogleMaps源码、GoogleMaps与Google-Maps-iOS-Utils两个 CocoaPods 依赖并以-DHAVE_GOOGLE_MAPS1 -DHAVE_GOOGLE_MAPS_UTILS1编译。示例工程的实际用法见 example/ios/Podfile该工程将rn_maps_path设为../..因为它在仓库内以相对路径引用本库。4.5 覆盖 Google Maps 依赖版本可选如果你需要锁定 Google Maps 相关依赖的版本可以在 Podfile 中、react-native-maps/Google声明之前设置两个全局变量$RNMapsGoogleMapsVersion 10.10.0 $RNMapsGoogleMapsUtilsVersion 7.0.0 rn_maps_path ../node_modules/react-native-maps pod react-native-maps/Google, :path rn_maps_path对应的解析逻辑位于 react-native-maps.podspec 中podspec 默认使用GoogleMaps 9.4.0与Google-Maps-iOS-Utils 6.1.0一旦检测到上述全局变量已定义就会改用你指定的版本。4.6 Info.plist 位置权限说明应用的Info.plist必须包含NSLocationWhenInUseUsageDescription键并用面向用户的措辞清楚说明应用为什么需要位置信息否则Apple 会拒绝应用上架。这一点无论你是否真正读取用户位置都是强制要求——因为 Google Maps iOS SDK 内部包含了访问用户位置的代码。配置完成后iOS 端的接入就完成了。五、裸工作流Android 配置5.1 在 Manifest 中声明 Google Maps API Key把 API Key 添加到android/app/src/main/AndroidManifest.xmlapplication !-- You will only need to add this meta-data tag, but make sure its a child of application -- meta-data android:namecom.google.android.geo.API_KEY android:valueYour Google maps API Key Here/ /applicationAndroid 端的地图视图 android/src/main/java/com/rnmaps/maps/MapView.java 及其管理器正是依赖这个 Key 初始化 Google Map 实例的。5.2 升级到 v0.31.0 的说明早期版本的安装文档要求你在build.gradle中配置supportLibVersion、playServicesVersion、androidMapsUtilsVersion等键。这些键现在都不再需要可以安全删除除非项目里其他模块仍在引用。ATTENTION如果你仍保留了playServicesVersion其版本号必须至少为18.0.0。5.3 确保设备装有 Google Play Services使用Genymotion 模拟器按其官方 FAQ 中关于 Google Play Services 的指引安装。使用真机在 Google 搜索 Google Play Services进入 Play Store 对应页面后点击更新按钮注意不要在 Play Store 内部搜索那样找不到更新入口。六、故障排查Troubleshooting6.1 地图背景空白Google Maps如果 Google logo、标记、折线等元素都正常显示唯独地图背景空白这几乎可以断定是 API Key 问题。请依次检查核对 API Key 及其**应用限制restrictions**配置是否正确确保原生侧provideAPIKey调用是didFinishLaunchingWithOptions的第一行确保你的 Google Cloud 项目已启用对应的 APIAndroidGoogle Maps SDK for AndroidiOS如需要Google Maps SDK for iOS参考该问题在社区中被多次报告相关 issue 编号为 #118、#176、#684。6.2 地图背景灰色Google MapsAndroid 设备上如果出现灰屏可以在android/app/src/main/res/values/下创建google_maps_api.xmlresources string namegoogle_maps_key templateMergeStrategypreserve translatablefalse(api key here)/string /resourcestemplateMergeStrategypreserve是 Android Studio 模板生成时的关键属性可避免后续构建覆盖你的 Key 值。6.3 完全没有地图什么也不显示请确认地图组件及其容器都有明确的视口尺寸。示例如下import MapView, { PROVIDER_GOOGLE } from react-native-maps; // remove PROVIDER_GOOGLE import if not using Google Maps ... const styles StyleSheet.create({ container: { ...StyleSheet.absoluteFillObject, height: 400, width: 400, justifyContent: flex-end, alignItems: center, }, map: { ...StyleSheet.absoluteFillObject, }, }); export default () ( View style{styles.container} MapView provider{PROVIDER_GOOGLE} // remove if not using Google Maps style{styles.map} region{{ latitude: 37.78825, longitude: -122.4324, latitudeDelta: 0.015, longitudeDelta: 0.0121, }} /MapView /View );其中provider{PROVIDER_GOOGLE}在 src/ProviderConstants.ts 中定义如果不用 Google Maps请移除该 prop 及对应导入。6.4 Google Maps iOS Utils 构建问题iOS如果你的 Xcode 工程使用动态框架例如工程中混有 Swift 代码则无法通过 CocoaPods 安装Google-Maps-iOS-Utils。该问题及绕过方案在 Google 官方的google-maps-ios-utils仓库的Swift.md文档中有详细记录可据此处理。6.5 iOS 运行时错误Apple Maps 后端如果工程按 Apple Maps 后端构建却在运行时试图以GOOGLE_PROVIDER挂载地图会直接抛出运行时异常使用 Apple Maps 时部分依赖 Google Maps SDK 的高级功能会被以运行时错误的方式禁用包括从 KML 文件创建标记Marker热力图Heatmap渲染标记聚合Marker clustering其他 Google 专属能力6.6 清理缓存遇到构建或运行异常时可以依次执行以下命令清理缓存watchman watch-del-all npm cache clean # Android若遇到 com.android.dex.DexException: Multiple dex files define Landroid/support/v7/appcompat/R$anim请清理 build 目录 cd android ./gradlew clean cd ..6.7 使用 Android Studio确保 Android Studio 保持最新并按 React Native 官方环境搭建文档配置 SDK。特别注意以下包必须安装Extras / Google Play servicesExtras / Google RepositoryAndroid 6.0 (API 23) / Google APIs Intel x86 Atom System Image Rev. 19Android SDK Build-tools 23.0.36.8 Android 模拟器问题启动模拟器时勾选Wipe user data使用 AVDAndroid Virtual Devices时确保虚拟设备的设置中勾选了Use Host GPU如果模拟器上只显示[APPNAME] wont run without Google Play services which are not supported by your device.提示说明当前系统镜像不含 Google APIs需要在 Android SDK Manager 中下载包含 Google APIs 的 CPU/ABI 系统镜像再切换模拟器的 CPU/ABI 设置。6.9 Google Play Services 与其他模块版本冲突当多个模块同时依赖相同版本的 Google Play Services 依赖例如react-native-onesignal时可以从这些模块中排除冲突依赖改在工程级build.gradle中统一引入implementation(project(:react-native-onesignal)){ exclude group: com.google.android.gms } implementation(project(:react-native-maps)){ exclude group: com.google.android.gms } implementation com.google.android.gms:play-services-base:18.0.1 implementation com.google.android.gms:play-services-location:19.0.1 implementation com.google.android.gms:play-services-maps:18.0.2ATTENTIONreact-native-maps要求play-services-maps 18.0.0低于该版本将无法编译通过。6.10 Google Play services 本身的问题确认你的模拟器包含 Google Play路径Android Studio → Virtual Devices → 检查 Play Store 列是否有图标点击模拟器底部的点状...图标进入 Google Play 标签页并点击Update完成更新。七、小结回顾整条安装链路npm 安装 → 按平台注入 API Key → 引入原生依赖 → 配置权限与部署目标。三个关键点值得牢记API Key 双平台分离Android 与 iOS 的 Key 不同且 iOS 的provideAPIKey必须是首行调用iOS 后端二选一默认 Apple Maps 开箱即用Google Maps 需要额外 Podfile 声明、版本变量与位置权限文案Expo 用户优先走插件在 app.json 中声明react-native-maps插件并传入 Key原生配置由 config pluginplugin/src/index.ts自动完成大幅降低接入成本。如需进一步了解组件的具体用法可继续阅读仓库中的 docs/mapview.md、docs/marker.md、docs/polyline.md 等专项文档示例工程的完整接入代码可参考 example/ios/rnmshowcase/AppDelegate.swift 与 example/ios/Podfile。赞分享移动开发UI组件前端【免费下载链接】react-native-mapsReact Native Mapview component for iOS Android项目地址https://gitcode.com/gh_mirrors/re/react-native-maps点击查看免费下载相关推荐React Native Maps终极指南10个实用技巧实现流畅地图动画与精准定位React Native Maps终极指南10个实用技巧实现流畅地图动画与精准定位 React Native Maps是React Native生态中最强大的移动开发UI组件前端终极指南如何快速配置react-native-maps Apple Maps地图服务终极指南如何快速配置react native maps Apple Maps地图服务 React Native Maps是React Native生态中最强大移动开发UI组件前端InSpec核心架构解析理解框架内部工作原理InSpec核心架构解析理解框架内部工作原理 InSpec是一个强大的基础设施审计和测试框架它采用独特的架构设计来实现跨平台合规性检查。本文将深入解析InS上一篇极简流处理Flink Java Lambda表达式实战指南下一篇阿里Wan2.2开源电影级视频生成平民化消费级显卡即可部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考