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

工程名 TencentMapDemo · 依赖 react-native-tencent-map-kit（file:../react-native-tencent-map-kit）· React Native 0.82.1 · React 19.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 一致。

id	标题	副标题
mapStyle	地图样式	标准 / 卫星 / 夜间
services	位置搜索 API	POI 检索、逆地理、搜索结果弹窗选点
navigation	导航与路线规划	出行方式切换、路线规划、轻量导航、原生导航

三、地图样式屏

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 / namespace com.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. 模拟器已设置自定义位置（若需验证定位与路线）。