使用手册

安装

npm i @loongbao-web-gis-utils/draw-utils-openlayer

draw-utils-openlayer 自动安装 draw-utils-core。OL 适配版本 10.9.0。

快速开始

import { DrawTool } from '@loongbao-web-gis-utils/draw-utils-core'
import { OpenLayerAdapter } from '@loongbao-web-gis-utils/draw-utils-openlayer'
import Map from 'ol/Map'

const map = new Map({ target: 'map', layers: [...], view: new View({...}) })

const tool = new DrawTool({
  adapter: new OpenLayerAdapter(map),
  bizCallbacks: {
    onInsert: async (f) => { /* 保存 */ return true },
    onEdit:   async (f) => { /* 更新 */ return true },
    onDelete: async (f) => { /* 删除 */ return true },
  },
})

// 事件桥接
const c = map.getTargetElement()
c.addEventListener('pointermove', (e) => { const p = map.getEventPixel(e); const coord = map.getCoordinateFromPixel(p); tool.onMouseMove([coord[0], coord[1]]) })
c.addEventListener('click',       (e) => { const p = map.getEventPixel(e); const coord = map.getCoordinateFromPixel(p); tool.onClick([coord[0], coord[1]]) })
c.addEventListener('dblclick',    (e) => { e.stopPropagation(); const p = map.getEventPixel(e); const coord = map.getCoordinateFromPixel(p); tool.onDblClick([coord[0], coord[1]]) })

// 开始绘制
tool.startDraw({ type: 'rect', limit: 5, enableEdit: true, enableDel: true })
tool.stopDraw()

API 参考

DrawTool

new DrawTool({ adapter, bizCallbacks? })

startDraw(config)

| 字段 | 类型 | 默认 | 说明 | |------|------|------|------| | type | FeatureType | — | 必填 | | name | string | 随机8位 | 要素名 | | limit | number | 1 | 本轮上限（0=禁止） | | enableLimitMsg | boolean | false | 超出弹 toast | | enableEdit | boolean | false | 允许编辑 | | enableDel | boolean | false | 允许删除 | | showLenOnInsert | boolean | false | 绘制时显边长 | | showAreaOnInsert | boolean | false | 绘制时显面积 | | showLenForAll | boolean | false | 全量显边长 | | showAreaForAll | boolean | false | 全量显面积 | | debug | boolean | false | 控制台日志 | | oldFeatures | FeatureInfo[] | — | 预加载要素 |

公开方法

| 方法 | 说明 | |------|------| | onMouseMove([lon,lat]) | 鼠标移动。绘制中更新预览；IDLE 时悬浮高亮 | | onClick([lon,lat]) | 单击。绘制中追加顶点；IDLE 时弹 Logo | | onDblClick([lon,lat]) | 双击。IDLE 时启动绘制；绘制中结束 | | startDraw(config) | 开始一轮 | | stopDraw() | 停止并清除 | | destroy() | 销毁实例+图层 | | getFeature(id) | 按 ID 查 | | getAllFeatures() | 全部要素 | | getState() | 当前状态 |

图形类型

| type | 名称 | 绘制方式 | WKT | 备注 | |------|------|---------|-----|------| | rect | 矩形 | 双击①→预览→双击② | POLYGON | — | | triangle | 三角形 | 双击①→单击②→预览→双击③ | POLYGON | — | | circle | 圆形 | 双击圆心→预览→双击 | POLYGON(64边) | details.radius | | line | 线段 | 双击①→预览→双击② | LINESTRING | 无 fillRgba | | polyline | 折线 | 双击①→单击续点→双击结束 | LINESTRING | 无 fillRgba | | customShape | 自定义多边形 | 双击①→单击续点→双击闭合 | POLYGON | — |

DrawState

IDLE → DRAWING → IDLE
IDLE → EDITING → IDLE
IDLE → DELETING → IDLE

FeatureInfo

{ id: number; type: FeatureType; wkt: string; details: Info }

封闭图形 WKT: POLYGON((...))，线条 WKT: LINESTRING(...)。圆形以 64 边正多边形近似。

通用 Info 字段

| 字段 | 类型 | 默认 | 适用 | |------|------|------|------| | name | string | "" | 全部 | | lineWidth | number | 2 | 全部 | | lineType | "solid"\|"dashed" | "solid" | 全部 | | strokeLineDash | string | "15 15 15 15" | 全部 | | lineRgba | string | 见默认色 | 全部 | | fillRgba | string | 见默认色 | 封闭图形 | | textRgba | string | 见默认色 | 全部 | | radius | number | — | 仅 circle |

默认颜色

| 图形 | 线条 | 填充 | |------|------|------| | 矩形 | rgba(255,0,0,1) | rgba(255,0,0,0.5) | | 三角形 | rgba(0,0,255,1) | rgba(0,0,255,0.5) | | 圆形 | rgba(34,197,94,1) | rgba(34,197,94,0.5) | | 线段/折线 | rgba(234,179,8,1) | — | | 自定义 | rgba(139,92,246,1) | rgba(139,92,246,0.5) |

oldFeatures 示例

tool.startDraw({
  type: 'rect', enableEdit: true,
  oldFeatures: [{
    id: 1001, type: 'rect',
    wkt: 'POLYGON((109 19, 110 19, 110 20, 109 20, 109 19))',
    details: { name: '区域A', lineWidth: 2, lineType: 'solid', strokeLineDash: '15 15 15 15', lineRgba: 'rgba(255,0,0,1)', fillRgba: 'rgba(255,0,0,0.3)', textRgba: 'rgba(255,255,255,1)' },
  }],
})

交互说明

• 单击已完成要素 → 弹出编辑/删除 Logo（点击坐标位置，跟随 zoom）
• 编辑面板：名称、线宽、线型、颜色调色盘（12色预设）、虚线间距（4输入框），面板可拖拽折叠
• 删除确认框：红色垃圾桶 SVG 图标 + 确认/取消按钮
• 编辑拖拽：矩形/三角形约束不变形，折线/自定义中点拖拽插入新顶点，圆形圆周把手拖拽改半径
• 悬浮高亮：鼠标悬浮时线宽 ×1.5
• Toast：超出 limit 时自动弹出（中上方居中）

架构设计

Adapter 模式

外部业务层
    │
    ▼
DrawTool (core) ── 使用 ──▶ IGisAdapter / IFeatureRenderer
                                  ▲
                                  │ 实现
                          OpenLayerAdapter
                          OpenLayerFeatureRenderer

• packages/core — 纯 TypeScript，GIS 框架无关。定义 DrawTool 核心逻辑、FeatureInfo 类型、Adapter 接口
• packages/openlayer — OpenLayers 适配。实现 WebGLVectorLayer 高性能渲染、编辑手柄、测量标注

图层设计

每个 DrawTool 实例拥有独立的 WebGLVectorLayer（1 个实例 = 1 个图层）。多实例并行不冲突。

IFeatureRenderer 核心接口

| 方法 | 说明 | |------|------| | renderFeature(f,highlight?) | 渲染要素（自动识别 Polygon/LineString） | | startEditing(f) / cancelEditing() | 编辑状态管理 + 拖拽手柄 | | updateFeatureStyle(id,style) | 实时更新颜色/线宽 | | showHoverActions(...) / hideHoverActions() | 编辑/删除 Logo | | getFeatureAtCoordinate(coord) | 拾取要素 | | setAllFeatureLabels / refreshAllFeatureLabels | 全量测量标注 | | updateDashVariables(d1,d2,d3,d4) | 虚线间距 | | highlightHoverFeature(id) | 悬浮高亮 |