【腾讯位置服务开发者征文大赛】腾讯位置服务 + React Native：地图、检索、规划、导航一条龙，附可运行 Demo

作者: weixin_47315004
发布时间: 已于 2026-04-15 11:52:15 修改
来源: https://blog.csdn.net/weixin_47315004/article/details/160170636

📹 嵌入式视频: https://live.csdn.net/v/embed/521734

demo视频

TencentMapDemo：基于 react-native-tencent-map-kit 的可运行示例

工程名TencentMapDemo· 依赖react-native-tencent-map-kit（file:../react-native-tencent-map-kit）· React Native0.82.1· React19.1.1

零、使用说明

0.1 环境

• macOS（同时开发 iOS 与 Android 时）。
• Node.js ≥ 20（与package.json中engines一致）。
• Yarn 1（仓库含packageManager字段）。
• Xcode；Android Studio，配置ANDROID_HOME，模拟器或真机。

0.2 目录结构

package.json：

"react-native-tencent-map-kit": "file:../react-native-tencent-map-kit"

组件库与 Demo 位于同一父目录，例如：

父目录/
  TencentMapDemo/
  react-native-tencent-map-kit/

若缺少同级组件库，yarn install会失败；可将组件库放到该路径，或把依赖改为 npm / git 地址。

0.3 Key 与控制台

1. 在腾讯位置服务控制台创建 Key。
2. Android 包名绑定com.rn.tencent.map；iOS 绑定 Xcode 中的 Bundle Identifier。
3. 在src/constants.ts填写TENCENT_WEB_SERVICE_KEY。

App.tsx启动时调用configureTencentMapSdk与TencentMapService.configure，均使用该常量。

0.4 安装与 Metro

cd TencentMapDemo
yarn install
yarn start

保持 Metro 终端运行，另开终端执行编译命令。

0.5 Android

1. 启动模拟器或连接真机。
2. 执行yarn android。
3. 首次使用定位时在系统弹窗中授予权限（工程内已调用ensureAndroidLocationPermission）。

0.6 iOS

1. 在仓库根目录执行yarn pod。
2. 用 Xcode 打开ios/TencentMapDemo.xcworkspace运行，或执行yarn ios。
3. 授予定位权限。
4. 模拟器测试定位与路线时，在 Features → Location → Custom Location 设置经纬度。

0.7 首页

标题「腾讯地图ReactNative 版本」，下列三项进入子屏，子屏顶部返回首页。

0.8 地图样式

1. 首页进入「地图样式」。
2. 地图随initialCenter执行moveToRegion。
3. 底部「标准 / 卫星 / 夜间」切换mapType。
4. 使用指南针、比例尺、定位按钮、缩放控件。

0.9 位置搜索 API

1. 首页进入「位置搜索 API」。
2. 搜索框默认「咖啡」；修改关键词后点「演示 searchPoi」，Modal 中选 POI，以当前位置为起点规划到该点。
3. 点「演示 planRoute：当前位置 → 演示终点」使用ROUTE_TO为终点。
4. 完成一次规划后，切换「驾车 / 步行 / 骑行 / 公交」会按上次终点自动重算。
5. 「附近咖啡」「北京地铁」「演示 reverseGeocode」为固定示例入口。
6. 「回到地图中心」调用setCenter(initialCenter)。

0.10 导航与路线规划

1. 首页进入「导航与路线规划」。
2. 搜索 → 选 POI → 自动规划；或未选点时「发起路线规划（默认终点）」使用ROUTE_TO。
3. 切换出行方式立即重规划。
4. 「开始应用内导航」：iOS 驾车优先startDriveNavigation；否则定时刷新位置的轻量跟随，并显示剩余距离。
5. 「停止」结束定时器并停止原生导航。

0.11 自有工程接入

1. yarn add react-native-tencent-map-kit（或file:/ git 依赖）。
2. 入口调用configureTencentMapSdk({ key })与TencentMapService.configure({ key })。
3. iOS：pod install；Android：按组件库说明配置 Gradle 与权限。
4. 页面中使用TencentMapView与TencentMapService；路线返回体用与 Demo 相同的parseDirectionPolyline解析。

0.12 常见问题

• 白图：检查 Key、包名与 Bundle ID、网络、configureTencentMapSdk是否执行。
• 规划失败：查看接口返回与 Key 权限、配额、起终点。
• 公交折线异常：使用包含steps[].lines[].polyline的解析逻辑。
• 位置搜索 API 页切换方式无新路线：需先成功规划一次产生lastRouteDest。
• yarn install报 engine：升级 Node 或使用yarn install --ignore-engines。

一、工程说明

React Native 示例应用，演示接入react-native-tencent-map-kit。DemoScreenId：home、mapStyle、services、navigation。子屏通过ScreenHeader返回。App.tsx在进入子屏的useEffect中调用getCurrentPositionRn()更新initialCenter。

二、首页入口

文案与src/screens/HomeScreen.tsx中MENU一致。

三、地图样式屏

MapStyleDemoScreen。ApiDemoIntro对应TencentMapView.mapType、uiControls、TencentMapViewRef.moveToRegion。mapType为standard/satellite/night，对应原生 0/1/2。

四、位置搜索 API 屏

ServiceApiDemoScreen，屏标题「位置服务 API」。API：searchPoi、planRoute、reverseGeocode、markers/polylines、getCurrentPositionRn。默认搜索词「咖啡」。lastRouteDest用于切换TravelMode后自动重规划。

五、导航与路线规划屏

NavigationDemoScreen。searchPoi、planRoute、未选 POI 时终点为ROUTE_TO。切换方式调用planRoute(mode)。iOS 驾车startDriveNavigation；轻量跟随使用remainingMetersAlongPolyline。卸载时stopDriveNavigation或NativeModules.TencentNavigationModule.stopDriveNavigation。

六、constants.ts

• DEMO_CENTER：纬度39.984104，经度116.307503。
• ROUTE_FROM、ROUTE_TO：演示路线起终点。
• TENCENT_WEB_SERVICE_KEY：WebService 与 SDK 初始化。

七、工具模块

geolocationRn.ts：WGS-84 转 GCJ-02。locationPermission.ts：Android 运行时定位权限。parseDirectionPolyline.ts：解析压缩 polyline；公交合并steps[].polyline与steps[].lines[].polyline。

八、原生配置摘要

• Android：AndroidManifest.xml网络与定位权限；applicationId/namespacecom.rn.tencent.map。
• iOS：Info.plist定位说明、UIBackgroundModes含location、LSApplicationQueriesSchemes含qqmap。

九、命令速查

cd TencentMapDemo
yarn install
yarn start
yarn pod
yarn ios
yarn android

十、部署检查

1. 控制台 Key 已绑定 Android 包名com.rn.tencent.map与 iOS Bundle ID。
2. src/constants.ts中 Key 已填写。
3. iOS 已执行yarn pod，使用.xcworkspace编译。
4. 模拟器已设置自定义位置（若需验证定位与路线）。