鸿蒙 Map Kit 实战：调用华为地图服务，开发一个“周边美食搜索”原子化服务卡片

标签：#HarmonyOS #MapKit #SiteKit #元服务 #ArkTS #LBS

🍱 前言：当 LBS 遇上万能卡片

传统的找店流程：解锁手机 -> 找 App -> 点击启动 -> 等广告 -> 搜索“美食” -> 筛选附近。
鸿蒙元服务流程：点亮屏幕 -> 看一眼桌面卡片。

这背后的技术链路其实并不复杂：

定位：获取用户当前经纬度。
搜索 (Site Kit)：根据坐标搜索周边 POI (兴趣点)。
展示 (Form)：将数据渲染到轻量级的卡片上。
导航 (Map Kit)：点击卡片，拉起地图进行导航。

数据流转图 (Mermaid):

🛠️ 一、准备工作：AGC 配置

在使用华为地图服务前，必须在 AppGallery Connect (AGC) 上开通权限。

注册开发者账号：登录华为开发者联盟。
创建项目与应用：获取client_id。
开启 API：在“我的项目” -> “API管理”中，开启Map Kit和Site Kit。
配置工程：在module.json5中配置client_id。

"module": { "metadata": [ { "name": "client_id", "value": "你的_CLIENT_ID" // ⚠️ 别忘了这个！ } ] }

📡 二、核心逻辑：获取定位与周边搜索

我们需要在EntryFormAbility(卡片的生命周期管理类) 或者后台 Service 中处理逻辑。为了演示清晰，我们直接看核心的 API 调用。

首先，申请权限ohos.permission.LOCATION和ohos.permission.APPROXIMATELY_LOCATION。

1. 引入模块

import{site}from'@kit.MapKit';// 鸿蒙 Next 中 Site Kit 已集成在 Map Kit 命名空间下import{geoLocationManager}from'@kit.LocationKit';

2. 封装搜索函数

我们需要调用 Site Kit 的nearbySearch接口。

asyncfunctionsearchNearbyFood(lat:number,lng:number){// 1. 构建搜索请求letsearchRequest:site.NearbySearchRequest={location:{latitude:lat,longitude:lng},query:"美食",// 搜索关键词radius:1000,// 搜索半径 1公里pageSize:4,// 卡片位置有限，只拿前4个pageIndex:1,poiType:[site.LocationType.RESTAURANT]// 指定类型为餐厅};try{// 2. 调用华为 Site Kitletresult=awaitsite.nearbySearch(searchRequest);if(result.sites){// 3. 转换数据格式，用于卡片渲染letfoodList=result.sites.map(item=>{return{name:item.name,address:item.formatAddress,distance:item.distance,// 如果有图片 url，也可以放这里};});returnfoodList;}}catch(err){console.error("Search failed: "+JSON.stringify(err));}return[];}

🖼️ 三、界面实现：ArkTS 卡片 UI

卡片 UI (Widget) 和普通 Page 的写法略有不同，它更轻量。

FoodCard.ets:

@Entry@Componentstruct FoodCard{// 接收 FormExtensionAbility 传来的数据@LocalStorageProp('foodList')foodList:Array<any>=[];build(){Column(){Text('附近美食推荐').fontSize(14).fontWeight(FontWeight.Bold).padding({left:12,top:10,bottom:5}).width('100%')if(this.foodList.length===0){Text('正在定位中...').fontSize(12).margin(10)}else{// 使用 Grid 布局展示 4 个餐厅Grid(){ForEach(this.foodList,(item:any)=>{GridItem(){Column(){// 模拟餐厅图标Image($r('app.media.icon_food')).width(30).height(30).borderRadius(8)Text(item.name).fontSize(10).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis}).margin({top:4})Text(`${item.distance}m`).fontSize(9).fontColor(Color.Gray)}// 点击事件：拉起主应用，并传递参数.onClick(()=>{postCardAction(this,{action:'router',abilityName:'EntryAbility',params:{targetPage:'MapPage',poiName:item.name,lat:item.location.latitude,lng:item.location.longitude}});}).backgroundColor('#F5F5F5').borderRadius(8).padding(8).width('100%').height(80)}})}.columnsTemplate('1fr 1fr 1fr 1fr')// 4列.columnsGap(8).padding(12)}}.width('100%').height('100%').backgroundColor(Color.White)}}

🗺️ 四、落地页：Map Kit 导航展示

当用户点击卡片上的餐厅时，跳转到 App 内的MapPage。这里我们需要使用 Map Component 展示具体位置。

MapPage.ets:

import{MapComponent,mapCommon,map}from'@kit.MapKit';@Entry@Componentstruct MapPage{@StatemapController:map.MapComponentController=newmap.MapComponentController();// 从路由参数中获取的目标坐标targetLat:number=0;targetLng:number=0;targetName:string="";aboutToAppear(){// 获取路由参数逻辑 (略)}build(){Stack(){// 地图组件MapComponent({mapOptions:{position:{target:{latitude:this.targetLat,longitude:this.targetLng},zoom:15// 缩放级别}},mapCallback:(err,controller)=>{if(!err){this.mapController=controller;// 地图加载完成后，添加一个标记this.addMarker();}}}).width('100%').height('100%')}}addMarker(){letmarkerOptions:mapCommon.MarkerOptions={position:{latitude:this.targetLat,longitude:this.targetLng},title:this.targetName,clickable:true};this.mapController.addMarker(markerOptions);}}

⚠️ 五、避坑指南

Client ID 报错：如果你发现地图白屏或者搜索报错 6004/010001，99% 是因为module.json5里的client_id没配对，或者指纹证书（SHA256）没在 AGC 后台录入。
定位延迟：在卡片上直接做实时定位（GPS）非常耗电且慢。最佳实践是：App 主程序启动时缓存最后一次位置，或者在 FormAbility 的onUpdateForm中使用“上次已知位置”快速刷新，再异步发起精确定位更新。
模拟器问题：DevEco Studio 的模拟器默认定位可能在海上。记得在模拟器的设置里手动 Mock 一个经纬度（比如深圳坂田）。