HarmonyOS MapKit mapCommon 完全指南：LatLng、CameraPosition、MapOptions

文章目录前言一、mapCommon.LatLng经纬度坐标1.1 基本定义1.2 项目中的使用二、mapCommon.MapOptions地图初始化配置2.1 完整 MapOptions 配置2.2 项目源码对比2.3 地图类型三、mapCommon.CameraPosition相机位置3.1 相机控制原理3.2 CameraPosition 字段详解3.3 缩放级别参考四、map.CameraUpdate 与 animateCamera4.1 创建 CameraUpdate4.2 其他 CameraUpdate 创建方式五、mapCommon.MarkerOptions标记配置5.1 本项目的 Marker 配置5.2 锚点详解5.3 CollisionRule 碰撞规则六、完整地图配置实战总结前言在前面的篇章中我们学习了 MapKit 的整体接入流程。但要真正灵活运用地图需要深入理解mapCommon命名空间中的各种类型定义——它们是地图配置、相机控制、标记添加的基础数据结构。本篇系统梳理mapCommon中的核心类型结合项目MapUtil.ets中的实际代码给出每个类型字段的详细说明和可运行示例。一、mapCommon.LatLng经纬度坐标1.1 基本定义// LatLng 是地图 API 中最基础的类型interfaceLatLng{latitude:number;// 纬度-90 到 90北纬为正longitude:number;// 经度-180 到 180东经为正}// 创建坐标点consttiananmen:mapCommon.LatLng{latitude:39.9087,longitude:116.3975};constshanghai:mapCommon.LatLng{latitude:31.2304,longitude:121.4737};1.2 项目中的使用// CalculateUtil.etsletlan1:mapCommon.LatLng{latitude:lat1,longitude:long1};letlan2:mapCommon.LatLng{latitude:lat2,longitude:long2};letdistancemap.calculateDistance(lan1,lan2)/1000;// MapUtil.ets - 坐标转换lettheWGS84Position:mapCommon.LatLng{latitude:latitude,longitude:longitude};lettheGCJ02Position:mapCommon.LatLngawaitmap.convertCoordinate(mapCommon.CoordinateType.WGS84,mapCommon.CoordinateType.GCJ02,theWGS84Position);二、mapCommon.MapOptions地图初始化配置2.1 完整 MapOptions 配置constmapOptions:mapCommon.MapOptions{// 相机初始位置position:{target:{latitude:39.9087,longitude:116.3975},zoom:16,// 缩放级别3-21bearing:0,// 地图朝向0 正北90 正东tilt:0// 俯仰角0 俯视最大45度},// 地图类型mapType:mapCommon.MapType.STANDARD,// 标准地图街道// 功能开关myLocationEnabled:true,// 是否显示我的位置层蓝点myLocationControlsEnabled:true,// 是否显示定位按钮// 交互控制zoomControlsEnabled:true,// 显示缩放按钮/-scrollGesturesEnabled:true,// 允许手势平移zoomGesturesEnabled:true,// 允许手势缩放tiltGesturesEnabled:false,// 禁止手势倾斜rotateGesturesEnabled:false,// 禁止手势旋转// 边界限制可选minZoom:3,// 最小缩放级别maxZoom:21,// 最大缩放级别};2.2 项目源码对比// GasStationPage.ets 中的简化配置this.mapOptions{position:{target:{latitude:this.latitude,// 初始经纬度从定位获取longitude:this.longitude},zoom:16,// 街道级别缩放},myLocationControlsEnabled:true,// 显示定位按钮右下角mapType:mapCommon.MapType.STANDARD,// 标准街道地图};2.3 地图类型MapType 值说明STANDARD标准街道地图默认SATELLITE卫星图航拍TERRAIN地形图等高线NONE无底图只显示覆盖物三、mapCommon.CameraPosition相机位置3.1 相机控制原理地图相机是一个虚拟摄像头控制地图的中心点、缩放级别、朝向、俯角相机 │ │ 俯仰角tilt │ ↓ 观察方向 ╔═══════╗ ║ 地图 ║ ← 地图平面 ╚═══════╝ 中心点target3.2 CameraPosition 字段详解// 完整的 CameraPositionconstcameraPosition:mapCommon.CameraPosition{target:{latitude:40.0046,// 相机中心点纬度longitude:116.4823// 相机中心点经度},zoom:15.9,// 缩放级别越大越近bearing:45,// 朝向度0正北90正东180正南tilt:0// 俯仰角度0垂直俯视45斜视};3.3 缩放级别参考zoom对应视野范围适合场景3-5全国/大洲宏观选择城市8-10城市选择区域12-13区/县规划路线15-16街道本项目使用查找附近设施17-18建筑精确导航到楼19-21室内室内导航四、map.CameraUpdate 与 animateCamera4.1 创建 CameraUpdate// 本项目源码通过 newCameraPosition 创建 CameraUpdatepublicmoveToCurrentPosition(latitude:number,longitude:number,mapController:map.MapComponentController):void{letcameraPosition:mapCommon.CameraPosition{target:{latitude,longitude},zoom:15.9};// 创建 CameraUpdate 对象描述相机应该移动到哪letcameraUpdate:map.CameraUpdatemap.newCameraPosition(cameraPosition);// 执行相机动画500ms 平滑移动mapController?.animateCamera(cameraUpdate,500);}4.2 其他 CameraUpdate 创建方式// 方式1移动到指定位置zoom 不变constupdate1map.newLatLng({latitude:40.0,longitude:116.4});// 方式2移动到指定位置并设置 zoomconstupdate2map.newLatLngZoom({latitude:40.0,longitude:116.4},16);// 方式3使用完整的 CameraPositionconstupdate3map.newCameraPosition({target:{latitude:40.0,longitude:116.4},zoom:16,bearing:0,tilt:0});// 方式4缩放到特定边界constupdate4map.newLatLngBounds({latitude:39.9,longitude:116.3},// 西南角{latitude:40.1,longitude:116.5},// 东北角50// 边距vp);五、mapCommon.MarkerOptions标记配置5.1 本项目的 Marker 配置// MapUtil.ets addMapMaker 方法letmarkerOptions:mapCommon.MarkerOptions{position:{latitude:latitude,longitude:longitude},rotation:0,// 图标旋转角度度visible:true,// 是否可见zIndex:0,// 层级alpha:1,// 透明度0-1anchorU:0.5,// 水平锚点0左0.5中1右anchorV:1,// 垂直锚点0上0.5中1下clickable:true,// 是否可点击flat:true,// true固定在地图上随地图旋转false始终朝向用户icon:station.svg,// 图标文件名在 rawfile 目录下collisionRule:mapCommon.CollisionRule.NAME,// 碰撞规则};awaitmapController.addMarker(markerOptions);5.2 锚点详解anchorU 0 anchorU 0.5 anchorU 1 (左侧锚点) (中心锚点) (右侧锚点) ■ ■ ■ │ │ │ ▼ 标记点 ▼ 标记点 ▼ 标记点 • • • anchorV 1底部锚点标记图标的底部对准坐标点 anchorV 0.5中心锚点标记图标的中心对准坐标点本项目anchorV: 1表示图标底部指向位置坐标点像一个图钉。5.3 CollisionRule 碰撞规则CollisionRule说明NONE不参与碰撞检测始终显示NAME与同名标记碰撞时隐藏后者本项目使用STRICT与任何标记碰撞时隐藏六、完整地图配置实战EntryComponentstruct MapConfigDemo{privatemapOptions:mapCommon.MapOptions{};privatecallback:AsyncCallbackmap.MapComponentControllerasync(err,mapController){if(err){console.error(地图初始化失败${err.message});return;}// 功能配置 // 开启定位层显示用户蓝点mapController.setMyLocationEnabled(true);// 事件监听 mapController.on(mapClick,(latLng:mapCommon.LatLng){console.log(点击地图${latLng.latitude.toFixed(4)},${latLng.longitude.toFixed(4)});});mapController.on(cameraIdle,(){// 地图移动停止时获取当前中心点constcentermapController.getCameraPosition();console.log(当前地图中心${center?.target.latitude.toFixed(4)});});// 添加标记 awaitmapController.addMarker({position:{latitude:39.9087,longitude:116.3975},icon:station.svg,anchorU:0.5,anchorV:1,clickable:true,visible:true,alpha:1,zIndex:1,flat:true,rotation:0,collisionRule:mapCommon.CollisionRule.NONE});// 移动相机到初始位置 constupdatemap.newLatLngZoom({latitude:39.9087,longitude:116.3975},16);mapController.animateCamera(update,500);};aboutToAppear():void{this.mapOptions{position:{target:{latitude:39.9087,longitude:116.3975},zoom:14,bearing:0,tilt:0},mapType:mapCommon.MapType.STANDARD,myLocationControlsEnabled:true,zoomControlsEnabled:true,};}build(){Stack(){MapComponent({mapOptions:this.mapOptions,mapCallback:this.callback,}).width(100%).height(100%)}.width(100%).height(100%)}}总结mapCommon命名空间是 HarmonyOS MapKit 的类型基础LatLng是所有坐标操作的基本单元MapOptions配置地图的初始状态CameraPosition描述地图视角CameraUpdateanimateCamera实现平滑相机动画MarkerOptions控制标记点的外观和交互行为。深入理解这些类型的字段含义是精准控制地图行为、实现复杂地图交互的前提。