@bitalltech-maplibre/core 1.0.4 → 1.0.5

package/README.md

@@ -1,297 +1,340 @@
-# @bitalltech-maplibre/core
-
-BitAllTech MapLibre 核心工具包，封装地图初始化、内置底图和低空可视化特效。
-
-## 安装
-
-```bash
-npm install @bitalltech-maplibre/core maplibre-gl
-```
-
-## 基础使用
-
-```ts
-import {
-  createMap,
-  maplibregl,
-  setMaplibreToolsConfig,
-} from "@bitalltech-maplibre/core";
-import "maplibre-gl/dist/maplibre-gl.css";
-
-setMaplibreToolsConfig({
-  tdtToken: "你的天地图 token",
-});
-
-const map = createMap({
-  container: "map",
-  center: [116.39, 39.91],
-  zoom: 10.5,
-  style: "openfreemap-liberty",
-  attributionControl: false,
-});
-
-map.addControl(new maplibregl.NavigationControl(), "top-right");
-```
-
-## 地图初始化
-
-`createMap(options)` 是 `new maplibregl.Map()` 的轻量封装，额外支持内置底图类型：
-
-- `openfreemap-liberty`
-- `openfreemap-bright`
-- `openfreemap-positron`
-- `openfreemap-dark`
-- `openfreemap-fiord`
-- `tdt-image`
-- `tdt-image-label`
-
-如果 `style` 传入普通 URL 或完整 `StyleSpecification`，会原样交给 MapLibre。
-
-## 底图
-
-```ts
-import { setBaseMap } from "@bitalltech-maplibre/core";
-
-setBaseMap(map, "tdt-image-label", {
-  token: "你的天地图 token",
-  diff: false,
-});
-```
-
-天地图 token 可以通过单次调用传入，也可以通过 `setMaplibreToolsConfig({ tdtToken })` 设置全局默认值。
-
-## 低空特效
-
-```ts
-import {
-  addBreathingCircle,
-  addRadarSweep,
-  addPulseMarker,
-  addTargetLock,
-  addCountermeasureBeam,
-} from "@bitalltech-maplibre/core";
-
-const radar = addRadarSweep(map, {
-  id: "radar",
-  center: [116.39, 39.91],
-  radius: 3000,
-  color: "#22c55e",
-});
-
-const pulse = addPulseMarker(map, {
-  id: "event-pulse",
-  center: [116.41, 39.92],
-  color: "#ef4444",
-});
-
-const breathing = addBreathingCircle(map, {
-  id: "target-breathing",
-  center: [116.405, 39.915],
-  radius: 90,
-  color: "#1677ff",
-  duration: 1800,
-});
-
-const lock = addTargetLock(map, {
-  id: "target-lock",
-  center: [116.4, 39.918],
-  color: "#ff3b30",
-  size: 76,
-});
-
-const beam = addCountermeasureBeam(map, {
-  id: "countermeasure-beam",
-  center: [116.386, 39.906],
-  target: [116.399, 39.912],
-  mode: "expulsion",
-  color: "#a855f7",
-});
-
-radar.update({ radius: 5000 });
-pulse.hide();
-breathing.show();
-lock.update({ center: [116.402, 39.919] });
-radar.remove();
-```
-
-扇形扫描支持从圆心到外缘的径向渐变：
-
-```ts
-addSectorScan(map, {
-  id: "sector",
-  center: [116.39, 39.91],
-  radius: 1600,
-  startAngle: 215,
-  endAngle: 282,
-  outlineColor: "#22c55e",
-  gradient: {
-    colors: ["#f97316", "#facc15", "#22c55e"],
-    steps: 64,
-    centerOpacity: 0.08,
-    edgeOpacity: 0.34,
-  },
-});
-```
-
-当前提供：
-
-- `addBreathingCircle`
-- `addPulseMarker`
-- `addRingPulseMarker`
-- `addSectorScan`
-- `addDirectionalPulse`
-- `addRadarSweep`
-- `addDefenceCircle`
-- `addTargetLock`
-- `addCountermeasureBeam`
-- `addCoordinatedCountermeasure`
-- `addNavigationSpoofing`
-- `addBreachAlert`
-
-这些方法都会返回控制器，支持 `update()`、`show()`、`hide()` 和 `remove()`。其中 `addBreachAlert` 额外提供 `trigger(point)`、`reset()` 和 `isActive()`：trigger 开始持续预警，reset 停止，开始与结束都由业务层决定。
-
-### 电子围栏渲染
-
-电子围栏提供两个互不依赖的渲染器，由业务在创建时明确选择：
-
-- `addStandardElectronicFenceLayer`：使用一个 GeoJSON Source 和固定数量的 MapLibre 内置图层，适合几十到上百个围栏。
-- `addWebGLElectronicFenceLayer`：使用一个原生 WebGL 3D CustomLayer 绘制透明围栏、白色流动虚线或实线，以及与围栏同色的多层柔和泛光，适合少量重点围栏；首版支持 Mercator 投影。
-
-两者共用 `ElectronicFenceFeature` 和 `ElectronicFenceController`，均不依赖编辑插件。围栏必须是带稳定字符串 `id` 的 GeoJSON Polygon；矩形和圆形应先转换成 Polygon。`properties` 仅作为业务数据保存和回传，插件不会读取其中字段覆盖高度、样式或状态。
-
-`defaults.thickness` 可省略，默认使用 `1` 米；显式传入时必须大于 `0`。
-
-```ts
-import {
-  addStandardElectronicFenceLayer,
-  addWebGLElectronicFenceLayer,
-  type ElectronicFenceFeatureCollection,
-} from "@bitalltech-maplibre/core";
-
-const data: ElectronicFenceFeatureCollection = {
-  type: "FeatureCollection",
-  features: [
-    {
-      type: "Feature",
-      id: "fence-01",
-      geometry: {
-        type: "Polygon",
-        coordinates: [[
-          [116.386, 39.905],
-          [116.396, 39.905],
-          [116.396, 39.912],
-          [116.386, 39.912],
-          [116.386, 39.905],
-        ]],
-      },
-      properties: {
-        name: "核心防区",
-      },
-    },
-  ],
-};
-
-const standardFence = addStandardElectronicFenceLayer(map, {
-  id: "standard-fence",
-  defaults: {
-    baseHeight: 0,
-    height: 130,
-    thickness: 18,
-  },
-});
-
-standardFence.setData(data);
-```
-
-WebGL 版本使用相同数据和控制器 API：
-
-```ts
-const webglFence = addWebGLElectronicFenceLayer(map, {
-  id: "webgl-fence",
-  defaults: {
-    baseHeight: 0,
-    height: 150,
-    thickness: 22,
-  },
-  styles: {
-    normal: {
-      color: "#c084fc",
-      opacity: 0.18,
-      glowStrength: 1,
-      flowColor: "#ffffff",
-      flowCount: 3,
-      flowLineStyle: "dashed",
-      flowWidth: 0.18,
-    },
-  },
-  animation: {
-    enabled: true,
-    fps: 30,
-    speed: 0.35,
-    scope: "all",
-  },
-});
-
-webglFence.setData(data);
-webglFence.setFeatureState("fence-01", "alarm");
-webglFence.setFeatureActive("fence-01", true);
-```
-
-公共控制器方法：
-
-- `setData(data)`：全量替换，清除 renderer state、active 和 hidden 状态。
-- `add(feature)`：严格新增，重复 id 抛错。
-- `update(id, patch)`：严格更新业务 Feature，不读取 properties 控制渲染。
-- `removeFeature(id)`：严格删除单围栏。
-- `clear()`：清空数据但保留插件。
-- `setFeatureState(id, state)`：显式设置 normal、warning、alarm 或 disabled 渲染状态。
-- `setFeatureActive(id, active)`：设置临时高亮，不修改业务 Feature。
-- `setFeatureVisible(id, visible)`：临时控制单围栏显隐。
-- `show()`、`hide()`：控制整个插件显隐；WebGL 版隐藏时暂停动画。
-- `destroy()`：释放 Source、Layer、事件和 WebGL 资源。
-
-当 `interactive` 未设为 `false` 时，两种渲染器都会通过地图触发 `fence.click`、`fence.mouseenter` 和 `fence.mouseleave`，事件载荷包含 `instanceId`、`renderer`、`id`、`feature` 和 `originalEvent`。
-
-### 围栏闯入预警
-
-`addBreachAlert` 用于无人机闯入电子围栏时的复合预警，三段叠加且各自独立开关。trigger 后三段持续播放，直到业务层调用 reset() 才停止：
-
-- 围栏高频闪烁：接触瞬间围栏由正常色（蓝/绿）切到高频闪烁警报红
-- 接触点涟漪扩散：以接触点为中心持续向外扩散红色涟漪
-- 战术框闪烁：全屏或局部 DOM 边框高频闪烁
-
-```ts
-import { addBreachAlert, createFenceCircle } from "@bitalltech-maplibre/core";
-
-// fence 支持直接传入 edit 插件 getAll() 的 FeatureCollection，
-// 或单个 Polygon / MultiPolygon / Feature；圆形用 createFenceCircle 构造。
-const fence = createFenceCircle([116.39, 39.91], 1000);
-
-const alert = addBreachAlert(map, {
-  id: "breach-zone",
-  center: [116.39, 39.91],
-  fence,                         // 围栏几何
-  fenceColor: "#1677ff",         // 正常态蓝
-  fenceAlertColor: "#ff3b30",    // 警报红
-  fenceFlash: true,              // 围栏闪烁：开
-  ripple: true,                  // 涟漪：开
-  tacticalFlash: false,          // 战术框：关
-});
-
-// 业务层判定闯入后触发（几何判定与目标分类归业务层）
-detector.on("breach", ({ point }) => {
-  alert.trigger(point);
-});
-
-alert.reset();   // 业务层判定解警后停止
-alert.remove();  // 销毁（连 DOM 一起清理）
-```
-
-> 插件只负责视觉表现，不判定「是否闯入」「目标是否黑飞/未知」，也不决定警报持续多久——这些都由业务层完成，插件只暴露 trigger 与 reset。
-
-## 常用导出
-
-- `createMap`、`maplibregl`
-- `setMaplibreToolsConfig`、`getMaplibreToolsConfig`
-- `getBaseMapStyle`、`setBaseMap`
-- 低空特效方法和对应类型
+# @bitalltech-maplibre/core
+
+BitAllTech MapLibre 核心工具包，封装地图初始化、内置底图和低空可视化特效。
+
+## 安装
+
+```bash
+npm install @bitalltech-maplibre/core maplibre-gl
+```
+
+## 基础使用
+
+```ts
+import {
+  createMap,
+  maplibregl,
+  setMaplibreToolsConfig,
+} from "@bitalltech-maplibre/core";
+import "maplibre-gl/dist/maplibre-gl.css";
+
+setMaplibreToolsConfig({
+  tdtToken: "你的天地图 token",
+});
+
+const map = createMap({
+  container: "map",
+  center: [116.39, 39.91],
+  zoom: 10.5,
+  style: "openfreemap-liberty",
+  attributionControl: false,
+});
+
+map.addControl(new maplibregl.NavigationControl(), "top-right");
+```
+
+## 地图初始化
+
+`createMap(options)` 是 `new maplibregl.Map()` 的轻量封装，额外支持内置底图类型：
+
+- `openfreemap-liberty`
+- `openfreemap-bright`
+- `openfreemap-positron`
+- `openfreemap-dark`
+- `openfreemap-fiord`
+- `tdt-image`
+- `tdt-image-label`
+
+如果 `style` 传入普通 URL 或完整 `StyleSpecification`，会原样交给 MapLibre。
+
+## 底图
+
+```ts
+import { setBaseMap } from "@bitalltech-maplibre/core";
+
+setBaseMap(map, "tdt-image-label", {
+  token: "你的天地图 token",
+  diff: false,
+});
+```
+
+天地图 token 可以通过单次调用传入，也可以通过 `setMaplibreToolsConfig({ tdtToken })` 设置全局默认值。
+
+## 低空特效
+
+```ts
+import {
+  addBreathingCircle,
+  addRadarSweep,
+  addRadarPowerGroup,
+  addPulseMarker,
+  addTargetLock,
+  addCountermeasureBeam,
+} from "@bitalltech-maplibre/core";
+
+const radar = addRadarSweep(map, {
+  id: "radar",
+  center: [116.39, 39.91],
+  radius: 3000,
+  color: "#22c55e",
+});
+
+const pulse = addPulseMarker(map, {
+  id: "event-pulse",
+  center: [116.41, 39.92],
+  color: "#ef4444",
+});
+
+const breathing = addBreathingCircle(map, {
+  id: "target-breathing",
+  center: [116.405, 39.915],
+  radius: 90,
+  color: "#1677ff",
+  duration: 1800,
+});
+
+const lock = addTargetLock(map, {
+  id: "target-lock",
+  center: [116.4, 39.918],
+  color: "#ff3b30",
+  size: 76,
+});
+
+const beam = addCountermeasureBeam(map, {
+  id: "countermeasure-beam",
+  center: [116.386, 39.906],
+  target: [116.399, 39.912],
+  mode: "expulsion",
+  color: "#a855f7",
+});
+
+radar.update({ radius: 5000 });
+pulse.hide();
+breathing.show();
+lock.update({ center: [116.402, 39.919] });
+radar.remove();
+```
+
+### 批量雷达威力图
+
+多个雷达威力图可以共用一个 GeoJSON source 和一组固定图层。调用时会先创建空 source/layer；如果不传 `radars`，也可以在接口数据返回后再调用 `setData`。
+
+```ts
+import { addRadarPowerGroup } from "@bitalltech-maplibre/core";
+
+map.on("load", () => {
+  const radarPower = addRadarPowerGroup(map, {
+    id: "radar-power",
+    // 可选：插入到指定图层之前；layerIds 会按 fill、core、ring、crosshair、labels 顺序创建。
+    beforeId: "target-layer",
+  });
+
+  // 数据返回后只更新共享 source，不重新创建图层，因此图层顺序保持不变。
+  radarPower.setData([
+    {
+      id: "radar-west",
+      center: [116.382, 39.903],
+      radius: 4000,
+      color: "#22c55e",
+      ringCount: 4,
+    },
+    {
+      id: "radar-east",
+      center: [116.42, 39.915],
+      radius: 3000,
+      color: "#38bdf8",
+      visible: true,
+    },
+  ]);
+
+  radarPower.setRadarVisible("radar-east", false);
+  radarPower.updateRadar("radar-west", { radius: 5000 });
+
+  // 不再使用时一次性清理整组 source/layer。
+  // radarPower.remove();
+});
+```
+
+`radarPower.sourceId` 是共享 GeoJSON source，`radarPower.layerIds` 是按绘制顺序排列的固定图层 id。插件只保证威力图组内部顺序；雷达组与目标、轨迹、测距等其他业务组之间的顺序，建议由业务侧统一图层管理器安排。
+扇形扫描支持从圆心到外缘的径向渐变：
+
+```ts
+addSectorScan(map, {
+  id: "sector",
+  center: [116.39, 39.91],
+  radius: 1600,
+  startAngle: 215,
+  endAngle: 282,
+  outlineColor: "#22c55e",
+  gradient: {
+    colors: ["#f97316", "#facc15", "#22c55e"],
+    steps: 64,
+    centerOpacity: 0.08,
+    edgeOpacity: 0.34,
+  },
+});
+```
+
+当前提供：
+
+- `addBreathingCircle`
+- `addPulseMarker`
+- `addRingPulseMarker`
+- `addSectorScan`
+- `addDirectionalPulse`
+- `addRadarSweep`
+- `addRadarPowerGroup`
+- `addDefenceCircle`
+- `addTargetLock`
+- `addCountermeasureBeam`
+- `addCoordinatedCountermeasure`
+- `addNavigationSpoofing`
+- `addBreachAlert`
+
+这些方法都会返回控制器，支持 `update()`、`show()`、`hide()` 和 `remove()`。其中 `addBreachAlert` 额外提供 `trigger(point)`、`reset()` 和 `isActive()`：trigger 开始持续预警，reset 停止，开始与结束都由业务层决定。
+
+### 电子围栏渲染
+
+电子围栏提供两个互不依赖的渲染器，由业务在创建时明确选择：
+
+- `addStandardElectronicFenceLayer`：使用一个 GeoJSON Source 和固定数量的 MapLibre 内置图层，适合几十到上百个围栏。
+- `addWebGLElectronicFenceLayer`：使用一个原生 WebGL 3D CustomLayer 绘制透明围栏、白色流动虚线或实线，以及与围栏同色的多层柔和泛光，适合少量重点围栏；首版支持 Mercator 投影。
+
+两者共用 `ElectronicFenceFeature` 和 `ElectronicFenceController`，均不依赖编辑插件。围栏必须是带稳定字符串 `id` 的 GeoJSON Polygon；矩形和圆形应先转换成 Polygon。`properties` 仅作为业务数据保存和回传，插件不会读取其中字段覆盖高度、样式或状态。
+
+`defaults.thickness` 可省略，默认使用 `1` 米；显式传入时必须大于 `0`。
+
+```ts
+import {
+  addStandardElectronicFenceLayer,
+  addWebGLElectronicFenceLayer,
+  type ElectronicFenceFeatureCollection,
+} from "@bitalltech-maplibre/core";
+
+const data: ElectronicFenceFeatureCollection = {
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      id: "fence-01",
+      geometry: {
+        type: "Polygon",
+        coordinates: [[
+          [116.386, 39.905],
+          [116.396, 39.905],
+          [116.396, 39.912],
+          [116.386, 39.912],
+          [116.386, 39.905],
+        ]],
+      },
+      properties: {
+        name: "核心防区",
+      },
+    },
+  ],
+};
+
+const standardFence = addStandardElectronicFenceLayer(map, {
+  id: "standard-fence",
+  defaults: {
+    baseHeight: 0,
+    height: 130,
+    thickness: 18,
+  },
+});
+
+standardFence.setData(data);
+```
+
+WebGL 版本使用相同数据和控制器 API：
+
+```ts
+const webglFence = addWebGLElectronicFenceLayer(map, {
+  id: "webgl-fence",
+  defaults: {
+    baseHeight: 0,
+    height: 150,
+    thickness: 22,
+  },
+  styles: {
+    normal: {
+      color: "#c084fc",
+      opacity: 0.18,
+      glowStrength: 1,
+      flowColor: "#ffffff",
+      flowCount: 3,
+      flowLineStyle: "dashed",
+      flowWidth: 0.18,
+    },
+  },
+  animation: {
+    enabled: true,
+    fps: 30,
+    speed: 0.35,
+    scope: "all",
+  },
+});
+
+webglFence.setData(data);
+webglFence.setFeatureState("fence-01", "alarm");
+webglFence.setFeatureActive("fence-01", true);
+```
+
+公共控制器方法：
+
+- `setData(data)`：全量替换，清除 renderer state、active 和 hidden 状态。
+- `add(feature)`：严格新增，重复 id 抛错。
+- `update(id, patch)`：严格更新业务 Feature，不读取 properties 控制渲染。
+- `removeFeature(id)`：严格删除单围栏。
+- `clear()`：清空数据但保留插件。
+- `setFeatureState(id, state)`：显式设置 normal、warning、alarm 或 disabled 渲染状态。
+- `setFeatureActive(id, active)`：设置临时高亮，不修改业务 Feature。
+- `setFeatureVisible(id, visible)`：临时控制单围栏显隐。
+- `show()`、`hide()`：控制整个插件显隐；WebGL 版隐藏时暂停动画。
+- `destroy()`：释放 Source、Layer、事件和 WebGL 资源。
+
+当 `interactive` 未设为 `false` 时，两种渲染器都会通过地图触发 `fence.click`、`fence.mouseenter` 和 `fence.mouseleave`，事件载荷包含 `instanceId`、`renderer`、`id`、`feature` 和 `originalEvent`。
+
+### 围栏闯入预警
+
+`addBreachAlert` 用于无人机闯入电子围栏时的复合预警，三段叠加且各自独立开关。trigger 后三段持续播放，直到业务层调用 reset() 才停止：
+
+- 围栏高频闪烁：接触瞬间围栏由正常色（蓝/绿）切到高频闪烁警报红
+- 接触点涟漪扩散：以接触点为中心持续向外扩散红色涟漪
+- 战术框闪烁：全屏或局部 DOM 边框高频闪烁
+
+```ts
+import { addBreachAlert, createFenceCircle } from "@bitalltech-maplibre/core";
+
+// fence 支持直接传入 edit 插件 getAll() 的 FeatureCollection，
+// 或单个 Polygon / MultiPolygon / Feature；圆形用 createFenceCircle 构造。
+const fence = createFenceCircle([116.39, 39.91], 1000);
+
+const alert = addBreachAlert(map, {
+  id: "breach-zone",
+  center: [116.39, 39.91],
+  fence,                         // 围栏几何
+  fenceColor: "#1677ff",         // 正常态蓝
+  fenceAlertColor: "#ff3b30",    // 警报红
+  fenceFlash: true,              // 围栏闪烁：开
+  ripple: true,                  // 涟漪：开
+  tacticalFlash: false,          // 战术框：关
+});
+
+// 业务层判定闯入后触发（几何判定与目标分类归业务层）
+detector.on("breach", ({ point }) => {
+  alert.trigger(point);
+});
+
+alert.reset();   // 业务层判定解警后停止
+alert.remove();  // 销毁（连 DOM 一起清理）
+```
+
+> 插件只负责视觉表现，不判定「是否闯入」「目标是否黑飞/未知」，也不决定警报持续多久——这些都由业务层完成，插件只暴露 trigger 与 reset。
+
+## 常用导出
+
+- `createMap`、`maplibregl`
+- `setMaplibreToolsConfig`、`getMaplibreToolsConfig`
+- `getBaseMapStyle`、`setBaseMap`
+- 低空特效方法和对应类型