my-openlayer 2.4.12 → 2.5.1

package/docs/Line.md

@@ -1,187 +1,215 @@
-# Line 线要素类
-
-`Line` 类用于在地图上绘制线要素，支持 GeoJSON 数据加载、自定义样式和图层管理。
-
-## 构造函数
-
-```typescript
-const line = new Line(map: Map);
-```
-
-- **map**: OpenLayers 地图实例。
-
-## 接口定义
-
-### LineOptions
-
-配置线图层的样式、属性和行为。继承自 `BaseOptions`, `StyleOptions`, `TextOptions`。
-
-| 属性 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| **基础配置** | | |
-| `layerName` | `string` | 图层名称，用于唯一标识和管理图层 |
-| `zIndex` | `number` | 图层层级，默认自动处理 |
-| `visible` | `boolean` | 图层是否可见，默认 `true` |
-| `opacity` | `number` | 图层透明度 (0-1) |
-| `fitView` | `boolean` | 添加要素后是否自动缩放视图以适应要素范围 |
-| **样式配置** | | |
-| `strokeColor` | `string` \| `number[]` | 线条颜色，如 `'#ff0000'` 或 `[255, 0, 0, 1]` |
-| `strokeWidth` | `number` | 线条宽度（像素） |
-| `lineDash` | `number[]` | 虚线模式，如 `[10, 10]` 表示 10px 实线 10px 间隔 |
-| `lineDashOffset` | `number` | 虚线偏移量 |
-| `style` | `Style` \| `Function` | 自定义 OpenLayers 样式或样式函数 |
-| **文本标注** | | |
-| `textVisible` | `boolean` | 是否显示文本标注 |
-| `textCallBack` | `(feature) => string` | 获取文本内容的回调函数 |
-| `textFont` | `string` | 字体样式，默认 `'12px sans-serif'` |
-| `textFillColor` | `string` | 文本填充颜色 |
-| `textStrokeColor` | `string` | 文本描边颜色 |
-| `textStrokeWidth` | `number` | 文本描边宽度 |
-| `textOffsetY` | `number` | 文本 Y 轴偏移量 |
-| **其他** | | |
-| `type` | `string` | 线条类型标识，会写入 Feature 的属性中 |
-
-### MapJSONData (GeoJSON)
-
-标准的 GeoJSON 格式数据结构。
-
-```typescript
-interface MapJSONData {
-  type: string;        // 通常为 "FeatureCollection"
-  name?: string;       // 数据集名称
-  features: FeatureData[]; // 要素数组
-}
-
-interface FeatureData {
-  type: string;        // "Feature"
-  properties: any;     // 属性对象
-  geometry: {
-    type: "LineString" | "MultiLineString";
-    coordinates: number[][] | number[][][];
-  };
-}
-```
-
-## 方法
-
-### addLine
-
-添加线要素图层。
-
-```typescript
-addLine(data: MapJSONData, options?: LineOptions): VectorLayer<VectorSource>
-```
-
-| 参数 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `data` | `MapJSONData` | GeoJSON 格式的线数据 |
-| `options` | `LineOptions` | 图层配置项 |
-
-**返回**: 创建的 `VectorLayer` 实例。
-
-### addLineByUrl
-
-从 URL 加载并添加线要素图层。
-
-```typescript
-addLineByUrl(url: string, options?: LineOptions): VectorLayer<VectorSource>
-```
-
-| 参数 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `url` | `string` | GeoJSON 数据的 URL 地址 |
-| `options` | `LineOptions` | 图层配置项 |
-
-**返回**: 创建的 `VectorLayer` 实例。
-
-### removeLineLayer
-
-根据图层名称移除线图层。
-
-```typescript
-removeLineLayer(layerName: string): void
-```
-
-| 参数 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `layerName` | `string` | 要移除的图层名称 |
-
-## 使用示例
-
-### 基础用法
-
-```typescript
-const lineModule = map.getLine();
-
-// GeoJSON 数据
-const lineData = {
-  type: 'FeatureCollection',
-  features: [
-    {
-      type: 'Feature',
-      geometry: {
-        type: 'LineString',
-        coordinates: [[119.8, 29.9], [119.9, 30.0]]
-      },
-      properties: { name: '线路1', status: 'active' }
-    }
-  ]
-};
-
-// 添加红色实线
-lineModule.addLine(lineData, {
-  layerName: 'base-line',
-  strokeColor: '#ff0000',
-  strokeWidth: 3,
-  fitView: true
-});
-```
-
-### 虚线与标注
-
-```typescript
-lineModule.addLine(lineData, {
-  layerName: 'dash-line',
-  strokeColor: '#0000ff',
-  strokeWidth: 2,
-  lineDash: [10, 5], // 10px实线，5px间隔
-  textVisible: true,
-  textFillColor: '#000',
-  textStrokeColor: '#fff',
-  textStrokeWidth: 2,
-  // 动态获取显示的文本
-  textCallBack: (feature) => feature.get('name')
-});
-```
-
-### 自定义样式函数
-
-```typescript
-import { Style, Stroke } from 'ol/style';
-
-lineModule.addLine(lineData, {
-  layerName: 'custom-style-line',
-  // 根据属性动态设置颜色
-  style: (feature) => {
-    const status = feature.get('properties').status;
-    const color = status === 'active' ? 'green' : 'gray';
-    
-    return new Style({
-      stroke: new Stroke({
-        color: color,
-        width: 4
-      })
-    });
-  }
-});
-```
-
-### 从接口加载
-
-```typescript
-lineModule.addLineByUrl('/api/lines/all.json', {
-  layerName: 'api-lines',
-  strokeColor: 'orange',
-  strokeWidth: 2
-});
-```
+# Line 线要素类
+
+`Line` 类用于在地图上管理静态线和流动线，支持 GeoJSON 数据加载、自定义样式、图层管理以及沿线运动符号 / 流光动画。
+
+## 构造函数
+
+```typescript
+const line = new Line(map: Map);
+```
+
+## 核心类型
+
+### LineOptions
+
+静态线配置，继承自 `BaseOptions`、`StyleOptions`、`TextOptions`。
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `layerName` | `string` | 图层名称 |
+| `strokeColor` | `string \| number[]` | 线颜色 |
+| `strokeWidth` | `number` | 线宽 |
+| `lineDash` | `number[]` | 虚线样式 |
+| `lineDashOffset` | `number` | 虚线偏移 |
+| `style` | `Style \| Style[] \| (feature) => Style \| Style[]` | 自定义静态线样式 |
+| `dataProjection` | `string` | 输入数据投影 |
+| `featureProjection` | `string` | 要素投影 |
+| `projectionOptOptions` | `any` | 旧版投影参数，兼容保留 |
+
+### FlowLineOptions
+
+流动线配置，继承 `LineOptions`。
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `loop` | `boolean` | 是否循环播放，默认 `true` |
+| `autoStart` | `boolean` | 创建后是否自动开始，默认 `true` |
+| `duration` | `number` | 单轮动画时长，默认 `4000` |
+| `speed` | `number` | 动画速度倍率，小于等于 `0` 时回退为 `1` |
+| `showBaseLine` | `boolean` | 是否显示基础静态线，默认 `true` |
+| `animationMode` | `'icon' \| 'dash' \| 'icon+dash'` | 动画模式 |
+| `flowSymbol` | `{ src?: string; scale?: number; color?: string; rotateWithView?: boolean; count?: number; spacing?: number }` | 沿线运动符号配置 |
+
+### FlowLineLayerHandle
+
+```typescript
+interface FlowLineLayerHandle {
+  layer: VectorLayer<VectorSource>
+  animationLayer: VectorLayer<VectorSource>
+  start: () => void
+  pause: () => void
+  resume: () => void
+  stop: () => void
+  setVisible: (visible: boolean) => void
+  updateData: (data: MapJSONData) => void
+  remove: () => void
+}
+```
+
+- `layer` 始终是基础线图层。
+- `animationLayer` 始终是动画图层。
+- 即使 `showBaseLine: false`，handle 结构也保持完整。
+
+## 公开方法
+
+### addLine
+
+```typescript
+addLine(data: MapJSONData, options?: LineOptions): VectorLayer<VectorSource>
+```
+
+添加静态线图层。
+
+### addLineByUrl
+
+```typescript
+addLineByUrl(url: string, options?: LineOptions): VectorLayer<VectorSource>
+```
+
+从 URL 加载并添加静态线图层。
+
+### removeLineLayer
+
+```typescript
+removeLineLayer(layerName: string): void
+```
+
+移除静态线图层。
+
+## 流动线 / 动态图标线
+
+### addFlowLine
+
+```typescript
+addFlowLine(data: MapJSONData, options?: FlowLineOptions): FlowLineLayerHandle | null
+```
+
+支持 `LineString` 和 `MultiLineString`。`MultiLineString` 会在内部拆解后参与动画。
+`flowSymbol.src` 不限于箭头，可以是船、车、粒子、标记等任意沿线运动符号；未传时内部会使用默认矢量 moving symbol。
+
+### addFlowLineByUrl
+
+```typescript
+addFlowLineByUrl(url: string, options?: FlowLineOptions): Promise<FlowLineLayerHandle | null>
+```
+
+从 URL 加载 GeoJSON 后创建流动线。网络失败、JSON 解析失败、数据结构非法时返回 `null`。
+
+### removeFlowLineLayer
+
+```typescript
+removeFlowLineLayer(layerName: string): void
+```
+
+按图层名移除流动线的基础图层与动画图层。
+
+## 使用示例
+
+### 基础静态线
+
+```typescript
+const lineModule = map.getLine();
+
+lineModule.addLine(lineData, {
+  layerName: 'base-line',
+  strokeColor: '#ff0000',
+  strokeWidth: 3
+});
+```
+
+### 流动线基础用法
+
+```typescript
+const lineModule = map.getLine();
+const flow = lineModule.addFlowLine(lineData, {
+  layerName: 'river-flow',
+  animationMode: 'icon+dash',
+  strokeColor: '#19b1ff',
+  strokeWidth: 3,
+  lineDash: [18, 12],
+  flowSymbol: {
+    src: '/symbols/boat.svg',
+    scale: 0.9,
+    color: '#19b1ff',
+    rotateWithView: true,
+    count: 2,
+    spacing: 0.2
+  },
+  duration: 3600
+});
+```
+
+### pause / resume / remove
+
+```typescript
+flow?.pause();
+flow?.resume();
+flow?.stop();
+flow?.remove();
+```
+
+### updateData
+
+```typescript
+flow?.updateData({
+  type: 'FeatureCollection',
+  features: [
+    {
+      type: 'Feature',
+      properties: { name: '支流' },
+      geometry: {
+        type: 'MultiLineString',
+        coordinates: [
+          [[119.8, 29.9], [119.9, 30.0]],
+          [[119.82, 30.02], [119.95, 30.06]]
+        ]
+      }
+    }
+  ]
+});
+```
+
+### 显式投影字段示例
+
+```typescript
+lineModule.addFlowLine(projectedLineData, {
+  layerName: 'projected-flow',
+  animationMode: 'icon+dash',
+  dataProjection: 'EPSG:4490',
+  featureProjection: 'EPSG:3857',
+  flowSymbol: {
+    src: '/symbols/ship.svg',
+    scale: 1,
+    count: 1,
+    spacing: 0.15
+  }
+});
+```
+
+默认输入按经纬度 GeoJSON 处理；如果地图使用其他投影，建议显式传入 `dataProjection` / `featureProjection`。
+
+## 样式兼容说明
+
+- `strokeColor`、`strokeWidth`、`lineDash`、`lineDashOffset`、`style` 继续兼容。
+- 当传入 `style` 时，它只控制基础线图层，不直接控制 moving symbol。
+- `animationMode: 'dash'` 未传虚线参数时，内部会补默认虚线样式，确保流光可见。
+- `animationMode: 'icon+dash'` 会同时渲染：
+  - 基础线图层
+  - 动画虚线图层
+  - `postrender` moving symbol 动画
+
+## 与旧版 projectionOptOptions 的关系
+
+- 新项目推荐使用 `dataProjection` / `featureProjection`。
+- `projectionOptOptions` 仅用于兼容旧代码，不再作为主入口。
+- 当两者同时存在时，显式字段 `dataProjection` / `featureProjection` 优先级更高。