# 3rdSDK-AITrae-TencentMapSDK

**Repository Path**: HMPC2Dtest/3rdsdk-aitrae-tencentmapsdk

## Basic Information

- **Project Name**: 3rdSDK-AITrae-TencentMapSDK
- **Description**: 腾讯地图定位sdk示例demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-21
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 腾讯地图定位 SDK 集成与验证指南（HarmonyOS ArkTS）

## 概述
- 本指南介绍在本项目中集成并验证腾讯地图定位 SDK 的完整流程，包含依赖接入、权限配置、SDK 初始化、页面示例、构建与部署以及常见问题排查。
- 目标：实现“点击首页按钮，触发定位并显示经纬度与精度”的最小验证 Demo，确认 SDK 正常可用。

## 环境要求
- HarmonyOS 开发环境（DevEco Studio）
- 真机或具备定位能力的模拟器
- 可用的腾讯定位 SDK `API Key`

## 快速开始
1. 安装依赖：在 `entry/oh-package.json5` 添加定位 SDK 依赖并安装
   ```json
   {
     "dependencies": {
       "@tencentmap/location_sdk": "1.0.0"
     }
   }
   ```
   运行：`ohpm install`

2. 配置权限：在 `entry/src/main/module.json5` 声明网络与定位权限（模糊+精确）
   ```json
   "requestPermissions": [
     { "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" }
     }
   ]
   ```
   对应文案位于：`entry/src/main/resources/base/element/string.json`

3. 初始化 SDK：在 `entry/src/main/ets/entryability/EntryAbility.ets` 初始化并设置隐私同意
   ```ts
   import { TencentLocationSDK } from '@tencentmap/location_sdk'
   
   TencentLocationSDK.setPrivacyPolicyAgreement(true)
   TencentLocationSDK.init(this.context, 'YOUR_TENCENT_LBS_KEY')
   ```
   - 请将 `YOUR_TENCENT_LBS_KEY` 替换为你申请到的实际 Key。

4. 页面示例：`entry/src/main/ets/pages/Index.ets` 提供最小演示
   ```ts
   import { TencentLocationManager, TencentLocationRequest, TencentLocationConstant, TencentLocation, TencentLocationError } from '@tencentmap/location_sdk'
   import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit'
   
   // 点击按钮 -> 申请权限 -> 触发定位 -> 显示经纬度与精度
   const req = TencentLocationRequest
     .default()
     .setCoordinateType(TencentLocationConstant.CoordinateType.GCJ02)
     .setRequestLevel(TencentLocationConstant.RequestLevel.POI)
     .setInterval(1)
   
   // 使用 startContinuousLocation 获取一次结果后立即停止
   // 成功回调中读取 latitude/longitude/accuracy 并展示
   ```

5. 构建与部署
   - 编译：`hvigorw assembleApp`
   - 一键部署（Windows）：`./run.ps1`
   - 成功后应用将自动启动，首页点击按钮即可验证定位

## 申请 AppId 与 Key（参考官方文档要点）
- AppId：可在 `EntryAbility.onCreate` 中读取签名信息获取（示例参考官方文档）
- Key：在腾讯位置服务控制台创建应用并获取定位 SDK Key
- 依赖声明与权限配置需与文档一致，权限说明：
  - `ohos.permission.INTERNET`：网络权限
  - `ohos.permission.APPROXIMATELY_LOCATION`：模糊位置权限
  - `ohos.permission.LOCATION`：精确位置权限（需同时声明模糊位置权限）

## 常见问题与排查
- 失败错误码与含义（示例）：
  - `201`（PermissionDenied）：未授权定位权限。解决：允许系统定位权限（包含模糊与精确）。
  - `3301100`（LocationSwitchOff）：系统定位开关关闭。解决：在系统设置中打开定位服务。
  - `990100`（PrivacyPolicyNotAgreed）：未同意隐私政策。解决：确保初始化时调用了 `setPrivacyPolicyAgreement(true)`。
- 无定位结果或精度差：
  - 检查网络是否可用
  - 建议在室外测试
  - 确认授权弹窗选择“允许”
- Key 不生效：
  - 确认 Key 与应用包名/AppId 绑定一致
  - 控制台未开通或被禁用

## 参考实现要点（本项目已完成）
- 依赖接入：`entry/oh-package.json5`
- 权限声明：`entry/src/main/module.json5`
- 文案资源：`entry/src/main/resources/base/element/string.json`
- SDK 初始化：`entry/src/main/ets/entryability/EntryAbility.ets`
- 演示页面：`entry/src/main/ets/pages/Index.ets`
- 构建部署：`hvigorw assembleApp`、`./run.ps1`

## 进阶与扩展
- 单次定位：使用 `startSingleLocation(request, success, failure)`
- 连续定位：使用 `startContinuousLocation(request, success, failure)`，可设置间隔与场景参数
- POI 与地址信息：将 `RequestLevel` 设置为 `POI` 或 `ADMIN_AREA`，读取返回的 `poiList/geoAddress`
- 地理围栏与设备状态：参考 SDK 基础类文档，按需封装业务逻辑

## 变更与维护
- 若更新 SDK 版本，请同步更新依赖并验证编译与运行
- Key 与隐私协议相关逻辑建议集中管理，避免在源码中硬编码敏感信息

---
- 更多细节请参考腾讯位置服务“鸿蒙定位 SDK”官方集成指南与基础类说明。