鸿蒙导航SDK快速集成指南（ArkTS版）

一、申请腾讯位置服务SDK Key

第一步：注册腾讯位置服务账号

1. 访问腾讯位置服务官网
2. 点击"控制台"注册/登录开发者账号

第二步：创建应用获取Key

1. 进入控制台后选择【应用管理】→【我的应用】
2. 点击【创建应用】按钮
3. 填写应用名称（如"MyHarmonyApp"）
4. 选择应用类型为"移动应用"
5. 在"添加新Key"部分：
   • 勾选"SDK"
   • 勾选“导航SDK”
   • 填写Harmony应用的appIdentifier
6. 点击【添加】生成Key

⚠️ 注意：请妥善保管您的Key，每个Key有每日调用限额

更新详细内容可以参考鸿蒙地图SDK配置Key的过程

二、导航SDK依赖配置

// 在module的oh-package.json5中添加依赖
"dependencies": {
    "@tencentmap/nav-ui": "1.0.0",
    "@tencentmap/nav": "1.0.0"
}

三、导航SDK权限配置

// 在module.json5中添加权限配置
"requestPermissions": [
    {
        "name": "ohos.permission.GET_NETWORK_INFO"
    },
    {
        "name": "ohos.permission.GET_WIFI_INFO",
    },
    {
        "name": "ohos.permission.INTERNET"
    },
    {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:fuzzy_location_permission",
        "usedScene": {
        "abilities": [
            "EntryAbility"
        ],
        "when": "inuse"
        }
    },
    {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_permission",
        "usedScene": {
        "abilities": [
            "EntryAbility"
        ],
        "when": "inuse"
        }
    },
    {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:Harmony_navi_permission_reason",
        "usedScene": {
        "when": "always"
        }
    },
    {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
    }
]

• ohos.permission.GET_NETWORK_INFO：获取网络状态。
• ohos.permission.GET_WIFI_INFO：获取Wi-Fi状态。
• ohos.permission.INTERNET：网络权限。
• ohos.permission.APPROXIMATELY_LOCATION：模糊位置权限。
• ohos.permission.LOCATION：精确位置权限，想要获取精确位置需要同时声明上面的模糊位置权限。
• ohos.permission.LOCATION_IN_BACKGROUND：后台定位权限，用于后台导航。（可选，后台导航需要）
• ohos.permission.KEEP_BACKGROUND_RUNNING：后台运行权限，用于后台导航。（可选，后台导航需要）

四、快速开始导航功能

第一步：初始化导航SDK

import {
  LatLng,
  MapController,
  NavContext,
  NavMapComponent,
  NavSDK,
  NavSearchPoint,
  TravelMode
} from "@tencentmap/nav";
import { NavUI } from "@tencentmap/nav-ui";

@Entry
@Component
export struct QuickStartPage {
  mapController?: MapController
  navContext?: NavContext

  aboutToAppear(): void {
    // 设置用户隐私协议同意状态
    NavSDK.setUserAgreedPrivacy(true)
    // 设置key
    NavSDK.Init({
      developerKey: "your key"
    })
    // 获取导航上下文实例
    this.navContext = NavSDK.getNavContext();
  }
}

第二步：设置地图视图

build() {
  RelativeContainer() {
    // 添加地图组件
    NavMapComponent({
      onReady: (error, mapController: MapController) => {
        this.mapController = mapController
        this.quickStart();
      }
    })

    // 添加导航UI组件
    NavUI({
      navContext: this.navContext
    }).hitTestBehavior(HitTestMode.Transparent)
  }
}

第三步：规划路线并开始导航

async quickStart() {
  if (!this.mapController || !this.navContext) return;

  // 设置起点(中关村第三极大厦)
  const start: NavSearchPoint = {
    poi: {
      latLng: new LatLng(39.984105, 116.307499),
      poiId: "3629720141162880123",
      name: "中关村第三极大厦"
    }
  }
  
  // 设置终点(腾讯北京总部大楼)
  const end: NavSearchPoint = {
    poi: {
      latLng: new LatLng(40.040417, 116.273514),
      poiId: "3232643565056451135",
      name: "腾讯北京总部大楼"
    }
  }
  
  // 搜索驾车路线
  const routeRes = await this.navContext.searchRoute({
    travelMode: TravelMode.TravelModeDriving,
    start: start,
    end: end,
  })

  // 开始导航
  this.navContext.startNav(this.mapController, routeRes.routes[0].routeId);
}

运行效果

五、常见问题

1. 鉴权失败：

   • 检查应用的appIdentifier是否与控制台配置一致

2. 无地图显示：

   • 检查网络连接是否正常
   • 确认已添加INTERNET权限