在上一篇文章中介绍了Map Kit的开发准备。本章将介绍如何使用地图组件MapComponent和MapComponentController呈现地图，包括地图初始化、地图属性设置、前后台切换、深色模式、室内图、3D地球、城市灯光效果等。

一、地图显示

1.1 版本特性

版本	新增功能
5.0.3(15)	Logo缩放功能、3D地球功能
5.1.1(19)	室内图功能、设置比例尺单位功能
6.0.0(20)	设置地图语言功能
6.1.0(23)	设置3D地图城市灯光效果

1.2 核心组件

组件	说明
MapComponent	地图组件，用于显示地图
MapComponentController	地图组件的主要功能入口类，用来操作地图

MapComponentController功能包括：

• 地图类型切换（标准地图、空地图）

• 改变地图状态（中心点坐标和缩放级别）

• 添加点标记（Marker）

• 绘制几何图形（MapPolyline、MapPolygon、MapCircle）

• 监听各类事件

二、接口说明

接口	说明
mapCommon.MapOptions	提供Map组件初始化的属性
MapComponent(mapOptions, mapCallback)	地图组件
map.MapComponentController	地图组件的主要功能入口类，用来操作地图

三、开发步骤

3.1 导入模块

import { MapComponent, mapCommon, map } from '@kit.MapKit';
import { AsyncCallback } from '@kit.BasicServicesKit';

3.2 初始化地图

@Entry
@Component
struct HuaweiMapDemo {
  private mapOptions?: mapCommon.MapOptions;
  private callback?: AsyncCallback<map.MapComponentController>;
  private mapController?: map.MapComponentController;
  private mapEventManager?: map.MapEventManager;

  aboutToAppear(): void {
    // 地图初始化参数，设置地图中心点坐标及层级
    this.mapOptions = {
      position: {
        target: {
          latitude: 39.9,
          longitude: 116.4
        },
        zoom: 10
      }
    };

    // 地图初始化的回调
    this.callback = async (err, mapController) => {
      if (!err) {
        this.mapController = mapController;
        this.mapEventManager = this.mapController.getEventManager();
        this.mapEventManager.on("mapLoad", () => {
          console.info("on-mapLoad");
        });
      } else {
        console.error(`Failed to initialize the map, code: ${err.code}`);
      }
    };
  }

  onPageShow(): void {
    // 地图切换到前台
    if (this.mapController) {
      this.mapController.show();
    }
  }

  onPageHide(): void {
    // 地图切换到后台
    if (this.mapController) {
      this.mapController.hide();
    }
  }

  build() {
    Stack() {
      MapComponent({ mapOptions: this.mapOptions, mapCallback: this.callback })
        .width('100%')
        .height('100%');
    }
    .height('100%')
  }
}

3.3 MapOptions属性

属性	描述	默认值
mapType	地图类型	STANDARD
position	地图相机位置	-
bounds	地图展示框	-
minZoom	地图最小层级	2
maxZoom	地图最大层级	20
rotateGesturesEnabled	是否支持旋转手势	true
scrollGesturesEnabled	是否支持滑动手势	true
zoomGesturesEnabled	是否支持缩放手势	true
tiltGesturesEnabled	是否支持倾斜手势	true
zoomControlsEnabled	是否展示缩放控件	true
myLocationControlsEnabled	是否展示我的位置按钮	false
compassControlsEnabled	是否展示指南针控件	true
scaleControlsEnabled	是否展示比例尺	false
alwaysShowScaleEnabled	是否始终显示比例尺	false
padding	设置地图和边界的距离	-
styleId	自定义样式ID	-
dayNightMode	日间夜间模式	DAY
logoScale	Logo缩放比例	1
sphereEnabled	是否开启3D地球效果	false
indoorMapEnabled	是否开启室内图	false
scaleUnit	地图比例尺公英制单位	METRIC_UNIT（公制）

四、常用功能

4.1 展示我的位置按钮

this.mapOptions = {
  position: {
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 10
  },
  myLocationControlsEnabled: true  // 展示我的位置按钮
};

4.2 展示比例尺

this.mapOptions = {
  position: {
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 10
  },
  scaleControlsEnabled: true  // 展示比例尺
};

4.3 开启3D建筑图层

// 开启3D建筑图层
this.mapController.setBuildingEnabled(true);

// 将缩放层级调整为16级或以上，向上滑动倾斜地图可看到3D建筑效果

4.4 地图前后台切换

// 页面显示时（前台）
onPageShow(): void {
  if (this.mapController) {
    this.mapController.show();  // 申请资源
  }
}

// 页面隐藏时（后台）
onPageHide(): void {
  if (this.mapController) {
    this.mapController.hide();  // 释放资源
  }
}

五、深色模式

5.1 方式一：初始化地图时设置

this.mapOptions = {
  position: {
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 10
  },
  dayNightMode: mapCommon.DayNightMode.NIGHT  // 夜间模式
};

DayNightMode枚举：

值	说明
DAY	日间模式（默认）
NIGHT	夜间模式
AUTO	自动模式（跟随系统深色开关）

5.2 方式二：创建地图后设置

// 设置地图为自动模式
this.mapController.setDayNightMode(mapCommon.DayNightMode.AUTO);

六、室内图

6.1 初始化地图时开启

this.mapOptions = {
  position: {
    target: { latitude: 31.979227, longitude: 118.762245 },
    zoom: 18
  },
  indoorMapEnabled: true  // 开启室内图功能
};

注意：仅17级及以上地图层级可见室内图和楼层调节控件。

6.2 创建地图后开启

// 开启室内图功能
this.mapController.setIndoorMapEnabled(true);

// 查询当前室内图开启状态
let isIndoorMapEnabled: boolean = this.mapController.isIndoorMapEnabled();

// 设置楼层调节控件的位置
this.mapController.setFloorControlsPosition({
  positionX: 500,
  positionY: 500
});

// 切换楼层（建筑物id, 楼层如'1F'、'B1'等）
this.mapController.switchIndoorMapFloor('822588304363886720', '3F');

6.3 室内图事件监听

// 进入室内图监听
this.mapEventManager.on("indoorMapEnter", (indoorMapInfo: map.IndoorMapInfo) => {
  console.info("on-indoorMapEnter");
});

// 退出室内图监听
this.mapEventManager.on("indoorMapExit", () => {
  console.info("on-indoorMapExit");
});

七、Logo缩放比例

7.1 初始化地图时设置

this.mapOptions = {
  position: {
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 10
  },
  logoScale: 0.9  // 取值范围[0.8, 1]
};

7.2 创建地图后设置

// 设置Logo缩放比例
this.mapController.setLogoScale(0.9);

// 获取当前Logo缩放比例
let logoScale: number = this.mapController.getLogoScale();

八、3D地球

8.1 初始化地图时开启

this.mapOptions = {
  position: {
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 2
  },
  sphereEnabled: true  // 开启3D地球
};

注意：开启3D地球后，当层级缩小到小于4时，可以清晰地看到3D地球。

8.2 创建地图后开启

// 开启3D地球
this.mapController.setSphereEnabled(true);

// 获取3D地球的开启状态
let result: boolean = this.mapController.isSphereEnabled();

九、城市灯光效果（6.1.0+）

// 开启城市灯光效果（参数：enabled, animateDuration, cityLight）
this.mapController.setSphereEnabled(true, 2000, true);