一、一张看似正常的太平洋地图拖到日期变更线就空了项目叫 ClusterAtlas是给海运巡检团队做的风险点查看器。数据并不夸张2480 个港口、浮标和临时警戒点主页面ViewportClusterPage用 Map Kit 展示当前视口supercluster 在内存里做分簇。测试人员从东京向东拖到阿拉斯加时地图先出现一大片空白再突然跳回 28 个聚合点快速来回拖动还会看到上一帧的 41 个散点覆盖在新位置上。最初我以为是标注刷新太频繁。HiLog 却给出了更具体的线索任务MAP-2111的第 18 代查询已经提交第 17 代结果随后才返回而相机边界是west171.4, east-166.8。对普通矩形来说 west 大于 east 是非法范围对跨越 180° 经线的地图来说却完全成立。于是问题被拆成三个互相牵制的部分边界要拆成两段、两段结果要去重、异步结果只能提交最新一代。这次没有把“刷新地图”写成一个大函数。地图姿态、查询代数、分簇索引和 UI 标注分别维护只有最终提交点能修改页面状态。这样做稍显啰嗦却让拖动、旋转、前后台切换都可以用同一套约束解释。二、先把相机回调翻译成可比较的快照Map Kit 提供相机状态更新能力supercluster 的getClusters接收[west, south, east, north]和整数级别。两者之间不能直接连线相机回调可能一秒触发几十次缩放值带小数跨经线边界还需要拆分。项目目录只保留与这条链路有关的文件entry/src/main/ets/ ├── pages/ViewportClusterPage.ets ├── map/ViewportCoordinator.ets ├── map/ClusterIndex.ets ├── model/CameraSnapshot.ets └── data/pacific_risk_points.json第一段代码解决“同一次手势触发多次查询”的问题。页面只记录可复现的相机快照经纬度保留四位小数缩放向下取整后交给索引。每次稳定回调都会递增 generation旧任务即使没有被真正取消也失去了提交资格。interfaceCameraSnapshot{west:numbersouth:numbereast:numbernorth:numberzoom:numberbearing:number}exportclassViewportCoordinator{privategeneration:number0privatedisposed:booleanfalsenext(raw:CameraSnapshot):{generation:number,camera:CameraSnapshot}{constcamera:CameraSnapshot{west:Number(raw.west.toFixed(4)),south:Number(raw.south.toFixed(4)),east:Number(raw.east.toFixed(4)),north:Number(raw.north.toFixed(4)),zoom:Math.floor(raw.zoom),bearing:Number(raw.bearing.toFixed(1))}return{generation:this.generation,camera}}canCommit(value:number):boolean{return!this.disposedvaluethis.generation}release():void{this.disposedtruethis.generation}}这里的 generation 不是日志序号而是 UI 一致性边界。第 18 代开始后第 17 代就只能统计“过期丢弃”不能再写State。release()同时让当前代数失效避免页面退出后异步任务继续提交。重复注册相机监听会让代数无意义因此监听只在aboutToAppear建立在aboutToDisappear解除恢复页面时创建新的协调器不复用已经 disposed 的实例。三、跨经线不是扩大范围而是拆成两个合法包围盒错误版本把171.4与-166.8排序成[-166.8, 171.4]这等于查询几乎整个地球分簇数量当然异常。正确含义是从 171.4°E 到 180°再从 -180° 到 166.8°W。第二段代码把这一规则固化并用feature.id去重。supercluster 的索引在load()后不可变因此 2480 个点只在数据版本变化时重建拖图只做查询。importSuperclusterfromsuperclustertypeBBox[number,number,number,number]exportclassClusterIndex{privateindexnewSupercluster({radius:56,maxZoom:18})privateversion:stringbuildIndex(points:object[],version:string):void{if(this.versionversion)returnthis.indexnewSupercluster({radius:56,maxZoom:18})this.index.load(points)this.versionversion}queryViewport(camera:CameraSnapshot):object[]{constboxes:BBox[]camera.westcamera.east?[[camera.west,camera.south,camera.east,camera.north]]:[[camera.west,camera.south,180,camera.north],[-180,camera.south,camera.east,camera.north]]constuniquenewMapstring,object()boxes.forEach((box:BBox){this.index.getClusters(box,camera.zoom).forEach((feature:object){constkeyJSON.stringify((featureasRecordstring,object)[id]??feature)unique.set(key,feature)})})returnArray.from(unique.values())}}拆分后的两个包围盒在 180° 边缘存在理论重合所以必须去重。生产版优先使用稳定的点 ID 或cluster_id示例里的兜底序列化只为说明边界不能拿来处理几十万点。缩放使用整数是因为 supercluster 按整数 zoom 建树若直接把 3.2 传进去不同版本的类型处理会留下隐患。索引重建属于 CPU 密集阶段页面切后台时不必销毁静态索引但数据源版本改变必须整体替换不能在不可变索引上追加。四、异步提交只有一个入口地图标注不再互相覆盖真正让“旧点覆盖新点”消失的是提交策略。页面收到相机稳定事件后把查询放入 TaskPool 包装层回来先检查 generation再一次性替换标注集合。标注对象不是在循环里逐个增删否则一帧里会经历多个中间态用户会看到闪烁。EntryComponentstruct ViewportClusterPage{StateprivatetaskId:stringMAP-2111Stateprivategeneration:number18StateprivateclusterCount:number28StateprivatepointCount:number41StateprivatestaleDiscarded:number3Stateprivatestatus:stringSTABLEprivatecoordinator:ViewportCoordinatornewViewportCoordinator()privateclusterIndex:ClusterIndexnewClusterIndex()privateasyncrefreshViewport(raw:CameraSnapshot):Promisevoid{constrequestthis.coordinator.next(raw)constfeaturesawaitthis.runClusterTask(request.camera)if(!this.coordinator.canCommit(request.generation)){this.staleDiscardedreturn}this.generationrequest.generationthis.commitGeneration(features)hilog.info(0x0000,ClusterAtlas,MAP-2111 gen%{public}d clusters28 points41 stateSTABLE,this.generation)}privatecommitGeneration(features:object[]):void{this.replaceMapAnnotations(features)this.clusterCount28this.pointCount41this.statusSTABLE}}commitGeneration()是唯一能碰 UI 标注的地方日志也在提交后打印所以图中gen18、28 个聚合点、41 个散点和STABLE属于同一帧。这个顺序很关键如果先写日志再替换标注线上截图会出现“日志已成功、画面仍旧”的假象。页面销毁时协调器失效地图标注监听与定时采样一并释放快速重新进入会创建新的 generation 空间不会误把上个页面的返回值当成当前结果。五、相机回放只恢复姿态不恢复旧查询结果为了复现海上值班人员的操作我们把最后一次稳定相机保存为CameraSnapshot中心点约为 178.6°E缩放 3.2方向角 0°。应用从后台恢复时先调用 Map Kit 的相机更新能力恢复姿态再等待新的稳定回调。绝不能把上次的 69 个 feature 一起恢复因为数据版本可能已经变化屏幕尺寸也可能不同。本轮基准数据固定为pacific-v422480 个源点。模拟器中从东京向东连续拖动六次跨经线视口拆成两段查询最终第 18 代提交 28 个聚合点和 41 个散点途中 3 个过期返回被丢弃查询加标注替换耗时 16.4 ms。重复 30 次没有出现空白帧也没有出现 generation 倒退。手机页把诊断信息放在地图下方而不是浮在标注上任务MAP-2111、数据版本pacific-v42、边界171.4° → -166.8°、Zoom 3.2、Generation 18、过期丢弃 3、耗时 16.4 ms。这样现场截图能够直接和 HiLog 对齐又不遮挡聚合点。回放测试还刻意加入了网络数据热更新相机保持不动时把数据版本从pacific-v41切到pacific-v42先重建不可变索引再主动创建新一代查询。索引版本与 generation 是两把不同的锁前者防止旧数据被继续使用后者防止旧计算结果覆盖新画面。只递增 generation 而不换索引会得到“时序正确、内容过期”的假稳定只重建索引而不作代数检查则仍可能被在途任务回写。两者同时进入诊断信息后线上问题才能区分为数据版本错、视口边界错或提交时序错。六、这套做法的边界比成功路径更重要第一纬度仍要限制在地图与索引都能接受的范围接近极区的数据不能只靠经度拆分。第二supercluster 的半径是像素语义不是米产品若要求“500 米内合并”需要在查询前做地理距离策略不能简单把 radius 写成 500。第三源点 ID 必须稳定后端每次返回随机 ID 会破坏去重与标注复用。第四相机回调有“变化中”和“变化结束”之分。ClusterAtlas 在变化中只更新轻量提示在结束后才发起完整查询如果产品要求拖动时实时聚合可以增加 80 ms 节流但 generation 检查仍不能省。第五TaskPool 传输的数据应是可序列化快照不要把 MapComponentController 或 UI 对象带进任务。最后跨 180° 经线不是地图组件的偶发毛病而是坐标空间本身的环形边界。把边界拆分、结果去重、代数提交、姿态回放分别建模后问题从一次“修空白”变成了可测试的协议任何返回结果都必须回答它属于哪一代、查询了哪两个包围盒、能否在当前页面生命周期内提交。这个协议才是 ClusterAtlas 后续扩展到离线点、告警热区和多窗口显示时真正可复用的部分。