refactor(layers): extract LayerRelativeCoords (stage-1 1.4)

Author: lzxue

.changeset/refactor-layers-p4-stage1-relcoords.md

@@ -0,0 +1,27 @@
+---
+'@antv/l7-layers': patch
+---
+
+refactor(layers): extract LayerRelativeCoords (stage-1 1.4)
+
+P4 阶段 1 第三刀（1.4，对外透明 delegate，零 API/行为变更）。
+
+从 BaseLayer 抽出相对坐标状态与转换 delegate `core/LayerRelativeCoords.ts`，
+收口 3 个原 protected 字段（`relativeOrigin` / `originalExtent` /
+`absoluteDataArray`）与 4 个方法：`processRelativeCoordinates`（原 protected，
+自我触发，init / setData 钩子调用）、`getAbsoluteData` / `getRelativeOrigin` /
+`getOriginalExtent`（public getter）。
+
+BaseLayer 保留全部对外签名作为薄转发：`processRelativeCoordinates` 保留
+protected 自调用（内部 call site 不变），3 getter 转发到 delegate。
+`processRelativeCoordinates` 核心逻辑字节级镜像原实现——读 `getLayerConfig`
+取 `enableRelativeCoordinates`（经 `(layerConfig as any)?.` 兼容字段不在类型上），
+经公开 `getSource()` 读写 `source.data.dataArray`（同引用，mutation 生效），
+不跨类直访 protected `layerSource`。
+
+3 字段原 protected、外部全走 ILayer getter 访问（grep 已确认无一字段直读），
+搬入 delegate 安全。`@antv/l7-utils` 的 `processRelativeCoordinates` 函数
+import 从 BaseLayer 上移至 delegate（阶段 0 已就绪，不跨包）。
+
+验证：eslint 0 error、prettier 通过、layers father build 275 files（含
+declaration d.ts 类型检查）、jest layers+maps 76 suites/653 passed。

docs/refactoring/layers/PLAN.md

@@ -72,7 +72,7 @@ citybuilding/ geometry/ — 12 个具体图层 extends BaseLayer（各自只 ove
 | 1.1  | `LayerStyleFluent`    | 流式 API（`color/size/shape/texture/rotate/filter/label/style/scale/animate/active/select` → `return this`）+ `pendingStyleAttributes` 注册 + `encodeStyle` + `splitValuesAndCallbackInAttribute`（~200 行）                                                                                                                                                                                                                                                                                                                       | plugin 已吃一半，本步收口方法体                                  |
 | 1.2  | `LayerModelManager`   | `models[]/layerModel/buildLayerModel/buildModels/rebuildModels/initLayerModels/createAttributes/updateModelData/prepareBuildModel/clearModels/uniformBuffers/getPickingUniformBuffer` + blend/`BlendTypes`（~250 行）                                                                                                                                                                                                                                                                                                              | —                                                                |
 | 1.3  | `LayerPickingManager` | `pick/boxSelect/active/setActive/select/setSelect` + `pickedFeatureID/selectedFeatureID/currentPickId/needPick` + set/get + `hooks.beforeHighlight/beforeSelect` 编排 + `setTimeout(reRender,1)` 收敛为可读调度（~150 行）。**1.3a ☑**：`pick/boxSelect/needPick` + `currentPickId/selectedFeatureID` 搬入 delegate，BaseLayer 薄转发。**1.3b ☑**：`active/setActive/select/setSelect` + hooks 编排 + setTimeout 收敛搬入 delegate；`reRender`（protected）经 ctor 注入 `rerender` 回调桥接（箭头延迟求值），零 protected 跨类访问 | `LayerPickService` 已抽出（picking 委托），本步收口**状态+编排** |
-| 1.4  | `LayerRelativeCoords` | `relativeOrigin/originalExtent/absoluteDataArray/processRelativeCoordinates/getAbsoluteData/getRelativeOrigin/getOriginalExtent`（~50 行，函数已 `@antv/l7-utils`）                                                                                                                                                                                                                                                                                                                                                                | —                                                                |
+| 1.4  | `LayerRelativeCoords` | `relativeOrigin/originalExtent/absoluteDataArray/processRelativeCoordinates/getAbsoluteData/getRelativeOrigin/getOriginalExtent`（~50 行，函数已 `@antv/l7-utils`）                                                                                                                                                                                                                                                                                                                                                                | ☑                                                                |
 | 1.5  | `LayerAnimateState`   | `animateOptions/animateStartTime/animateStatus/getTime/setAnimateStartTime/stopAnimate/getLayerAnimateTime`（~40 行）                                                                                                                                                                                                                                                                                                                                                                                                              | —                                                                |
 | 1.6  | `LayerScaleLegend`    | `scaleOptions/getScaleOptions/getScale/getLegend/getLegendItems`（`invertExtent/ticks/domain` 三分支分类法，~80 行）                                                                                                                                                                                                                                                                                                                                                                                                               | —                                                                |
 | 1.7  | `LayerMaskManager`    | `addMask/removeMask/disableMask/enableMask/addMaskLayer/removeMaskLayer` + `masks[]`（~50 行）                                                                                                                                                                                                                                                                                                                                                                                                                                     | ☑                                                                |

packages/layers/src/core/BaseLayer.ts

@@ -41,7 +41,7 @@ import type {
   Triangulation,
 } from '@antv/l7-core';
 import { BlendType, IDebugLog, ILayerStage, globalConfigService } from '@antv/l7-core';
-import { lodashUtil, processRelativeCoordinates } from '@antv/l7-utils';
+import { lodashUtil } from '@antv/l7-utils';
 import { EventEmitter } from 'eventemitter3';
 import { createPlugins } from '../plugins';
 import type Source from '../source';
@@ -50,6 +50,7 @@ import { createMultiPassRenderer, normalizePasses } from '../utils/multiPassRend
 import LayerMaskManager from './LayerMaskManager';
 import LayerPickingManager from './LayerPickingManager';
 import LayerPickService from './LayerPickService';
+import LayerRelativeCoords from './LayerRelativeCoords';
 import LayerVisibilityZoom from './LayerVisibilityZoom';
 import TextureService from './TextureService';
 const { isEqual, isFunction, isNumber, isObject, isPlainObject, isUndefined } = lodashUtil;
@@ -217,9 +218,11 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
   protected animateOptions: IAnimateOption = { enable: false };
 
   // 相对坐标系支持
-  protected relativeOrigin: [number, number] = [0, 0];
-  protected originalExtent: [number, number, number, number] = [0, 0, 0, 0];
-  protected absoluteDataArray: IParseDataItem[] = []; // 保存绝对坐标数据用于交互
+  /**
+   * 相对坐标状态与转换 delegate（阶段 1.4）。原 protected 字段搬入；
+   * 外部经 ILayer getter 访问，`processRelativeCoordinates` 经 protected 薄转发。
+   */
+  protected relativeCoordsManager: LayerRelativeCoords = new LayerRelativeCoords(this);
 
   /**
    * 图层容器
@@ -1249,46 +1252,28 @@ export default class BaseLayer<ChildLayerStyleOptions = {}>
    * 处理相对坐标转换
    */
   protected processRelativeCoordinates() {
-    const layerConfig = this.getLayerConfig();
-    const enableRelativeCoordinates = layerConfig?.enableRelativeCoordinates;
-
-    if (!enableRelativeCoordinates || !this.layerSource || !this.layerSource.data) {
-      return;
-    }
-
-    // 保存原始绝对坐标数据用于交互
-    this.absoluteDataArray = [...this.layerSource.data.dataArray];
-
-    // 处理相对坐标转换
-    const result = processRelativeCoordinates(this.layerSource.data.dataArray, {
-      enableRelativeCoordinates: true,
-    });
-
-    // 更新source数据为相对坐标
-    this.layerSource.data.dataArray = result.dataArray;
-    this.relativeOrigin = result.relativeOrigin;
-    this.originalExtent = result.originalExtent;
+    this.relativeCoordsManager.processRelativeCoordinates();
   }
 
   /**
    * 获取绝对坐标数据（用于交互计算）
    */
   public getAbsoluteData() {
-    return this.absoluteDataArray;
+    return this.relativeCoordsManager.getAbsoluteData();
   }
 
   /**
    * 获取相对坐标原点
    */
   public getRelativeOrigin() {
-    return this.relativeOrigin;
+    return this.relativeCoordsManager.getRelativeOrigin();
   }
 
   /**
    * 获取原始数据范围
    */
   public getOriginalExtent() {
-    return this.originalExtent;
+    return this.relativeCoordsManager.getOriginalExtent();
   }
 
   protected sourceEvent = () => {

packages/layers/src/core/LayerRelativeCoords.ts

@@ -0,0 +1,77 @@
+import type { IParseDataItem } from '@antv/l7-core';
+import { processRelativeCoordinates } from '@antv/l7-utils';
+import type BaseLayer from './BaseLayer';
+
+/**
+ * 相对坐标状态与转换 delegate（阶段 1.4）。
+ *
+ * 收口 BaseLayer 中相对坐标相关逻辑：
+ * - 状态 `relativeOrigin` / `originalExtent` / `absoluteDataArray`（均原 protected
+ *   字段，外部经 ILayer getter 访问、无一字段直读，已确认）
+ * - 转换 `processRelativeCoordinates()`（原 protected，读 `getLayerConfig`
+ *   + 经公开 `getSource()` 读写 `source.data.dataArray`）
+ * - getter `getAbsoluteData` / `getRelativeOrigin` / `getOriginalExtent`
+ *
+ * `processRelativeCoordinates` 在 BaseLayer 内部多处调用（init / setData 钩子），
+ * 经 BaseLayer 保留 protected 薄转发桥接；逻辑字节级镜像原实现。
+ * `layerSource`（protected）不跨类直访——经公开 `layer.getSource()` 返回同一
+ * 引用后读写 `data.dataArray`，mutation 经引用生效。子类 override 路径不变
+ * （全仓无子类 override 这一组，已确认）。
+ */
+export default class LayerRelativeCoords {
+  private layer: BaseLayer;
+  private relativeOrigin: [number, number] = [0, 0];
+  private originalExtent: [number, number, number, number] = [0, 0, 0, 0];
+  private absoluteDataArray: IParseDataItem[] = []; // 保存绝对坐标数据用于交互
+
+  constructor(layer: BaseLayer) {
+    this.layer = layer;
+  }
+
+  /**
+   * 处理相对坐标转换
+   */
+  public processRelativeCoordinates() {
+    const layerConfig = this.layer.getLayerConfig();
+    const enableRelativeCoordinates = (layerConfig as any)?.enableRelativeCoordinates;
+
+    const layerSource = this.layer.getSource();
+    if (!enableRelativeCoordinates || !layerSource || !layerSource.data) {
+      return;
+    }
+
+    // 保存原始绝对坐标数据用于交互
+    this.absoluteDataArray = [...layerSource.data.dataArray];
+
+    // 处理相对坐标转换
+    const result = processRelativeCoordinates(layerSource.data.dataArray, {
+      enableRelativeCoordinates: true,
+    });
+
+    // 更新 source 数据为相对坐标
+    layerSource.data.dataArray = result.dataArray;
+    this.relativeOrigin = result.relativeOrigin;
+    this.originalExtent = result.originalExtent;
+  }
+
+  /**
+   * 获取绝对坐标数据（用于交互计算）
+   */
+  public getAbsoluteData() {
+    return this.absoluteDataArray;
+  }
+
+  /**
+   * 获取相对坐标原点
+   */
+  public getRelativeOrigin() {
+    return this.relativeOrigin;
+  }
+
+  /**
+   * 获取原始数据范围
+   */
+  public getOriginalExtent() {
+    return this.originalExtent;
+  }
+}