大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在地图类或者生活服务类应用中,有一个非常经典的交互场景:用户在搜索框中输入“咖啡店”、“加油站”或者“洗手间”,点击搜索后,地图上不仅要出现一堆定位大头针(Marker),地图视角还要自动缩放和平移,刚好把所有搜索结果都展示在屏幕内。如果点击某一个大头针,还能弹出这个地点的详细名称和地址。

这个过程看似一气呵成,但在 HarmonyOS 开发中,它实际上是由位置搜索能力与地图渲染能力组合而成的。本文将以 HarmonyOS NEXT 中的 @kit.SiteKit(位置服务)和 @kit.MapKit(地图服务)为例,拆解这个“POI 搜索与地图展示”的完整开发流程。

一、这个能力到底解决什么问题

在地图开发语境下,POI(Point of Interest,兴趣点) 指的是地图上有意义的特定地点,比如商铺、景点、公交站等。

当我们输入关键词并呈现在地图上时,底层实际上解决了两个独立的问题:

  1. 数据问题(Site Kit):将用户的模糊文本(“咖啡店”),转化为一组包含精确经纬度、名称、地址的结构化位置数据。
  2. 渲染问题(Map Kit):将这组经纬度数据,转化为地图上的视觉元素(Marker),并通过调整地图相机的缩放级别和中心点(CameraUpdate),让这些元素聚焦在用户眼前。

这两个环节通过一段完整的业务逻辑串联,就构成了日常使用的地图搜索功能。

二、先把官方规则弄清楚

在写业务代码之前,按照官方接口约束,我们需要先理清几个前提条件:

  • 依赖 Kit:需导入 @kit.SiteKit 用于文本搜索,导入 @kit.MapKit 用于地图渲染。
  • 工程配置:使用这两种能力,必须在华为 AppGallery Connect (AGC) 上创建项目、开启“地图服务”和“位置服务”,并获取对应的 Client ID / API Key。
  • 权限要求:至少需要在 module.json5 中声明 ohos.permission.INTERNET(发起搜索网络请求及加载地图瓦片)。如果需要基于用户当前位置进行周边搜索,还需要申请 ohos.permission.APPROXIMATELY_LOCATION 等定位权限。本文聚焦搜索与展示,主要依赖网络权限。
  • 计费与配额:官方文档明确提示,Site Kit 的搜索接口和 Map Kit 的调用都有配额限制,实际商用项目中需要关注 AGC 控制台的调用次数。

三、核心代码实现

我们直接进入正题,构造一个包含搜索框和地图的最小化场景。

目标效果:

  1. 用户输入关键词后触发搜索。
  2. 获取 POI 列表,在地图上批量打点。
  3. 地图自动计算所有点的边界,移动视角(Camera)适配展示范围。
  4. 处理无结果或网络异常等边界情况。

以下是按照官方文档接口组织的核心实现代码:

import { site } from '@kit.SiteKit';
import { MapComponent, mapCommon, map } from '@kit.MapKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct PoiSearchMapPage {
  @State keyword: string = '咖啡店';
  private mapController: map.MapComponentController | null = null;
  private markers: map.Marker[] = []; // 保存当前地图上的 Marker 实例

  // 地图初始化回调
  private mapCallback = async (err: BusinessError, mapController: map.MapComponentController) => {
    if (!err) {
      this.mapController = mapController;
    }
  };

  build() {
    Column() {
      // 搜索区域
      Row() {
        TextInput({ text: this.keyword, placeholder: '请输入搜索关键词' })
          .onChange((value: string) => {
            this.keyword = value;
          })
          .layoutWeight(1)
        
        Button('搜索')
          .onClick(() => {
            this.searchAndDisplayPoi();
          })
          .margin({ left: 10 })
      }
      .width('100%')
      .padding(15)

      // 地图显示区域
      MapComponent({ mapOptions: {
        position: {
          target: {
            latitude: 39.9, // 默认中心点,例如北京
            longitude: 116.4
          },
          zoom: 10
        }
      }, mapCallback: this.mapCallback })
      .width('100%')
      .layoutWeight(1)
    }
    .width('100%')
    .height('100%')
  }

  // 执行 POI 搜索并在地图上展示
  private async searchAndDisplayPoi() {
    if (!this.keyword) {
      promptAction.showToast({ message: '请输入关键词' });
      return;
    }

    // 1. 构造搜索请求参数
    let request: site.TextSearchRequest = {
      query: this.keyword,
      pageSize: 10,
      pageIndex: 1
    };

    try {
      // 2. 调用位置搜索接口
      const response: site.SiteSearchResponse = await site.textSearch(request);
      
      // 3. 处理无结果情况
      if (!response.sites || response.sites.length === 0) {
        promptAction.showToast({ message: '未找到相关结果' });
        return;
      }

      // 4. 清理旧数据,绘制新结果并移动地图
      this.updateMapWithSites(response.sites);

    } catch (err) {
      // 8. 网络错误或服务异常处理
      let error = err as BusinessError;
      promptAction.showToast({ message: `搜索失败: ${error.code} - ${error.message}` });
    }
  }

  private async updateMapWithSites(sites: site.Site[]) {
    if (!this.mapController) return;

    // 清除上一次搜索遗留的 Marker
    this.markers.forEach(marker => marker.remove());
    this.markers = [];

    // 用于计算所有 POI 点的最外围边界
    let minLat = 90, maxLat = -90, minLng = 180, maxLng = -180;

    // 5. 批量添加 Marker
    for (let i = 0; i < sites.length; i++) {
      let currentSite = sites[i];
      if (!currentSite.location) continue;

      let position: mapCommon.LatLng = {
        latitude: currentSite.location.latitude,
        longitude: currentSite.location.longitude
      };

      // 更新经纬度极值
      minLat = Math.min(minLat, position.latitude);
      maxLat = Math.max(maxLat, position.latitude);
      minLng = Math.min(minLng, position.longitude);
      maxLng = Math.max(maxLng, position.longitude);

      // 在地图上添加 Marker,自带默认 InfoWindow
      let marker = await this.mapController.addMarker({
        position: position,
        title: currentSite.name,               // 6. 点击 Marker 弹出的标题
        snippet: currentSite.formatAddress     // 点击 Marker 弹出的详细地址
      });
      
      this.markers.push(marker);
    }

    // 7. 地图移动到搜索范围
    let bounds: mapCommon.LatLngBounds = {
      northeast: { latitude: maxLat, longitude: maxLng },
      southwest: { latitude: minLat, longitude: minLng }
    };
    
    // 生成相机更新对象,设置边缘 padding 为 50 像素
    let cameraUpdate = map.CameraUpdateFactory.newLatLngBounds(bounds, 50);
    this.mapController.animateCamera(cameraUpdate, 1000); // 1000ms 动画平滑过渡
  }
}

四、几个关键点拆开看

这段代码解决的核心问题并不在单个 API 上,而是 API 组合时的状态流转,这里挑选 4 个核心环节单独说明。

1. 批量添加 Marker 时的状态管理

每次发起新的搜索,地图不应该保留上一次搜索的“旧点”。从官方接口设计来看,添加 Marker 后返回的 map.Marker 对象句柄非常重要。
代码中专门使用了一个 this.markers 数组来保存这些实例。在下次搜索前,必须遍历这个数组调用 marker.remove(),防止地图上积累大量无用节点导致内存泄漏或画面杂乱。

2. 为什么需要手动计算极值(LatLngBounds)

site.textSearch 会返回一组散布在各个地方的坐标。为了让用户一屏看到所有结果,必须利用 mapCommon.LatLngBounds。
我们需要手动遍历所有的结果点,找出最大的经度/纬度和最小的经度/纬度,从而构造出一个刚好能包围这些点的矩形边界(东北角和西南角)。然后调用 newLatLngBounds(bounds, 50),其中的 50 是预留的屏幕边缘 Padding(单位通常是 vp),防止某些 Marker 贴着屏幕边缘显示不全。

3. Marker 的点击事件与默认弹窗

代码中并没有显式编写点击 Marker 弹出详情页的逻辑。这是因为 Map Kit 的 addMarker 方法中,只要配置了 title 和 snippet 属性,底层会自动为你接管点击事件,并弹出一个标准的 InfoWindow 显示名字和地址。
实际开发时,如果默认 UI 无法满足要求,可以通过 this.mapController.setCustomInfoWindow() 结合 @Builder 来自定义弹窗样式。

4. 没有结果与网络错误如何区分

通过 Site Kit 发起搜索时,可能会遇到几种完全不同的异常情况,必须区分处理:

  • response.sites 为空数组:属于正常业务逻辑,说明网络通畅,服务正常,只是该区域真的没有你搜索的 POI(比如你在沙漠里搜“咖啡店”)。
  • 进入 catch 分支并抛出 BusinessError:属于异常逻辑,最典型的是网络不通、或者鉴权失败(比如 Client ID 未配置,或者对应的 AGC 应用没开通权限),错误码可以直接指导我们排查方向。

五、容易踩坑的地方

按照上面的思路实现,大部分时候跑起来会很顺利,但也极容易在这两个地方卡住:

第一:Client ID 未正确初始化导致鉴权 401 错误。
这是由于 HarmonyOS 的地图和位置服务强依赖华为云服务鉴权。不仅要在 AGC 下载 agconnect-services.json 放入工程,还必须在 module.json5 的 metadata 中正确配置 client_id。如果这里漏了,无论代码写得多好,site.textSearch 调用必然抛出鉴权异常。

第二:过快的搜索请求可能导致限流或报错。
用户在搜索框中如果连续快速删除、输入,会触发高频的 onChange 回调。实际项目中千万不要在 onChange 里直接调用 site.textSearch,否则不仅会浪费云端 API 配额,还很容易触发 QPS(每秒查询率)超限报错。建议像示例代码一样通过点击“搜索”按钮触发,或者在 onChange 中增加 500ms 的防抖(Debounce)处理。

六、实际项目中怎么排查地图搜不到数据的问题?

当你发现搜索“咖啡店”但地图没反应时,可以按照以下顺序进行归因排查:

  1. 先看日志(确认是否抛异常):检查 catch 块是否捕获了 BusinessError。如果有错,直接查对应错误码(如网络异常、鉴权异常)。
  2. 再看返回结果(确认 Site Kit 工作正常):打断点或者 console.info 打印 response.sites 的长度。如果长度大于 0,说明 Site Kit 数据请求这一环是完全正常的。
  3. 接着看地图控制器(确认 Map Kit 渲染状态):确认 mapCallback 是否成功执行并拿到了非空的 mapController。如果不为空,检查 marker.remove() 是否误删了刚加进去的点。
  4. 最后看相机控制(确认是否只是没看到):有时候点其实已经加到地图上了,但是因为 animateCamera 的范围计算错误,或者传了错误的坐标参数,导致镜头移动到了大洋中心,让你产生“没有结果”的错觉。可以通过拖拽地图看看默认中心点附近有没有 Marker 出现。

通过这种方式组合 @kit.SiteKit 和 @kit.MapKit,我们就能以较低的代码成本实现一个标准的 POI 搜索展示场景。如果你正在开发包含地图功能的应用,可以重点检查一下项目中管理 Marker 生命周期的代码,因为频繁的搜索与清理逻辑往往是引发地图卡顿与内存问题的关键区域。

参考资料

  1. 《Map Kit 开发指南 - 绘制Marker》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/map-draw-marker-V5
  2. 《Site Kit 开发指南 - 关键字搜索》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/site-text-search-V5

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐