zss-ol-map

一个基于 OpenLayers 构建的企业级地图组件库，专注于提供强大的数据集成、图层管理、空间分析和高性能渲染能力，为 B 端业务系统提供全面的地图解决方案。

✨ 核心特性

📊 企业级数据集成与管理

• 多源数据接入：支持 GeoJSON、Shapefile、CSV、数据库数据、API 接口数据等格式
• 智能数据标准化：自动转换非空间数据，内置地址解析（Geocoding）能力
• 批量数据处理：支持万级以上数据的异步批量导入/更新，提供加载进度反馈
• 业务数据绑定：将业务数据与空间要素关联，支持数据实时更新与监听

🎛️ 精细化图层管理与权限控制

• 图层分组管理：按业务场景组织图层，支持分组显隐、排序与优先级控制
• 临时图层处理：快速创建和清理临时图层，优化内存使用
• 基于角色的权限控制：图层级可见性和编辑权限管理，支持多角色场景
• 统一的图层生命周期管理：通过 LayerManager 集中管理所有图层

⚡ 高性能与大规模数据支撑

• 数据分片与按需加载：基于视野范围和缩放级别智能加载数据
• 矢量瓦片支持：预生成的矢量瓦片降低前端计算压力，支持超大数据量
• WebGL 加速渲染：使用 WebGL 渲染海量点数据和热力图，提升帧率
• 样式缓存机制：智能缓存重复样式，减少对象创建，提升性能

📐 空间分析能力

• 基础空间计算：距离/面积测量、缓冲区分析、空间关系判断
• 业务场景化分析：多源路径规划、密度分析、选址分析

🎨 交互式编辑与标注工具

• 矢量要素编辑：点/线/面绘制、顶点编辑、批量编辑
• 高级标注功能：自定义符号、动态文本标注、交互式弹窗

🔄 系统集成与扩展能力

• 标准化 API：统一的接口风格和事件机制，便于框架集成
• 多框架适配：支持 Vue/React 等主流前端框架
• 数据导出与联动：支持多种格式导出和第三方工具联动

🚀 快速开始

安装

npm install zss-ol-map

基本使用

import { Map, VectorLayer, StyleUtil } from 'zss-ol-map';
import 'ol/ol.css';

// 初始化地图
const map = new Map({
  target: 'map-container',
  center: [116.397428, 39.90923],
  zoom: 12
});

// 添加矢量图层
const vectorLayer = new VectorLayer({
  id: 'my-layer',
  name: '业务图层',
  group: '运营数据',
  style: StyleUtil.createCircleStyle({
    radius: 6,
    fillColor: '#4ECDC4',
    strokeColor: '#fff',
    strokeWidth: 2
  })
});

map.addLayer(vectorLayer);

📖 核心功能示例

1. 企业级数据集成

import { DataAdapter, VectorLayer } from 'zss-ol-map';

// 创建数据图层
const dataLayer = new VectorLayer({
  id: 'business-data',
  name: '业务数据',
  group: '企业数据'
});

// 使用数据适配器加载数据
await dataLayer.loadDataWithAdapter(
  businessData,  // 企业业务数据
  {
    type: 'CSV',
    latField: 'latitude',
    lonField: 'longitude',
    idField: 'id'
  },
  {
    chunkSize: 1000,
    retryTimes: 3
  },
  (progress) => {
    console.log(`加载进度: ${progress.loaded}/${progress.total}`);
  }
);

// 绑定业务数据
layer.bindData('salesInfo', salesData);

// 监听数据变化
layer.watchData(({ key, value }) => {
  console.log('业务数据已更新:', key, value);
});

2. 精细化图层管理

// 获取图层管理器
const layerManager = map.getLayerManager();

// 创建分组图层
const logisticsLayer = new VectorLayer({
  id: 'logistics',
  name: '物流网点',
  group: '物流图层'
});

// 批量控制图层组显示
map.setGroupVisibility('物流图层', true);

// 设置角色权限
map.setLayerPermissionsByRole('operator', {
  'logistics': { visible: true, editable: true },
  'customers': { visible: true, editable: false }
});

// 清理临时图层
map.clearTempLayers();

3. 高性能数据渲染

import { VectorTileLayer, StyleCache } from 'zss-ol-map';

// 初始化样式缓存
const styleCache = StyleCache.getInstance();
styleCache.setMaxCacheSize(2000);

// 创建矢量瓦图层
const tileLayer = new VectorTileLayer({
  id: 'vector-tiles',
  name: '矢量瓦片',
  url: 'https://example.com/tiles/{z}/{x}/{y}.mvt',
  useWebGL: true,
  webGLConfig: {
    colorMap: true,
    colorField: 'value'
  },
  layerStyles: {
    'points': (feature, resolution) => {
      // 使用样式缓存获取样式
      return styleCache.getStyle({
        image: {
          type: 'circle',
          radius: 5,
          fill: { color: '#FF6B6B' }
        }
      });
    }
  }
});

// 添加可视范围控制的高性能图层
const performanceLayer = new VectorLayer({
  id: 'performance',
  name: '高性能图层',
  visibilityRange: { minZoom: 10, maxZoom: 18 },
  useWebGL: true
});

📚 API 文档

核心类

Map

• constructor(options) - 创建地图实例
• addLayer(layer, options?) - 添加图层，options 支持 { temp: true } 标记临时图层
• removeLayer(layer) - 移除图层
• getLayerManager() - 获取图层管理器
• setGroupVisibility(groupName, visible) - 设置图层组可见性
• clearTempLayers() - 清理所有临时图层
• setLayerPermissionsByRole(role, permissions) - 设置角色对应的图层权限

BaseLayer

• setMap(map) - 设置地图实例
• setVisible(visible) - 设置图层可见性
• setZIndex(zIndex) - 设置图层叠放顺序
• setGroup(group) - 设置图层分组
• getGroup() - 获取图层分组
• setPermissions(permissions) - 设置图层权限
• checkPermission(operation) - 检查操作权限

VectorLayer

继承自 BaseLayer，增加数据操作能力：

• addFeatures(features) - 添加要素
• updateFeature(id, properties) - 更新要素属性
• removeFeatures(ids) - 移除要素
• loadDataWithAdapter(data, adapterOptions, loadOptions, progressCallback) - 使用数据适配器加载数据
• bindData(key, data) - 绑定业务数据
• watchData(handler) - 监听数据变化
• unwatchData(handler) - 取消数据监听
• batchImport(data, options, callback) - 批量导入数据

VectorTileLayer

继承自 BaseLayer，支持矢量瓦片：

• updateLayerStyle(layerName, style) - 更新指定图层的样式
• updateLayerStyles(styles) - 批量更新图层样式
• clearTileCache() - 清除瓦片缓存

LayerManager

• registerLayer(layer) - 注册图层
• unregisterLayer(layerId) - 注销图层
• getLayer(layerId) - 获取图层
• getGroup(groupName) - 获取图层组
• getLayers() - 获取所有图层
• setLayerPermissionsByRole(role, permissions) - 设置角色权限

DataAdapter

• constructor(options) - 创建数据适配器
• convert(data) - 转换数据格式
• batchConvert(data, options) - 批量转换数据

StyleCache

单例模式：

• getInstance() - 获取实例
• getStyle(styleConfig) - 获取缓存的样式
• setStyle(key, style) - 设置样式缓存
• clearCache() - 清空缓存
• setMaxCacheSize(size) - 设置最大缓存大小
• getCacheSize() - 获取当前缓存大小

工具类

StyleUtil

• createCircleStyle(options) - 创建圆形样式
• createTextStyle(options) - 创建文本样式
• createIconStyle(options) - 创建图标样式
• createStrokeStyle(options) - 创建线条样式
• createFillStyle(options) - 创建填充样式

🗺️ 行业场景适配

物流/供应链

• 多站点路径优化
• 电子围栏管理
• 车辆轨迹回放与监控

零售/连锁

• 门店选址分析
• 周边竞品分布
• 客群热力图

城市管理

• 网格划分
• 事件点上报
• 多部门图层协同

能源/基建

• 管线路径管理
• 设备点位维护
• 缓冲区预警分析

📁 项目结构

├── src/
│   ├── layers/           # 图层相关类
│   ├── map/              # 地图核心类
│   ├── utils/            # 工具函数
│   ├── types/            # TypeScript 类型定义
│   └── index.ts          # 入口文件
├── example/              # 示例代码
├── test/                 # 测试文件
├── package.json
└── README.md

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License