巡检人员在地图上长按一个位置，页面马上出现坐标、事件名称和“可确认”的工单草稿。这个过程很容易被写成“长按地图即可建单”，但对位置服务而言，真正重要的是：这条坐标究竟由什么对象返回，页面为什么认定它可作为落点证据，以及人工登记为什么不能把空白状态伪装成真实地图事件。

当前页面工程同时监听 Marker 和 POI 的长按。两类事件都能提供可用于页面内工单草稿的坐标，但它们不是同一个对象：Marker 是应用或页面添加、可被识别的地图标记；POI 是地图底图中的兴趣点对象。将两者合并为“任意地图长按”，会让后续人员失去判断来源的机会。

本文只讨论一个主技术点：如何围绕 Marker 与 POI 长按事件，建立可解释的巡检落点记录。它不把页面中的工单草稿写成后台工单，也不把人工位置描述写成 MapKit 返回坐标。

先明确：长按得到的不是同一种位置事实

Marker 表示一个可追溯的页面标记

页面初始化完成后，会在地图中心添加一枚“巡检测试 Marker”。操作者长按该标记时，回调对象是 map.Marker。页面可以从该对象读取标题，并通过 getPosition() 获取经纬度。

Marker 的价值不在于它看上去像一个图钉，而在于它有明确的页面来源：谁添加的、标题是什么、可否交互、回调何时到达，都可以在当前运行中记录。因此，Marker 长按适合验证“页面添加的巡检点是否能形成一条真实事件记录”。

POI 表示底图返回的兴趣点对象

POI 长按的回调对象是 mapCommon.Poi。它有自己的名称、标识和位置字段。页面记录 POI 时，坐标从 poi.position 获取，事件详情保留 poi.name 与 poi.id。

POI 的名称并不等于业务台账中的设备、门店或设施编号。它只能说明当前底图对象返回了什么；如果现场任务需要关联业务资产，还需要另行比对资产编号、区域、任务时间和人工核验结果。把 POI 名称直接写入资产台账，会把地图对象关系误写成业务关系。

普通点击、空白长按与人工登记不属于真实事件

页面只在 Marker 或 POI 的长按监听中递增计数、写入坐标和更新最近事件。普通点击、空白区域的操作、切换任务类型、调整优先级都不会获得同样的证据等级。

人工登记也被单独记录为“人工降级”。它可以让巡检任务在地图条件不完整时继续保存说明，但不能写入 MapKit 坐标，更不能增加 Marker 或 POI 的长按次数。这不是刻意让流程变复杂，而是避免后续审阅把手工描述误读为事件回调。

来源	页面可保留的内容	可以说明什么	不能说明什么
Marker 长按	标题、经纬度、事件时间、来源类型	页面添加的标记确实触发了长按回调	业务资产已经确认
POI 长按	POI 名称、POI 标识、经纬度、事件时间	底图兴趣点对象触发了长按回调	POI 与当前任务必然属于同一实体
人工登记	任务说明、人工状态、待补字段	任务尚可继续交接	真实地图坐标已取得
地图画面	当前视口、图层、页面控件	操作者看到的空间上下文	长按事件已经到达

先让事件来源进入状态模型

页面不是只保存一个“最后坐标”

巡检落点页面使用一个事件记录结构保存每次观察：序号、来源、详情、坐标、是否真实回调和事件时间。只保存最后坐标虽然简单，却会丢失来源和顺序；当操作人员先长按 Marker、再长按 POI 时，后续查看者无法知道当前坐标来自哪里，也无法追溯前一次观察。

interface InspectionEventItem {
  sequence: number;
  source: string;
  detail: string;
  coordinate: string;
  isReal: boolean;
  eventTime: string;
}

这段定义能说明：页面把来源、详情、坐标、真实标记和时间作为同一条事件的组成部分。它不能说明：记录已经同步到服务端、已经成为正式工单，或已经完成现场复核。

这种模型特别适合地图场景，因为同一组经纬度在不同来源下具有不同含义。39.9042, 116.4074 如果来自 Marker，只能说明页面标记所在位置；如果来自 POI，说明的是底图对象位置；如果来自人工描述，则不应以经纬度字段出现。数据形式相似，不代表证据来源相同。

操作序号把页面内观察串成时间线

每次事件或人工登记都会生成新的操作序号并记录时间。时间线只保留最近的页面内记录，目的是让当前会话可读，而不是取代长期归档。

private updateOperation(prefix: string): void {
  this.operationSequence += 1;
  this.lastOperation = `${prefix}-${this.operationSequence}`;
  this.lastUpdatedAt = timestamp();
}

private recordInspectionEvent(
  source: string, detail: string, coordinate: string, isReal: boolean
): void {
  this.updateOperation(isReal ? 'EVENT' : 'MANUAL');
  const item: InspectionEventItem = {
    sequence: this.operationSequence,
    source, detail, coordinate, isReal,
    eventTime: this.lastUpdatedAt
  };
  this.eventRecords = [item, ...this.eventRecords].slice(0, 5);
}

这段代码能说明：页面把真实回调与人工降级标记为不同类型，并按操作序号写入当前会话时间线。它不能说明：早于当前页面会话的历史记录仍被保存，也不能推导现场处置已经结束。页面内“最近五条”是观察窗口，不是业务档案库。

监听注册决定了哪些动作有资格写入坐标

地图控制器就绪后再注册事件

MapComponent 回调返回控制器后，页面获取事件管理器、注册两个长按监听，并尝试添加测试 Marker。若控制器没有返回或回调携带错误，页面保留初始化失败状态，不会假设事件管理器已经可用。

this.mapController = controller;
this.mapEventManager = controller.getEventManager();
this.registerLongPressEvents(this.mapEventManager);
this.mapState = '地图控制器已就绪，长按监听已注册';

await controller.addMarker({
  position: this.center,
  title: '巡检测试 Marker',
  snippet: '真实长按以创建巡检点位证据',
  clickable: true,
  draggable: false
});

这段代码能说明：长按监听的注册依赖实际返回的地图控制器，页面还会在当前中心点添加可交互标记。它不能说明：底图 POI 一定可见、目标设备一定支持相同的对象交互，或任何长按都会回调。

因此，验收时应将“地图已加载”“测试 Marker 已添加”“监听已注册”“Marker 或 POI 长按已到达”分别记录。前一个状态成功不等于后一个状态已经发生。

Marker 与 POI 走各自的原始字段链路

两个监听分别读取各自对象提供的字段，而不是把它们强行规整成只有名称的字符串。

manager.onMarkerLongClick((marker: map.Marker) => {
  const position = marker.getPosition();
  const coordinate = `${position.latitude}, ${position.longitude}`;
  this.markerLongPressCount += 1;
  this.lastEvent = `Marker 长按：${marker.getTitle()}`;
  this.eventCoordinates = coordinate;
  this.recordInspectionEvent('Marker 长按', marker.getTitle(), coordinate, true);
});

manager.onPoiLongClick((poi: mapCommon.Poi) => {
  const coordinate = `${poi.position.latitude}, ${poi.position.longitude}`;
  this.poiLongPressCount += 1;
  this.lastEvent = `POI 长按：${poi.name} (${poi.id})`;
  this.eventCoordinates = coordinate;
  this.recordInspectionEvent('POI 长按', poi.name, coordinate, true);
});

这段代码能说明：Marker 与 POI 的计数独立维护，事件详情与坐标只在相应的真实回调中更新，并以 isReal: true 写入时间线。它不能说明：Marker 标题就是资产名称，或者 POI 标识就是当前巡检任务的业务主键。

在工程实践中，独立计数比单一的“长按次数”更容易排查问题。例如 Marker 可长按、POI 不可长按时，页面可以明确观察到差异；若只有一个总数，问题会被隐藏在看似正常的数字里。

页面离开时只释放引用，不虚构注销结果

页面离开时会将事件管理器和地图控制器引用置空。当前运行环境中不提供逐事件注销方法，错误调用会导致离页异常。这里的处理只说明页面不再继续持有当前组件的引用，不应被夸大为“已完成所有事件清理验证”。

这类生命周期边界与长按事件本身不同，却直接关系到页面的稳定性：一个在离开页面时崩溃的地图页，会让同一组事件数据难以复现。文章应如实写明工程采取的对象释放策略，不把未提供的 API 包装成已经调用过的能力。

用事件时间线替代一次性结果文案

时间线同时容纳真实回调与人工降级

页面把时间线项标记为“真实回调”或“人工降级”。这两个标签不用于评价谁更好，而是用于说明坐标和详情的来源等级。

时间线条目	应出现的字段	后续可执行动作
Marker 长按	Marker 标题、经纬度、时间、序号	查看标记是否与巡检任务有关，再确认草稿
POI 长按	POI 名称、POI 标识、经纬度、时间、序号	核对 POI 与现场对象的关系，再确认草稿
人工登记	待补点位原因、无真实坐标、时间、序号	转现场补证或再次执行地图操作
初始化失败	错误摘要、控制器状态、时间	排查配置、网络或地图服务条件

如果所有状态都只显示“建单成功”或“操作失败”，就无法区分是事件未到达、字段未取到、还是业务关联尚未完成。位置服务中的可用状态往往比最终状态多，页面应该保留这些中间层，而不是为了显示简洁把它们压平。

任务类型和优先级是上下文，不是坐标来源

页面允许切换“设施异常/设施复检”和 P1/P2 优先级。这些字段解释当前草稿打算处理什么、需要怎样的响应节奏，却不能生成或修改真实坐标。无论任务类型怎样切换，只有 Marker 或 POI 的回调才能让页面进入“已获取真实坐标”的状态。

这条边界可以防止一种常见误解：页面上出现了设施名称、任务类型、优先级和一枚地图标记，就被误写成“设备定位已确认”。实际上，业务对象、任务语义和地图对象需要各自留存，再在人工核验中建立关系。

真实回调以后仍然需要人工关联

获得 Marker 或 POI 坐标后，页面允许确认本地工单草稿。这里的“确认”只针对当前页面草稿，不代表后台系统已经创建工单，也不代表地点和业务对象已经经过现场确认。

private confirmDraft(): void {
  if (!this.hasRealEvidence()) {
    this.workOrderState = '待确认草稿缺少真实地图点位，无法确认。';
    return;
  }
  this.workOrderState =
    `本地工单草稿已确认：${this.taskType} · ${this.priority}，未提交后台。`;
  this.updateOperation('DRAFT');
}

这段代码能说明：页面把“获得至少一条真实事件”作为确认本地草稿的前提，同时明确未提交后台。它不能证明：工单已经创建、责任人已接单、巡检对象已经被正确识别，或现场问题已经处置。

人工登记为什么只能是降级路径

没有真实事件时，业务仍可以留下说明

地图服务、网络、底图对象可交互性或运行条件可能使长按事件暂时无法获得。页面允许在没有真实证据时创建人工登记草稿，避免任务完全中断。人工条目会写入“无真实坐标”，并在时间线中标为人工降级。

private hasRealEvidence(): boolean {
  return this.markerLongPressCount + this.poiLongPressCount > 0;
}

private canCreateManualRecord(): boolean {
  return !this.hasRealEvidence();
}

private createManualRecord(): void {
  if (!this.canCreateManualRecord()) {
    this.manualRecordState = '人工登记未执行：真实坐标已存在，不可覆盖 MapKit 事件。';
    return;
  }
  this.manualRecordState = '人工登记草稿已创建：未写入地图坐标或长按计数。';
  this.workOrderState = '人工登记草稿待补充真实点位';
  this.lastEvent = '人工登记：等待补充真实点位';
  this.recordInspectionEvent('人工登记', '未获得 MapKit 长按事件', '无真实坐标', false);
}

这段代码能说明：人工登记仅在没有真实长按证据时启用，且不会覆盖已有 MapKit 事件，不会写入地图坐标或事件计数。它不能说明：人工描述已经变成空间位置，或之后一定可以补到真实回调。

人工描述不能被格式化成经纬度

“设备区 A-03 东侧”“风机旁通道”“进入机房后右侧”都是有价值的现场描述，但它们属于人工观察，不是经纬度。把自然语言描述写进坐标字段，会造成两层伤害：一是后续系统可能把它当成可计算位置；二是审阅人员失去判断数据来源的机会。

正确做法是保留两列：地图坐标只接受真实回调原值；人工描述进入备注或补证任务。若后来取得真实事件，应新增一条真实回调记录，而不是回写覆盖原先的人工条目。这样可以保留“为什么当时走了人工路径、后来补了什么”的完整过程。

一条巡检落点的可复演操作链

操作一：确认地图与监听基线

进入页面后，先查看地图控制器状态、测试 Marker 添加状态和长按监听状态。此时事件计数为零、坐标为空是预期状态。不要因为地图已显示就认定监听已经触发，也不要把测试 Marker 的默认位置当成已经产生的巡检落点。

操作二：长按页面添加的 Marker

在地图可用后长按“巡检测试 Marker”。观察 Marker 长按计数是否增加、最近事件是否显示 Marker 标题、坐标是否出现、时间线是否新增“真实回调”。本次操作只验证 Marker 链路，不替代 POI 链路验证。

操作三：长按可见 POI

在可交互的底图 POI 上执行长按。观察 POI 长按计数是否独立增加，最近事件中是否保留 POI 名称和标识。若没有收到回调，应保留“未取得”状态并检查运行条件，而不是把上一条 Marker 坐标复制到 POI 事件里。

操作四：确认本地草稿的边界

获得至少一条真实事件后，确认本地工单草稿。检查草稿是否保留任务类型、优先级、点位来源和坐标；同时确认页面仍明确显示“未提交后台”。该操作验证的是页面草稿门槛，而不是业务系统工单状态。

操作五：验证人工降级不污染真实事件

在尚未产生长按事件的新会话中建立人工登记草稿。应看到“无真实坐标”和人工降级条目，Marker/POI 计数保持为零。获得真实事件后，人工登记入口应不再覆盖真实坐标。这一步保证业务连续性与位置事实能够共存。

操作六：重置会话后重新观察

重置会话会清空两个事件计数、当前坐标、最近事件和页面内时间线。重置只作用于当前页面状态，并不删除外部地图对象，也不影响已经在其他系统形成的业务记录。下一次操作应作为新的观察开始。

常见错误与排查

把 Marker 标题当成资产主键

Marker 标题是页面显示文本，可能随着设计调整而变化。若业务需要关联资产，应保存独立资产编号或人工确认依据。页面标题可以帮助阅读，但不能天然承担跨系统唯一标识。

把 POI 名称写成现场确认结果

POI 名称来自底图对象，不等于现场设施、门店或资产已经被确认。特别是在名称相似、地图数据更新或周边对象密集的场景中，必须把 POI 标识、坐标、时间与人工核验分开保存。

用地图中心填补没有回调的坐标

地图中心只是当前视口或默认配置。没有真实回调时，把中心点填进坐标栏会把“页面正在显示地图”伪装成“巡检点位已取得”。正确状态应是坐标为空，并在人工登记中保留待补原因。

合并 Marker 与 POI 的事件计数

如果只显示一个总次数，开发和测试都无法判断哪一种对象交互失效。独立计数能够定位到事件来源层：是 Marker 没有添加、POI 不可交互、监听未注册，还是操作者没有按在目标对象上。

将本地草稿确认写成工单已创建

当前页面只确认本地工单草稿。没有后台接口返回、持久化记录或业务回执时，不能使用“已创建”“已派发”之类的结论。把页面状态与业务状态分开，后续才不会把展示成功误认为系统完成。

FAQ

Q：Marker 和 POI 长按都返回坐标，是否可以统一成一种事件？

可以在业务层做统一处理，但原始记录不应丢失来源。Marker 与 POI 的字段和创建方式不同，保留来源类型、详情与原始标识，才能在问题出现时判断是页面标记、底图对象还是关联规则造成的差异。

Q：为什么已经有真实 Marker 坐标后，人工登记按钮还要关闭？

这是为了防止人工条目覆盖真实回调。人工登记的价值是处理“尚未得到真实点位”的情况；一旦已有真实事件，继续写入无来源位置只会让同一任务出现彼此冲突的坐标依据。

Q：POI 长按没有回调，是不是可以直接认定地图能力不可用？

不能直接认定。先检查地图控制器是否就绪、监听是否注册、POI 是否可交互、网络与服务配置是否满足。Marker 长按和 POI 长按应分别观察，不能因一条链路失败就推导另一条也失败。

Q：页面显示“真实事件已捕获”，是否代表巡检对象已经确认？

不代表。该状态只说明当前页面收到了一条 Marker 或 POI 长按回调。对象与业务资产、任务区域或现场问题的关联仍需要独立核验。

Q：为什么时间线只保留最近几条记录？

页面内时间线用于说明当前会话的操作顺序，便于即时排查。长期留存需要由业务系统或受控的运行记录承担，不能把页面内有限状态当作完整的历史档案。

必要条件｜安装与配置操作手册

第1步：准备SDK和构建工具

在 DevEco Studio 的 SDK Manager 安装 HarmonyOS 6.1.1 API 24，使用项目自带 Hvigor 构建 entry 模块。

第2步：确认Kit引入

按本文代码检查对应 Kit：ArkWeb 使用 WebView/Download API，Camera 使用 CameraKit，ImageSource 使用图像模块，MapKit 使用 MapKit，Notification 使用 NotificationKit，AI字幕使用 SpeechKit，通行证识别使用 VisionKit。

第3步：登记模块和页面

确认页面出现在 entry/src/main/resources/base/profile/main_pages.json，并核对 module.json5 的 Stage、设备类型和权限声明。

第4步：完成设备权限

首次运行前申请本文所需权限。Camera 页面申请 CAMERA，AI字幕页面申请 MICROPHONE；权限被拒绝时先处理授权状态，不能直接创建会话或组件。

第5步：确认系统能力和硬件

在 API 24 设备或模拟器确认本文需要的摄像头、麦克风、地图服务、视觉识别或文件读取能力，能力检查通过后再执行页面操作。

第6步：配置 MapKit（仅MapKit文章）

在 AppGallery Connect 创建或选择项目，添加与 app.json5/工程包名一致的应用，核对签名证书指纹，进入服务管理开通 MapKit，并按控制台要求完成应用服务凭据/授权配置。只保留服务开关、包名和脱敏项目标识的截图；不得把 App ID、Client ID、API 密钥或证书私钥写入文章或源码。完成控制台配置后再验证地图初始化和检索回调。