HarmonyOS Location Kit 地理围栏双方案实战：端侧与云侧落地指南

2.2 合规要求：用户授权与数据安全

根据华为 Location Kit 的个人数据处理规范：

1. 必须获得用户明确同意：使用地理围栏前，需向用户说明'为什么需要监听位置'（如'考勤打卡需识别您是否进入公司区域'），用户同意后才能启用围栏。
2. 数据不持久化：定位服务处理用户位置数据后会立即删除，不会保存，开发者无需额外处理数据存储合规性，但需在 App 隐私政策中说明这一点。

三、端侧 GNSS 围栏开发：自定义圆形围栏（ArkTS）

端侧 GNSS 围栏是最常用的方案，适合开发者自主定义小范围圆形围栏，事件触发在本地设备，响应速度快。核心流程是'创建 WantAgent→配置围栏参数→注册围栏监听'。

3.1 核心概念：WantAgent 的作用

地理围栏触发后需要执行预设动作（如拉起 App、发送通知），而 WantAgent 就是 HarmonyOS 中'封装动作意图'的工具——它能把'拉起某 Ability''发送公共事件'等动作包装成对象，围栏触发时系统会自动执行该动作。

3.2 完整开发步骤

第一步：导入核心模块

需要导入地理围栏、WantAgent 和错误处理相关模块：

import { geoLocationManager } from '@kit.LocationKit';
import { wantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

第二步：创建 WantAgent（定义围栏触发动作）

根据业务需求选择动作类型，常用两种场景：

场景 A：触发时拉起 App 的 Ability（如考勤打卡页面）

/**
 * 创建拉起 Ability 的 WantAgent
 * 围栏触发时，自动打开 EntryAbility
 */
function createStartAbilityWantAgent() {
  // 配置 WantAgent 信息：指定要拉起的 Ability
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        deviceId: '', // 空表示当前设备
        bundleName: 'com.example.myapplication', // 你的 App 包名
        abilityName: 'EntryAbility', // 要拉起的 Ability 名称
        parameters: { "fenceAction": "checkIn" } // 传递额外参数（如'打卡'动作）
      }
    ],
    operationType: wantAgent.OperationType.START_ABILITY, // 动作类型：拉起 Ability
    requestCode: 0, // 请求码（自定义，用于区分不同 WantAgent）
    wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG] // 常量标志（确保动作可重复触发）
  };

  // 创建 WantAgent 对象
  wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data: wantAgent.WantAgent) => {
    if (err) {
      console.error(`创建 WantAgent 失败：errCode=${err.code}, errMsg=${err.message}`);
      return;
    }
    console.info("创建拉起 Ability 的 WantAgent 成功");
    // 下一步：注册地理围栏（传入该 WantAgent）
    registerGnssGeofence(data);
  });
}

场景 B：触发时发送公共事件（如通知 App 后台处理）

/**
 * 创建发送公共事件的 WantAgent
 * 围栏触发时，发送自定义事件，App 后台监听处理
 */
function createSendEventWantAgent() {
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        action: 'com.example.geofence.CHECK_IN_EVENT', // 自定义事件名（需唯一）
        parameters: { "fenceId": "companyFence" } // 传递围栏 ID 等参数
      }
    ],
    operationType: wantAgent.OperationType.SEND_COMMON_EVENT, // 动作类型：发送公共事件
    requestCode: 1,
    wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG]
  };

  wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data: wantAgent.WantAgent) => {
    if (err) {
      console.error(`创建 WantAgent 失败：errCode=${err.code}, errMsg=${err.message}`);
      return;
    }
    console.info("创建发送公共事件的 WantAgent 成功");
    registerGnssGeofence(data);
  });
}

第三步：配置围栏参数并注册监听

端侧围栏仅支持圆形，需指定'中心点经纬度、半径、有效期'，然后调用 on('gnssFenceStatusChange') 注册围栏：

/**
 * 注册端侧 GNSS 地理围栏
 * @param wantAgentObj 已创建的 WantAgent 对象
 */
function registerGnssGeofence(wantAgentObj: wantAgent.WantAgent) {
  // 1. 配置围栏参数
  const geofenceRequest: geoLocationManager.GeofenceRequest = {
    scenario: 0x301, // 围栏场景：0x301 表示'日常位置监控'（固定值）
    geofence: {
      latitude: 31.12, // 围栏中心点纬度（如公司纬度）
      longitude: 121.11, // 围栏中心点经度（如公司经度）
      radius: 100, // 围栏半径（单位：米，建议 10-500 米，太大影响精度）
      expiration: 86400000 // 围栏有效期（单位：毫秒，86400000=24 小时）
    }
  };

  // 2. 注册围栏监听
  try {
    geoLocationManager.on('gnssFenceStatusChange', geofenceRequest, wantAgentObj);
    console.info("端侧 GNSS 围栏注册成功");
  } catch (err) {
    const error = err as BusinessError;
    console.error(`围栏注册失败：errCode=${error.code}, errMsg=${error.message}`);
  }
}

第四步：取消围栏监听（避免内存泄漏）

当不需要围栏时（如用户退出考勤功能），需及时取消监听：

/**
 * 取消端侧 GNSS 围栏监听
 */
function unregisterGnssGeofence() {
  try {
    geoLocationManager.off('gnssFenceStatusChange');
    console.info("端侧 GNSS 围栏已取消");
  } catch (err) {
    const error = err as BusinessError;
    console.error(`取消围栏失败：errCode=${error.code}, errMsg=${error.message}`);
  }
}

3.3 关键注意事项

1. 环境限制：端侧围栏依赖 GNSS 芯片，仅在室外开阔区域能准确触发（室内、高楼遮挡时 GNSS 信号弱，可能误触发或不触发）。
2. 半径建议：半径太小（<10 米）可能因定位误差导致漏触发，太大（>1000 米）精度下降，建议根据场景设置 10-500 米。
3. 有效期设置：若不需要长期有效，建议设置合理有效期（如考勤围栏仅设置工作日 9:00-18:00 有效），避免不必要的功耗。

四、云侧围栏开发：公共围栏快速接入（ArkTS）

云侧围栏无需开发者创建围栏，直接使用华为云侧的公共围栏（如商圈、景区、交通枢纽等），适合需要'大范围、多区域'围栏的场景。核心是通过 FenceExtensionAbility 接收云端触发的围栏事件。

4.1 核心流程梳理

1. 开发者在 AGC（AppGallery Connect）平台配置要使用的公共围栏（如'全国万达商圈'）。
2. 设备满足围栏条件（进入/离开）时，华为云会通知设备。
3. 设备通过 FenceExtensionAbility 接收事件，执行自定义业务逻辑（如发送通知）。

4.2 完整开发步骤

第一步：AGC 平台配置（前置操作）

1. 登录 AGC 平台，进入你的应用。
2. 开通'Location Kit'服务，在'地理围栏'模块选择需要的公共围栏类型（如商圈、景区），配置下发策略（如'进入围栏时触发'）。
3. 下载 agconnect-services.json 文件，放到工程 entry/src/main 目录下（用于 App 与 AGC 关联）。

第二步：创建 FenceExtensionAbility（事件接收组件）

FenceExtensionAbility 是专门接收云侧围栏事件的组件，需要单独创建和注册。

新建组件文件

在工程 entry/ets 目录下新建 fenceextensionability 文件夹，创建 MyFenceExtensionAbility.ets 文件：

import { FenceExtensionAbility, geoLocationManager } from '@kit.LocationKit';
import { notificationManager } from '@kit.NotificationKit';
import { Want, wantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 自定义 FenceExtensionAbility，接收云侧围栏事件
 */
export class MyFenceExtensionAbility extends FenceExtensionAbility {
  /**
   * 围栏状态变化时回调（进入/离开/驻留）
   * @param transition 围栏事件信息（围栏 ID、事件类型等）
   * @param additions 附加信息（如围栏名称、类型）
   */
  onFenceStatusChange(transition: geoLocationManager.GeofenceTransition, additions: Record<string, string>): void {
    console.info(`收到云侧围栏事件：围栏 ID=${transition.geofenceId}, 事件类型=${transition.transitionEvent}`);
    console.info(`围栏附加信息：${JSON.stringify(additions)}`);
    // 业务逻辑：发送通知提醒用户（如商圈优惠通知）
    this.sendFenceNotification(transition, additions);
  }

  /**
   * 组件销毁时回调（释放资源）
   */
  onDestroy(): void {
    console.info("FenceExtensionAbility 已销毁");
    super.onDestroy();
  }

  /**
   * 发送围栏触发通知
   */
  private sendFenceNotification(
    transition: geoLocationManager.GeofenceTransition,
    additions: Record<string, string>
  ): void {
    // 1. 创建 WantAgent：点击通知时拉起 App
    const wantAgentInfo: wantAgent.WantAgentInfo = {
      wants: [
        {
          bundleName: 'com.example.myapplication',
          abilityName: 'EntryAbility',
          parameters: {
            geofenceId: transition.geofenceId,
            transitionEvent: transition.transitionEvent,
            fenceName: additions.fenceName // 围栏名称（从附加信息中获取）
          } as Record<string, any>
        } as Want
      ],
      operationType: wantAgent.OperationType.START_ABILITY,
      requestCode: 100
    };

    // 2. 创建通知并发布
    wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: wantAgent.WantAgent) => {
      // 配置通知内容
      const notificationRequest: notificationManager.NotificationRequest = {
        id: Math.floor(Math.random() * 1000), // 唯一通知 ID
        content: {
          notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
          normal: {
            title: `【${additions.fenceName}】围栏通知`,
            text: `您已${transition.transitionEvent === 1 ? '进入' : '离开'}${additions.fenceName}，点击查看详情`,
          }
        },
        notificationSlotType: notificationManager.SlotType.SOCIAL_COMMUNICATION, // 通知类型（社交/服务等）
        wantAgent: wantAgentObj // 点击通知触发的动作
      };

      // 发布通知
      notificationManager.publish(notificationRequest).catch((err: BusinessError) => {
        console.error(`发布通知失败：errCode=${err.code}, errMsg=${err.message}`);
      });
    }).catch((err: BusinessError) => {
      console.error(`创建 WantAgent 失败：errCode=${err.code}, errMsg=${err.message}`);
    });
  }
}

注册组件（module.json5）

在 module.json5 中注册 FenceExtensionAbility，类型必须设为 fence：

{
  "module": {
    "extensionAbilities": [
      {
        "name": "MyFenceExtensionAbility",
        "srcEntry": "./ets/fenceextensionability/MyFenceExtensionAbility.ets",
        "description": "接收云侧围栏事件的扩展能力",
        "type": "fence", // 固定类型：fence
        "exported": false // 不对外暴露
      }
    ]
  }
}

第三步：启动云侧围栏监听

云侧围栏无需手动注册围栏（AGC 已配置），只需确保 App 已集成 AGC 配置，且用户已授权位置权限，设备联网后即可自动接收事件。

4.3 关键参数解析

• transition.transitionEvent：围栏事件类型，1=进入围栏，2=离开围栏，3=驻留围栏（可根据业务需求处理不同事件）。
• additions：附加信息，包含围栏名称（fenceName）、围栏类型（fenceType）等，具体字段由 AGC 配置的公共围栏决定。

五、避坑指南：常见问题与解决方案

5.1 端侧围栏触发不灵敏

• 原因：室内/高楼遮挡导致 GNSS 信号弱；围栏半径太小；定位权限未授权。
• 解决方案：
  1. 提示用户在室外使用该功能。
  2. 半径设置≥30 米，避免定位误差影响。
  3. 检查 isLocationEnabled() 是否为 true，确保位置开关已打开。

5.2 云侧围栏收不到事件

• 原因：AGC 未配置围栏策略；设备未联网；FenceExtensionAbility 未注册或注册错误。
• 解决方案：
  1. 检查 AGC 平台'地理围栏'配置是否生效，agconnect-services.json 是否正确放置。
  2. 确保设备联网（云侧事件依赖网络传输）。
  3. 检查 module.json5 中 extensionAbilities 的 type 是否为 fence，srcEntry 路径是否正确。

5.3 后台无法接收围栏事件

• 原因：未申请 LOCATION_IN_BACKGROUND 权限；App 被系统后台回收。
• 解决方案：
  1. 申请后台位置权限，并向用户说明后台使用场景。
  2. 对于云侧围栏，FenceExtensionAbility 是系统级组件，后台回收概率低；端侧围栏可申请'长时任务'保活（参考 HarmonyOS 长时任务机制）。

总结

地理围栏是 Location Kit 的'场景化核心能力'，端侧 GNSS 围栏适合自定义小范围场景，云侧围栏适合快速接入公共围栏，两者互补覆盖绝大多数位置提醒需求。开发时需注意：

1. 权限与合规是前提，必须获得用户授权并说明数据用途。
2. 端侧围栏依赖 GNSS 和室外环境，云侧围栏依赖 AGC 配置和网络。
3. 及时取消围栏监听或销毁组件，避免内存泄漏和不必要的功耗。

通过本文的实战指南，你可以根据自己的业务场景选择合适的围栏方案，快速实现'基于位置的智能提醒'功能。如果需要更复杂的场景（如多围栏叠加、驻留事件处理），可以进一步参考华为开发者文档的接口详情，结合定位和地理编码能力，打造更完整的位置服务体验。