my-openlayer

v3.1.4

Published

11 days ago

my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地图组件库，专为 Web GIS 应用开发者设计。提供完整的 TypeScript 支持、模块化的类型定义、强大的错误处理和事件管理系统，支持天地图底图加载、要素绘制、图层管理、事件监听等丰富功能，极大提升地图开发效率。

0High
0Medium
0Low

cuteyuchen

openlayers ol gis map vue

my-openlayer

my-openlayer 是一个基于 OpenLayers 的现代地图组件库，专为 Web GIS 应用开发者设计。提供完整的 TypeScript 支持、模块化的类型定义、强大的错误处理和事件管理系统，支持天地图底图加载、要素绘制、图层管理、事件监听等丰富功能，极大提升地图开发效率。

在线 Demo · 文档 · 迁移指南 (2.x → 3.0)

3.0 亮点

3.0 是一次 API 形态层的范式转移，核心目标是统一 lifecycle、降低学习成本：

统一 LayerHandle — 真实图层类 add* 返回 { layer, remove(), setVisible() } 形态的句柄，跨 Point / Line / Polygon 复用同一套 lifecycle 模型
统一 ControlHandle — addDomPoint / addVueTemplatePoint 返回 { target, remove(), setVisible() }，并保留 anchors / getPoints() 等原有能力
点 API GeoJSON 直接输入 — addPoint / addClusterPoint / addPulsePointLayer 直接接受 PointData[]、GeoJSON FeatureCollection、Feature、MultiPoint geometry，内部统一标准化，创建后的 Feature 可直接通过 feature.get('name') / feature.getProperties() 读取业务字段
addGeoJSON 综合渲染 — MyOl.addGeoJSON(data, options) 自动识别点/线/面几何类型，按分组创建图层，返回统一 GeoJSONRenderHandle，支持 groupBy 分组、styleByProperties 逐要素样式、数组/Record 多数据集输入
*ByUrl 异步化 — addPointByUrl / addLineByUrl / addPolygonByUrl 统一先获取 JSON，再返回完整 Handle
destroy 级联清理 — MyOl.destroy() 现在依次调用 SelectHandler.destroy / Line.destroyAll / Point.destroyAll / Polygon.destroyAll，确保静态线、流动线 rAF / Overlay / Vue 实例 / Select interaction 全部释放
ProjectionManager — 投影逻辑从 MyOl 内部抽取为独立类，支持 ProjectionManager.register({ code, def }) 在 MyOl 实例之外注册任意 EPSG
ConfigManager.setDefaults — 运行时修改全局默认配置，所有未提供该字段的后续调用都生效
统一错误类型 — 全部 throw 使用 MyOpenLayersError 并携带 ErrorType（VALIDATION_ERROR / MAP_ERROR / LAYER_ERROR / COORDINATE_ERROR / DATA_ERROR / COMPONENT_ERROR），另有 LayerNotFoundError / InvalidGeoJSONError / ProjectionError 子类，方便 instanceof 判别
layerName 必填 — 公开 add* 方法签名上 layerName 变成必填（编译时强制）
PulsePointIconOptions src → img — 统一命名，旧 src 标 @deprecated

从 2.x 升级请参考 MIGRATION-3.0.md。3.0 会把旧 add* 的原始 layer 返回值改为 Handle；访问 OL 图层请使用 handle.layer。

项目概述

项目名称：my-openlayer
用途：基于 OpenLayers 的 TypeScript 地图组件库，提供点/线/面要素、底图切换、热力图、事件与配置管理等能力。
目标用户：Web GIS 开发者、可视化工程师、前端开发者

功能亮点

🗺️ 底图管理 (MapBaseLayers)
- 支持天地图矢量、影像、地形底图切换
- 动态切换底图与注记图层管理
- 地图裁剪与自定义范围显示
- 支持 GeoServer WMS 图层
📍 要素操作
- 点位管理 (Point)：点位标注（自定义图标、聚合、DOM 闪烁、高性能矢量闪烁）
- 线要素绘制 (Line)：支持静态线、流光线、流动线图标动画，详见 Line 动画文档
- 面要素 (Polygon)：面要素绘制、分区高亮、遮罩层
- Vue组件支持 (VueTemplatePoint)：支持将 Vue 组件作为地图点位渲染
🛠️ 地图工具
- 测量工具 (MeasureHandler)：距离和面积测量
- 要素选择 (SelectHandler)：支持点击、悬停、多选等交互选择
- 地图工具 (MapTools)：图层管理、定位、视图自适应、全图裁剪 (clipMap)
- 事件管理 (EventManager)：统一的地图事件监听与管理
⚡ 高级特性
- TypeScript 完全支持：提供完整的类型定义，严格模式
- 错误处理 (ErrorHandler)：统一的错误捕获与日志，含具体子类型
- 配置管理 (ConfigManager)：集中管理默认配置，支持运行时 setDefaults
- 投影管理 (ProjectionManager)：内置 EPSG:4326 / EPSG:4490 / EPSG:4549，支持 ProjectionManager.register() 注册任意自定义投影

安装

npm install my-openlayer
# 或
yarn add my-openlayer
# 或
pnpm add my-openlayer

依赖要求

Node.js: >= 18
OpenLayers: ^10.6.1
proj4: ^2.7.5
@turf/turf: ^7.2.0

CC Switch 技能仓库

本仓库已按 CC Switch 技能仓库结构提供 my-openlayer-helper：

skills/my-openlayer-helper/SKILL.md

在 CC Switch 的“添加技能仓库”中填写：

仓库 URL：cuteyuchen/my-openlayer
分支：main

CC Switch 扫描后会识别到 my-openlayer-helper。后续更新只需要同步本仓库，使用者在 CC Switch 中刷新/更新技能即可。

快速上手

1. 初始化地图

import { MyOl } from 'my-openlayer';

const map = new MyOl('map-container', {
  center: [119.81, 29.969],
  zoom: 10,
  token: import.meta.env.VITE_TIANDITU_TOKEN, // 天地图 Token
  annotation: true
});

2. 使用功能模块

// 获取模块实例（懒加载）
const point = map.getPoint();
const line = map.getLine();
const polygon = map.getPolygon();

// 添加点位（3.0 add* 返回统一 LayerHandle）
const handle = point.addPoint(
  [{ lgtd: 119.81, lttd: 29.969, name: '示例点' }],
  { layerName: 'example-point', img: 'marker.png' }
);
handle?.remove(); // 统一的生命周期管理

// 也支持直接传 GeoJSON FeatureCollection
const geoHandle = point.addPoint(
  { type: 'FeatureCollection', features: [
    { type: 'Feature', properties: { name: '杭州' }, geometry: { type: 'Point', coordinates: [120.15, 30.27] } }
  ]},
  { layerName: 'geojson-points', textKey: 'name' }
);

const feature = geoHandle?.layer.getSource()?.getFeatures()[0];
feature?.get('name'); // '杭州'
// feature.get('rawData') 仅保留兼容旧代码，新代码优先读取顶层业务字段。

3. 添加高性能闪烁点

当需要展示大量预警点位时，优先使用 addPulsePointLayer。它与 addPoint 保持一致的 img、scale、textKey 等参数习惯，通过单个 requestAnimationFrame 驱动整个 VectorLayer，避免为每个点创建 DOM 动画。

const pulseLayer = point.addPulsePointLayer(
  [
    { lgtd: 119.81, lttd: 29.969, lev: 0, stnm: '风险村' },
    { lgtd: 119.86, lttd: 29.992, lev: 3, stnm: '普通村' }
  ],
  {
    layerName: 'village-pulse',
    levelKey: 'lev',
    textKey: 'stnm',
    img: '/icons/village.svg',
    scale: 0.8,
    textVisible: true,
    pulse: {
      duration: 2400,
      radius: [8, 28],
      colorMap: {
        0: 'rgba(255, 48, 54, 0.48)',
        1: 'rgba(255, 136, 0, 0.45)',
        2: 'rgba(253, 216, 46, 0.4)',
        3: 'rgba(6, 183, 253, 0.32)'
      }
    }
  }
);

pulseLayer?.stop();
pulseLayer?.start();
pulseLayer?.remove();

4. 添加流动线

const flow = map.getLine().addFlowLine(lineData, {
  layerName: 'river-flow',
  animationMode: 'icon+dash',
  strokeColor: '#19b1ff',
  strokeWidth: 3,
  flowSymbol: {
    src: '/symbols/boat.svg',
    scale: 0.9,
    count: 2,
    spacing: 0.2
  }
});

flow?.pause();
flow?.resume();
flow?.remove();

5. 全图裁剪

const tools = map.getTools();

// 裁剪整张地图（底图 + 注记 + 用户图层全部只在区域内可见）
tools.clipMap(geoJsonBoundary);

// 或只裁剪当前底图
const baseLayers = map.getMapBaseLayers().getCurrentBaseLayers();
baseLayers.forEach(layer => MapTools.setMapClip(layer, geoJsonBoundary));

6. 注册自定义投影

import { ProjectionManager } from 'my-openlayer';

// 在 MyOl 实例之外注册任意 EPSG
ProjectionManager.register({
  code: 'EPSG:4528',
  def: '+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=40500000 +y_0=0 +ellps=GRS80 +units=m +no_defs'
});

// 之后 MyOl 构造时直接用
const map = new MyOl('map', { projection: { code: 'EPSG:4528' } });

7. 运行时修改默认配置

import { ConfigManager } from 'my-openlayer';

// 所有后续 addLine 调用的默认 strokeWidth 变为 4
ConfigManager.setDefaults('LINE_OPTIONS', { strokeWidth: 4 });

// 恢复内置默认
ConfigManager.resetDefaults('LINE_OPTIONS');

8. addGeoJSON 综合渲染

自动识别点/线/面几何类型，按分组创建图层，返回统一句柄：

// 混合 FeatureCollection — 自动拆分为点、线、面图层
const handle = map.addGeoJSON(geojsonData, {
  layerName: 'risk',
  groupBy: 'level',                                    // 按 properties.level 分组
  point: { textKey: 'name', textVisible: true },
  line:  { strokeColor: '#3b82f6', strokeWidth: 3 },
  polygon: { fillColor: 'rgba(239,68,68,0.15)' }
});

// 句柄操作
handle.setVisible(false);              // 隐藏全部
handle.setGroupVisible('high', false); // 只隐藏 high 组
handle.removeGroup('low');             // 只移除 low 组
handle.remove();                       // 移除全部

// styleByProperties — 按 feature 属性返回不同样式
map.addGeoJSON(points, {
  layerName: 'styled',
  point: {
    styleByProperties: (props) => ({
      circleColor: props.risk === 'high' ? '#ef4444' : '#22c55e',
      circleRadius: props.risk === 'high' ? 10 : 6
    })
  }
});

文档索引

详细文档请访问 在线文档，交互式 Demo 请访问 Demo 站点。

核心类库

MyOl: 地图入口类，负责初始化和模块访问。
ProjectionManager: 投影管理（3.0 新增），支持 register() 注册任意 EPSG。
MapBaseLayers: 底图与注记管理。
ConfigManager: 配置管理，支持运行时 setDefaults。
EventManager: 事件管理。
ErrorHandler: 错误处理，含 LayerNotFoundError / InvalidGeoJSONError / ProjectionError。

要素操作

Point: 点要素（含聚合、DOM 点位、高性能闪烁点、统一 Handle）。
Line: 线要素（含静态线、流动线、URL 异步加载）。
Polygon: 面要素（含热力图、图片层、遮罩层、统一 Handle）。
VueTemplatePoint: Vue 组件点位。

交互与工具

SelectHandler: 要素选择交互（支持独立样式渲染、多选隔离）。
MeasureHandler: 测量工具。
MapTools: 通用地图工具（含 clipMap 全图裁剪）。
ValidationUtils: 验证工具。

详细用法示例

底图切换

const baseLayers = map.getMapBaseLayers();
baseLayers.switchBaseLayer('img_c'); // 切换到影像底图

测量工具

import { MeasureHandler } from 'my-openlayer';

// 需要传入原生的 OpenLayers map 实例
const measure = new MeasureHandler(map.map);

measure.start('LineString'); // 开始测距
measure.end(); // 结束测量

要素选择

const selectHandler = map.getSelectHandler();

selectHandler.enableSelect('click', {
  layerFilter: ['cities'],
  onSelect: (event) => console.log('选中:', event.selected)
});

// 编程式选择
selectHandler.selectByProperty('name', '杭州', { fitView: true });

注意：更多示例请访问 Demo 站点，每个公开类都有独立的交互式演示页。

贡献指南

欢迎提交 Issue 或 Pull Request！

Fork 本仓库
新建分支：git checkout -b feature/your-feature
提交更改：git commit -m 'feat: 新功能描述'
推送分支：git push origin feature/your-feature
提交 Pull Request

许可证

MIT

联系方式: [email protected] | GitHub Issues

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

my-openlayer

3.0 亮点

项目概述

功能亮点

安装

依赖要求

CC Switch 技能仓库

快速上手

1. 初始化地图

2. 使用功能模块

3. 添加高性能闪烁点

4. 添加流动线

5. 全图裁剪

6. 注册自定义投影

7. 运行时修改默认配置

8. addGeoJSON 综合渲染

文档索引

核心类库

要素操作

交互与工具

详细用法示例

底图切换

测量工具

要素选择

贡献指南

许可证