# zss-ol-map

**Repository Path**: zengshengsun-code/zss-ol-map

## Basic Information

- **Project Name**: zss-ol-map
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-13
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zss-ol-map

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

## ✨ 核心特性

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

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

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

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

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

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

## 🚀 快速开始

### 安装

```bash
npm install zss-ol-map
```

### 基本使用

```javascript
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. 企业级数据集成

```javascript
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. 精细化图层管理

```javascript
// 获取图层管理器
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. 高性能数据渲染

```javascript
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