HarmonyOS中高德地图第一篇：高德地图SDK集成与初始化

第一篇：高德地图SDK集成与初始化

本篇教程将带你完成高德地图HarmonyOS SDK的集成配置，这是后续所有功能的基础。

学习目标

• 了解高德地图SDK的组成模块
• 完成SDK的安装和配置
• 申请并配置API Key
• 实现隐私政策合规调用

1. SDK模块介绍

高德地图HarmonyOS SDK主要包含以下模块：

模块	包名	功能
地图SDK	@amap/amap_lbs_map3d	地图显示、标记、覆盖物等
搜索SDK	@amap/amap_lbs_search	POI搜索、路线规划、地理编码等
定位SDK	@amap/amap_lbs_location	高精度定位（可选）
公共模块	@amap/amap_lbs_common	隐私政策、公共类型定义

2. 安装SDK

2.1 修改根目录 oh-package.json5

在项目根目录的 oh-package.json5 中添加依赖：

{
  "modelVersion": "6.0.0",
  "description": "高德地图开发教程",
  "dependencies": {
    "@amap/amap_lbs_map3d": "^2.1.0",
    "@amap/amap_lbs_search": "^1.0.8",
    "@amap/amap_lbs_common": "^1.0.3"
  }
}

2.2 修改entry模块 oh-package.json5

在 entry/oh-package.json5 中添加依赖：

{
  "name": "entry",
  "version": "1.0.0",
  "description": "高德地图开发教程",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "@amap/amap_lbs_map3d": "^2.1.0",
    "@amap/amap_lbs_search": "^1.0.8",
    "@amap/amap_lbs_common": "^1.0.3"
  }
}

2.3 同步依赖

点击DevEco Studio右上角的 Sync Now 按钮，或使用命令：

ohpm install

3. 申请API Key

3.1 注册高德开发者账号

1. 访问 高德开放平台
2. 点击右上角「注册」创建账号
3. 完成实名认证（个人开发者/企业开发者）

3.2 创建应用

1. 登录后进入「控制台」
2. 点击「应用管理」→「我的应用」→「创建新应用」
3. 填写应用名称和类型

3.3 添加Key

1. 在创建的应用下点击「添加Key」
2. 选择服务平台：HarmonyOS
3. 填写必要信息：
   • Key名称: 自定义名称
   • Package Name : 与build-profile.json5中的bundleName一致
   • SHA256指纹: 签名证书的SHA256指纹

3.4 获取签名证书指纹

在DevEco Studio中：

1. 打开 Build → Generate Key and CSR
2. 创建或选择已有的签名证书
3. 查看证书详情获取SHA256指纹

或使用命令行：

keytool -list -v -keystore your_keystore.p12 -storepass your_password

4. 配置API Key

4.1 创建常量配置文件

创建文件 entry/src/main/ets/common/Constants.ets：

/**
 * 应用常量配置
 */
export class Constants {
  /**
   * 高德地图API Key
   * 请替换为你在高德开放平台申请的Key
   */
  static readonly AMAP_API_KEY: string = "你的API_Key";
  
  /**
   * 默认地图中心点（北京天安门）
   */
  static readonly DEFAULT_CENTER_LAT: number = 39.909187;
  static readonly DEFAULT_CENTER_LNG: number = 116.397451;
  
  /**
   * 默认缩放级别
   */
  static readonly DEFAULT_ZOOM: number = 15;
}

5. 配置隐私政策（必须）

根据国家法规要求，使用高德SDK前必须进行隐私政策合规配置。

5.1 在EntryAbility中配置

修改 entry/src/main/ets/entryability/EntryAbility.ets：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { MapsInitializer } from '@amap/amap_lbs_map3d';
import { ServiceSettings } from '@amap/amap_lbs_search';
import { 
  AMapPrivacyShowStatus, 
  AMapPrivacyInfoStatus, 
  AMapPrivacyAgreeStatus 
} from '@amap/amap_lbs_common';
import { Constants } from '../common/Constants';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'EntryAbility', 'Ability onCreate');
    
    // 初始化高德地图SDK
    this.initAMapSDK();
  }

  /**
   * 初始化高德地图SDK
   */
  private initAMapSDK(): void {
    try {
      // 1. 设置隐私政策合规（必须在初始化之前调用）
      // 地图SDK隐私政策
      MapsInitializer.updatePrivacyShow(
        AMapPrivacyShowStatus.DidShow,      // 已向用户展示隐私政策
        AMapPrivacyInfoStatus.DidContain    // 隐私政策中包含高德SDK说明
      );
      MapsInitializer.updatePrivacyAgree(
        AMapPrivacyAgreeStatus.DidAgree     // 用户已同意隐私政策
      );
      
      // 搜索SDK隐私政策
      ServiceSettings.updatePrivacyShow(
        AMapPrivacyShowStatus.DidShow,
        AMapPrivacyInfoStatus.DidContain,
        this.context
      );
      ServiceSettings.updatePrivacyAgree(
        AMapPrivacyAgreeStatus.DidAgree,
        this.context
      );
      
      // 2. 设置API Key
      MapsInitializer.setApiKey(Constants.AMAP_API_KEY);
      
      // 3. 开启调试模式（发布时建议关闭）
      MapsInitializer.setDebugMode(true);
      
      hilog.info(0x0000, 'EntryAbility', 'AMap SDK initialized successfully');
    } catch (error) {
      hilog.error(0x0000, 'EntryAbility', 'AMap SDK init failed: ' + JSON.stringify(error));
    }
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0000, 'EntryAbility', 'Ability onWindowStageCreate');

    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'EntryAbility', 'Failed to load content: ' + JSON.stringify(err));
        return;
      }
      hilog.info(0x0000, 'EntryAbility', 'Content loaded successfully');
    });
  }

  onForeground(): void {
    hilog.info(0x0000, 'EntryAbility', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(0x0000, 'EntryAbility', 'Ability onBackground');
  }

  onDestroy(): void {
    hilog.info(0x0000, 'EntryAbility', 'Ability onDestroy');
  }
}

6. 配置权限

修改 entry/src/main/module.json5，添加必要权限：

{
  "module": {
    "name": "entry",
    "type": "entry",
    // ... 其他配置
    
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:permission_internet_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:permission_location_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:permission_location_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

6.1 添加权限说明字符串

在 entry/src/main/resources/base/element/string.json 中添加：

{
  "string": [
    {
      "name": "permission_internet_reason",
      "value": "用于加载地图数据和进行网络请求"
    },
    {
      "name": "permission_location_reason",
      "value": "用于获取您的位置信息，提供定位服务"
    }
  ]
}

7. 验证配置

创建一个简单的测试页面验证SDK是否配置成功。

在 entry/src/main/ets/pages/Index.ets 中：

import { MapsInitializer } from '@amap/amap_lbs_map3d';
import { Constants } from '../common/Constants';

@Entry
@Component
struct Index {
  @State sdkVersion: string = '检测中...';
  @State initStatus: string = '检测中...';

  aboutToAppear(): void {
    this.checkSDKStatus();
  }

  private checkSDKStatus(): void {
    try {
      // 检查API Key是否已设置
      if (Constants.AMAP_API_KEY && Constants.AMAP_API_KEY !== '你的API_Key') {
        this.initStatus = '✅ SDK配置成功';
        this.sdkVersion = '高德地图SDK已就绪';
      } else {
        this.initStatus = '❌ 请配置API Key';
        this.sdkVersion = '请在Constants.ets中设置AMAP_API_KEY';
      }
    } catch (error) {
      this.initStatus = '❌ SDK初始化失败';
      this.sdkVersion = String(error);
    }
  }

  build() {
    Column() {
      Text('高德地图SDK配置检测')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 50, bottom: 30 })

      Column() {
        Text('初始化状态')
          .fontSize(16)
          .fontColor('#666')
        Text(this.initStatus)
          .fontSize(18)
          .fontWeight(FontWeight.Medium)
          .margin({ top: 8 })
      }
      .width('90%')
      .padding(20)
      .backgroundColor('#f5f5f5')
      .borderRadius(12)
      .margin({ bottom: 20 })

      Column() {
        Text('SDK信息')
          .fontSize(16)
          .fontColor('#666')
        Text(this.sdkVersion)
          .fontSize(14)
          .margin({ top: 8 })
      }
      .width('90%')
      .padding(20)
      .backgroundColor('#f5f5f5')
      .borderRadius(12)

      Text('完成配置后，请继续学习下一篇教程')
        .fontSize(14)
        .fontColor('#999')
        .margin({ top: 40 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Start)
  }
}

8. 运行测试

1. 连接真机或启动模拟器
2. 点击运行按钮
3. 查看页面上的状态显示
4. 如果显示"SDK配置成功"，说明配置完成

常见问题

Q1: 安装依赖失败？

A: 检查网络连接，确保ohpm源可访问。也可以尝试清除缓存后重新安装。

Q2: API Key无效？

A: 检查以下几点：

• Key是否已启用
• Package Name是否与项目bundleName一致
• SHA256指纹是否正确

Q3: 隐私政策必须调用吗？

A: 是的，这是高德SDK的合规要求，不调用将无法正常使用SDK功能。

本篇小结

本篇教程我们完成了：

• ✅ 高德地图SDK的安装
• ✅ API Key的申请和配置
• ✅ 隐私政策的合规调用
• ✅ 必要权限的声明

下一篇我们将学习如何显示第一个地图界面。 developer.huawei.com/consumer/cn...

源代码地址

gitcode.com/daleishen/g...