1. 配置 Site Kit 依赖

在 oh-package.json5 中确认已引入 MapKit：

{
  "dependencies": {
    "@kit.MapKit": "^5.0.0"
  }
}

2. 定义 POI 数据接口

// services/HuaweiPoiSearchService.ets
import { site } from '@kit.MapKit'
import { BusinessError } from '@kit.BasicServicesKit'

/**
 * POI 位置接口
 */
export interface HuaweiPoiLocation {
  latitude: number
  longitude: number
}

/**
 * POI 营业时间接口
 */
export interface HuaweiPoiOpeningHours {
  periods?: Array<{
    open?: { day?: number, time?: string }
    close?: { day?: number, time?: string }
  }>
  openNow?: boolean
}

/**
 * POI 项目接口
 */
export interface HuaweiPoiItem {
  // 基础信息
  poiId: string
  title: string
  snippet: string        // 地址
  typeDes: string        // 类型描述
  
  // 位置信息
  latitude: number
  longitude: number
  distance: number       // 距离（米）
  
  // 联系信息
  tel?: string           // 电话
  website?: string       // 网站
  
  // 评价信息
  rating?: string        // 评分
  starRating?: string    // 星级
  
  // 营业信息
  openingHours?: HuaweiPoiOpeningHours
  businessStatus?: string
  
  // 地址信息
  formatAddress?: string
  
  // 分类信息
  poiTypes?: string[]
}

/**
 * POI 搜索结果接口
 */
export interface HuaweiPoiSearchResult {
  pois: HuaweiPoiItem[]
  totalCount: number
  pageNum: number
  pageSize: number
}

/**
 * POI 搜索参数接口
 */
export interface HuaweiPoiSearchParams {
  keyword: string        // 搜索关键词
  latitude: number       // 中心点纬度
  longitude: number      // 中心点经度
  radius: number         // 搜索半径（米）
  pageNum?: number       // 页码（默认1）
  pageSize?: number      // 每页数量（默认20）
}

3. 实现 POI 搜索服务

/**
 * Site Kit POI 搜索服务类
 */
export class HuaweiPoiSearchService {
  
  // 默认配置
  private static readonly DEFAULT_PAGE_SIZE: number = 20
  private static readonly DEFAULT_LANGUAGE: string = 'zh'
  private static readonly MAX_RADIUS: number = 50000  // 最大半径 50km

  /**
   * 周边 POI 搜索
   * @param params 搜索参数
   * @returns Promise<HuaweiPoiSearchResult>
   */
  static async searchNearby(params: HuaweiPoiSearchParams): Promise<HuaweiPoiSearchResult> {
    // 参数验证
    if (!params.keyword || params.keyword.trim() === '') {
      throw new Error('搜索关键词不能为空')
    }
    if (params.radius <= 0 || params.radius > this.MAX_RADIUS) {
      throw new Error(`搜索半径必须在 1-${this.MAX_RADIUS} 米之间`)
    }
    
    try {
      console.info('[PoiSearch] 开始周边搜索')
      console.info(`  关键词: ${params.keyword}`)
      console.info(`  中心点: ${params.latitude}, ${params.longitude}`)
      console.info(`  半径: ${params.radius}米`)
      
      // 构建 Site Kit 搜索参数
      const searchParams: site.SearchByTextParams = {
        query: params.keyword.trim(),
        location: {
          latitude: params.latitude,
          longitude: params.longitude
        },
        radius: params.radius,
        language: this.DEFAULT_LANGUAGE,
        pageIndex: params.pageNum || 1,
        pageSize: params.pageSize || this.DEFAULT_PAGE_SIZE
      }
      
      // 调用 Site Kit API
      const siteResult = await site.searchByText(searchParams)
      
      if (!siteResult) {
        throw new Error('Site Kit API 返回结果为空')
      }
      
      console.info(`[PoiSearch] ✅ 搜索成功，返回 ${siteResult.sites?.length || 0} 个结果`)
      
      // 转换为统一格式
      const pois = this.parseSiteKitData(siteResult, params.latitude, params.longitude)
      
      return {
        pois: pois,
        totalCount: siteResult.totalCount || pois.length,
        pageNum: params.pageNum || 1,
        pageSize: params.pageSize || this.DEFAULT_PAGE_SIZE
      }
      
    } catch (err) {
      const error = err as BusinessError
      console.error(`[PoiSearch] ❌ 搜索失败: ${error.code} - ${error.message}`)
      throw new Error(`POI 搜索失败: ${error.message}`)
    }
  }
}

4. 解析 Site Kit 返回数据

/**
 * 解析 Site Kit 返回的 POI 数据
 */
private static parseSiteKitData(
  siteResult: site.SearchByTextResult,
  centerLat: number,
  centerLng: number
): HuaweiPoiItem[] {
  if (!siteResult.sites || siteResult.sites.length === 0) {
    console.info('[PoiSearch] 未找到 POI 数据')
    return []
  }
  
  const pois: HuaweiPoiItem[] = []
  
  for (let i = 0; i < siteResult.sites.length; i++) {
    const siteInfo = siteResult.sites[i]
    
    try {
      // 检查位置信息
      if (!siteInfo.location) {
        console.warn(`[PoiSearch] POI ${i} 缺少位置信息`)
        continue
      }
      
      // 计算距离
      const distance = this.calculateDistance(
        centerLat, centerLng,
        siteInfo.location.latitude,
        siteInfo.location.longitude
      )
      
      const poi: HuaweiPoiItem = {
        // 基础信息
        poiId: siteInfo.siteId || `poi_${Date.now()}_${i}`,
        title: siteInfo.name || '未知地点',
        snippet: this.parseAddress(siteInfo),
        typeDes: this.parseSiteType(siteInfo),
        
        // 位置信息
        latitude: siteInfo.location.latitude,
        longitude: siteInfo.location.longitude,
        distance: distance,
        
        // 联系信息
        tel: siteInfo.poi?.phone,
        
        // 评价信息
        rating: this.parseRating(siteInfo.poi),
        starRating: this.parseStarRating(siteInfo.poi),
        
        // 营业信息
        openingHours: this.parseOpeningHours(siteInfo.poi),
        
        // 地址信息
        formatAddress: siteInfo.formatAddress,
        
        // 分类信息
        poiTypes: siteInfo.poi?.poiTypes
      }
      
      pois.push(poi)
    } catch (err) {
      console.error('[PoiSearch] 解析 POI 数据失败:', err)
    }
  }
  
  console.info(`[PoiSearch] 解析完成，共 ${pois.length} 个 POI`)
  return pois
}

/**
 * 解析地址
 */
private static parseAddress(siteInfo: site.Site): string {
  if (siteInfo.formatAddress) {
    return siteInfo.formatAddress
  }
  
  // 组合地址字段
  const parts: string[] = []
  if (siteInfo.address?.adminArea) parts.push(siteInfo.address.adminArea)
  if (siteInfo.address?.locality) parts.push(siteInfo.address.locality)
  if (siteInfo.address?.subLocality) parts.push(siteInfo.address.subLocality)
  if (siteInfo.address?.thoroughfare) parts.push(siteInfo.address.thoroughfare)
  
  return parts.join('') || '地址未知'
}

/**
 * 解析 POI 类型
 */
private static parseSiteType(siteInfo: site.Site): string {
  if (siteInfo.poi?.poiTypes && siteInfo.poi.poiTypes.length > 0) {
    return siteInfo.poi.poiTypes[0]
  }
  return '其他'
}

/**
 * 解析评分
 */
private static parseRating(poiInfo: site.Poi | undefined): string | undefined {
  if (!poiInfo || !poiInfo.rating) return undefined
  return poiInfo.rating.toFixed(1)
}

/**
 * 解析星级评分
 */
private static parseStarRating(poiInfo: site.Poi | undefined): string | undefined {
  if (!poiInfo || !poiInfo.starRating) return undefined
  return poiInfo.starRating.toFixed(1)
}

/**
 * 解析营业时间
 */
private static parseOpeningHours(poiInfo: site.Poi | undefined): HuaweiPoiOpeningHours | undefined {
  if (!poiInfo || !poiInfo.openingHours) return undefined
  
  return {
    periods: poiInfo.openingHours.periods?.map(period => ({
      open: period.open ? { day: period.open.week, time: period.open.time } : undefined,
      close: period.close ? { day: period.close.week, time: period.close.time } : undefined
    }))
  }
}

5. 计算两点间距离

/**
 * 计算两点间距离（Haversine 公式）
 * @returns 距离（米）
 */
private static calculateDistance(
  lat1: number, lng1: number,
  lat2: number, lng2: number
): number {
  const R = 6371000  // 地球半径（米）
  const dLat = this.toRadians(lat2 - lat1)
  const dLng = this.toRadians(lng2 - lng1)
  
  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(this.toRadians(lat1)) * Math.cos(this.toRadians(lat2)) *
    Math.sin(dLng / 2) * Math.sin(dLng / 2)
  
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
  
  return Math.round(R * c)
}

private static toRadians(degrees: number): number {
  return degrees * Math.PI / 180
}

6. 在页面中使用

// pages/PoiSearchPage.ets
import { HuaweiPoiSearchService, HuaweiPoiItem } from '../services/HuaweiPoiSearchService'

@Entry
@Component
struct PoiSearchPage {
  @State keyword: string = ''
  @State searchResults: HuaweiPoiItem[] = []
  @State isSearching: boolean = false
  @State errorMessage: string = ''
  
  // 当前位置（示例：北京天安门）
  private currentLat: number = 39.9042
  private currentLng: number = 116.4074
  
  build() {
    Column({ space: 16 }) {
      // 搜索框
      Row({ space: 8 }) {
        TextInput({ placeholder: '搜索周边...', text: this.keyword })
          .layoutWeight(1)
          .height(44)
          .onChange((value: string) => this.keyword = value)
        
        Button('搜索')
          .width(80)
          .height(44)
          .onClick(() => this.doSearch())
      }
      .width('100%')
      
      // 搜索状态
      if (this.isSearching) {
        Row() {
          LoadingProgress().width(24).height(24)
          Text('搜索中...').margin({ left: 8 })
        }
      }
      
      // 错误提示
      if (this.errorMessage) {
        Text(this.errorMessage)
          .fontColor('#FF4444')
          .fontSize(14)
      }
      
      // 搜索结果列表
      List() {
        ForEach(this.searchResults, (poi: HuaweiPoiItem) => {
          ListItem() {
            Column({ space: 4 }) {
              Row() {
                Text(poi.title)
                  .fontSize(16)
                  .fontWeight(FontWeight.Medium)
                  .layoutWeight(1)
                Text(`${poi.distance}m`)
                  .fontSize(14)
                  .fontColor('#666666')
              }
              .width('100%')
              
              Text(poi.snippet)
                .fontSize(14)
                .fontColor('#999999')
                .maxLines(1)
                .textOverflow({ overflow: TextOverflow.Ellipsis })
              
              Row({ space: 16 }) {
                Text(poi.typeDes)
                  .fontSize(12)
                  .fontColor('#A9846A')
                
                if (poi.rating) {
                  Text(`⭐ ${poi.rating}`)
                    .fontSize(12)
                    .fontColor('#FF9500')
                }
                
                if (poi.tel) {
                  Text(`📞 ${poi.tel}`)
                    .fontSize(12)
                    .fontColor('#007AFF')
                }
              }
            }
            .alignItems(HorizontalAlign.Start)
            .padding(12)
          }
        })
      }
      .layoutWeight(1)
      .divider({ strokeWidth: 1, color: '#E8E8E8' })
    }
    .width('100%')
    .height('100%')
    .padding(16)
  }
  
  /**
   * 执行搜索
   */
  private async doSearch(): Promise<void> {
    if (!this.keyword.trim()) {
      this.errorMessage = '请输入搜索关键词'
      return
    }
    
    this.isSearching = true
    this.errorMessage = ''
    this.searchResults = []
    
    try {
      const result = await HuaweiPoiSearchService.searchNearby({
        keyword: this.keyword,
        latitude: this.currentLat,
        longitude: this.currentLng,
        radius: 5000,  // 5公里范围
        pageSize: 20
      })
      
      this.searchResults = result.pois
      
      if (result.pois.length === 0) {
        this.errorMessage = '未找到相关地点'
      }
    } catch (error) {
      this.errorMessage = `搜索失败: ${error}`
    } finally {
      this.isSearching = false
    }
  }
}

效果

控制台日志：

[PoiSearch] 开始周边搜索
  关键词: 咖啡
  中心点: 39.9042, 116.4074
  半径: 5000米
[PoiSearch] ✅ 搜索成功，返回 20 个结果
[PoiSearch] 解析完成，共 20 个 POI

搜索结果示例：

关键点总结