# 概述与入门

## 标注约定

| 标注 | 含义 |
|------|------|
| **自定义** | 本库新增的类、方法、属性或选项 |
| **OL** | OpenLayers 原生 API（继承、透传或直接调用） |
| **融合** | 同一对象上同时存在自定义字段与 OL 行为（挂载、混入 options、继承后再扩展） |

---

## 全局说明 · 项目结构

`simple-map` 是一层业务 GIS 引擎：对外提供 `Map` / 工具类；对内用 OpenLayers 完成渲染与交互。

### 模块解耦关系

```
@its-cool/simple-map（包入口 src/simpleMap.js）
│
├── Map（src/core/Map.js）          ← 业务门面（自定义）
│   ├── this.map : ol/Map           ← 渲染内核（OL）
│   ├── this.layers{}               ← 按 code 索引的业务图层字典（自定义）
│   ├── this.businessLayers{}       ← 业务图层配置（自定义）
│   └── prototype mixins
│       ├── baseMethods             视图 / 底图 / 测量 / 点数据
│       ├── layerMethods            建层 / 显隐 / 高亮 / 云图层
│       ├── analysisMethods         绘制查询 / 管网分析 / 统计
│       ├── toolMethods             Track / Inspection / Profile 工厂
│       └── internalMethods         点查、WFS、ArcGIS（内部）
│
├── Tools（src/tools/*）            可独立 new，也可由 Map 方法创建
├── Layers（src/layers/*）          未从包入口导出，由 Map._getLayer 创建
├── Sources（src/sources/*）        底图瓦片源，配合 TileLayer
└── transformCoord / mapTools       无地图依赖或弱依赖工具
```

### 运行时对象关系（融合核心）

```
业务 Map 实例
  ├─ map ──────────────► ol/Map
  │                        └─ .business ──► 指回业务 Map（点击事件反查）
  ├─ layers.baseLayers     底图组 { osm: [TileLayer…], gaode: […] }
  ├─ layers.highlight      高亮 VectorLayer
  ├─ layers[code]          业务图层（多为 extends ol/layer/*）
  ├─ overview?             ol/control/OverviewMap + .baseLayers（自定义挂载）
  └─ measureTool / drawSearchTool / track …
```

### 设计原则

1. **业务入口走 `Map` 方法**：如 `displayLayer`、`drawPoint`，会同步维护 `layers` 字典与 WMS `LAYERS` 参数。
2. **渲染细节走 `map.map`（OL）**：如临时监听 `pointermove`、取 `getView().getResolution()`。
3. **图层类多采用「继承 OL + `Object.assign(this, options)`」**：同一实例上既有 `setVisible()`（OL），也有 `addGraphics()`（自定义）。

### 包入口导出

```js
import {
  Map,
  transformCoord,
  Draw, Measure, Tip, WriteServer, DrawSearch, Track, Inspection, Profile,
  mapTools
} from '@its-cool/simple-map';
import '@its-cool/simple-map/style.css';
```

| 导出 | 类型 | 说明 |
|------|------|------|
| `Map` | `class` | 业务地图 |
| `transformCoord` | `Function` | 坐标转换 |
| `Draw` / `Measure` / `DrawSearch` | `class` | 绘制系（extends `ol/layer/Vector`） |
| `WriteServer` / `Inspection` / `Profile` | `class` | 编辑 / 巡检 / 剖面（extends Vector） |
| `Track` / `Tip` | `class` | 轨迹 / 提示（组合 OL Layer，非业务门面必需） |
| `mapTools` | `Object` | 独立工具函数 |
| `default` | `Object` | 上述聚合 |

> `Layers` / `Sources` **未**从包入口导出。

---

## 安装与快速开始

### 安装

* **类型**：环境要求
* **用法**：

```bash
npm install @its-cool/simple-map
```

Node `>=14.18.0`。`ol` / `proj4` / `turf` 已打入产物，一般无需再装。

### 快速开始

示例页：[`/basic`](/basic)

```js
import { Map } from '@its-cool/simple-map';
import '@its-cool/simple-map/style.css';

const map = new Map('map', {
  centerX: 13528430,
  centerY: 3676466,
  zoom: 11,
  wkid: 3857,
  initBaseLayer: 'osm',
  baseLayers: {
    osm: [{ type: 'OSMLayer', layerType: 'org' }]
  },
  callback: {
    layersReadyCallback() {
      console.log('图层初始化完成');
    },
    clickCallback(features) {
      console.log(features);
    }
  }
});

map.initLayers({});
```

```html
<div id="map" style="width:100%;height:500px;"></div>
```

---

## Playground 示例对照

| 主题 | 路由 |
|------|------|
| 基础地图 | [`/basic`](/basic) |
| 底图切换 | [`/baselayer`](/baselayer) |
| 视图控制 | [`/controls`](/controls) |
| 测量 | [`/measure`](/measure) |
| 绘制 | [`/draw`](/draw) |
| 坐标转换 | [`/transform`](/transform) |
| GeoTIFF 栅格 | [`/geotiff`](/geotiff) |
| 流向分析 | [`/flow-direction`](/flow-direction) |
| 管线压力测试 | [`/pipe`](/pipe) |
| Pinia 点击 | [`/pinia`](/pinia) |
| 高级工具 | [`/advanced`](/advanced) |
| 本文档 | [`/docs`](/docs) |

---

## 版本与许可

* 包名：`@its-cool/simple-map`
* OpenLayers：`^10`（构建打入产物）
* 许可：MIT