# Map 视图与控制

## Map 方法 · 视图与生命周期

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

### changeGisConfig(options)

* **类型**：`Function`
* **归属**：自定义
* **参数**：
  * `{Object} options`
    * `{number} [options.centerX]` — 新中心 X
    * `{number} [options.centerY]` — 新中心 Y
    * `{number} [options.zoom]` — 新级别
    * `{Array<string>} [options.fixedLayerIds]` — 要显示的固定层 code；未列出的固定层隐藏
* **返回值**：无
* **相关 OL**：`View.setCenter` / `setZoom`；`layer.setVisible`
* **用法**：

```js
map.changeGisConfig({
  centerX: 13528430,
  centerY: 3676466,
  zoom: 14,
  fixedLayerIds: ['boundary']
});
```

### destroy()

* **类型**：`Function`
* **归属**：自定义
* **参数**：无
* **返回值**：无
* **相关 OL**：`map.dispose()`
* **用法**：

```js
// Vue beforeUnmount
map.destroy();
map = null;
```

### zoomIn()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：当前级别 +1（动画）。
* **用法**：

```js
map.zoomIn();
```

### zoomOut()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：当前级别 -1（动画）。
* **用法**：

```js
map.zoomOut();
```

### resetMap()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：动画回到 `initView`。
* **用法**：

```js
map.resetMap();
```

### setExtent(extent)

* **类型**：`Function`
* **参数**：
  * `{number[]} extent` — `[minX, minY, maxX, maxY]`，地图投影坐标
* **返回值**：无
* **相关 OL**：`View.fit(extent, { duration: 1000 })`
* **用法**：

```js
map.setExtent([13520000, 3670000, 13530000, 3680000]);
```

### getCenterAndZoom()

* **类型**：`Function`
* **参数**：无
* **返回值**：`{ x: number, y: number, zoom: number }`
* **用法**：

```js
const { x, y, zoom } = map.getCenterAndZoom();
console.log(x, y, zoom);
```

### offset(zoom, param)

* **类型**：`Function`
* **参数**：
  * `{number|null} zoom` — 目标级别；可不改级别
  * `{Object} param` — 传给内部 `_locateTo`，常用 `{ offset: [dx, dy] }`（像素或逻辑偏移，由实现解释）
* **返回值**：无
* **用法**：

```js
map.offset(null, { offset: [0, -80] }); // 视野上移，露出底部面板
```

### locateTo(x, y, zoom, param?)

* **类型**：`Function`
* **归属**：自定义
* **参数**：
  * `{number} x` — 目标点 X（地图投影）
  * `{number} y` — 目标点 Y
  * `{number} [zoom]` — 目标级别
  * `{Object} [param]`
    * `{boolean} [param.symbol]` — 是否打定位符号（默认相关逻辑见 `_locateTo`）
    * `{Array} [param.offset]` — 中心偏移
* **返回值**：无
* **说明**：先清空高亮层，再定位。
* **用法**：

```js
map.locateTo(13528430, 3676466, 16, { symbol: true });
```

### locateToPolygon(data)

* **类型**：`Function`
* **参数**：
  * `{Array<number[]>} data` — 折线/环坐标序列 `[[x,y], …]`；若存在自定义 `projection` 会先转到 3857
* **返回值**：无
* **相关 OL**：`View.fit(new LineString(data))`
* **用法**：

```js
map.locateToPolygon([
  [13528000, 3676000],
  [13529000, 3676000],
  [13529000, 3677000]
]);
```

### locateByLngLat(lng, lat)

* **类型**：`Function`
* **参数**：
  * `{number} lng` — WGS84 经度
  * `{number} lat` — WGS84 纬度
* **返回值**：无
* **说明**：转为墨卡托，在高亮层打 `type:'mark'` 点并居中。
* **用法**：

```js
map.locateByLngLat(120.15, 30.28);
```

### locateToCurrentPosition(lng, lat, zoom?, from?, to?)

* **类型**：`Function`
* **参数**：
  * `{number} lng`
  * `{number} lat`
  * `{number} [zoom]`
  * `{string} [from]` — 源坐标系名，见 `Transform`（如 `'wgs84'`、`'gcj02'`）
  * `{string} [to]` — 目标坐标系名（如 `'webmercator'`、`'map'`）
* **返回值**：无
* **说明**：调用 `changeCurrentPosition` 后 `setCenter` / 可选 `setZoom`。
* **用法**：

```js
map.locateToCurrentPosition(120.15, 30.28, 15, 'wgs84', 'webmercator');
```

### changeCurrentPosition(lng, lat, from?, to?)

* **类型**：`Function`
* **参数**：同 `locateToCurrentPosition` 的坐标与坐标系参数
* **返回值**：`number[]` — 转换后的地图坐标 `[x, y]`
* **说明**：更新高亮层中 `type:'current'` 的定位点，**不**强制改 zoom。
* **用法**：

```js
const coord = map.changeCurrentPosition(120.15, 30.28, 'gcj02', 'map');
```

---

## Map 方法 · 底图与鹰眼

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

### changeBaseLayer(type)

* **类型**：`Function`
* **参数**：
  * `{string} type` — `baseLayers` 的键，如 `'osm'`、`'gaode'`
* **返回值**：无
* **说明**：仅该组底图 `setVisible(true)`，其它组隐藏；若有鹰眼则同步。
* **用法**：

```js
map.changeBaseLayer('gaode');
```

### displayOverview()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **相关 OL**：`overview.setCollapsed(!overview.getCollapsed())`
* **用法**：

```js
map.displayOverview();
```

---

## Map 方法 · 测量与坐标

示例页：[`/measure`](/measure)、[`/transform`](/transform)

### measure(type)

* **类型**：`Function`
* **参数**：
  * `{string} type` — `'length'`（或其它非 `area`）测距；`'area'` 测面
* **返回值**：无
* **说明**：先 `cancelMeasure`，再调用 `measureTool.measure`。需已 `initLayers`。
* **用法**：

```js
map.measure('length');
map.measure('area');
```

### cancelMeasure()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：取消当前测量交互。

```js
map.cancelMeasure();
```

### clearMeasure()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：清空测量图形与结果。

```js
map.clearMeasure();
```

### transformCoordinate(data, from, to, projectionCode?)

* **类型**：`Function`
* **参数**：
  * `{number[]} data` — `[x, y]` 或 `[lng, lat]`
  * `{string} from` — 源坐标系：`'wgs84'` | `'gcj02'` | `'webmercator'` | `'map'` 等
  * `{string} to` — 目标坐标系
  * `{string|proj4.Proj} [projectionCode]` — `to === 'map'` 或自定义投影时使用
* **返回值**：`number[]` — 转换后坐标
* **用法**：

```js
const merc = map.transformCoordinate([120.15, 30.28], 'wgs84', 'webmercator');
const wgs = map.transformCoordinate(merc, 'webmercator', 'wgs84');
```

### getNavigationCoord(x, y)

* **类型**：`Function`
* **参数**：
  * `{number} x` — Web 墨卡托 X
  * `{number} y` — Web 墨卡托 Y
* **返回值**：`number[]` — WGS84 `[lng, lat]`
* **用法**：

```js
const [lng, lat] = map.getNavigationCoord(13528430, 3676466);
```

---

## Map 方法 · 服务编辑入口

### writeServer(options?)

* **类型**：`Function`
* **归属**：自定义（返回 **融合** 类 `WriteServer`）
* **参数**：
  * `{Object} [options]`
    * `{string} [options.addType]` — `'geoserver'` | `'arcgis'`
    * `{string[]} [options.layerCodes]` — 参与编辑的业务图层 code
    * `{string} [options.serviceAddress]` — 服务地址 / workspace
    * `{string[]} [options.queryLayerCodes]` — ArcGIS 查询子层 code（会映射为 layerId）
    * `{string} [options.codeField]` — 覆盖实例默认主键
    * 其它字段原样传给 `WriteServer` 构造
* **返回值**：`WriteServer`
* **说明**：自动注入 `postGIS`、当前 `geoserver` 图层、`vectorTileLayers`、`codeField` 等。
* **用法**：

```js
const editor = map.writeServer({
  addType: 'geoserver',
  layerCodes: ['pipe', 'valve']
});
editor.insertFeature('Point', { objCode: 'V001', name: '阀门1' });
```

---

## Map 方法 · 点与告警数据

### drawPoint(data, clear?)

* **类型**：`Function`
* **参数**：
  * `{Object<string, Array<Object>>} data` — key 为 `layerCode`，value 为点属性数组。点对象常用字段：
    * `{string|number} objCode` — 主键
    * `{number} gpsX` / `{number} gpsY` 或几何相关字段（由 CloudLayer 解析）
    * `{number} [alarm]` — 告警等级
    * 其它业务属性、飘窗 HTML 等
  * `{boolean} [clear]` — 为 `true` 时先 `clear` 该层再添加
* **返回值**：无
* **说明**：图层必须已在 `businessLayers` / `layers` 注册；关联图层（热力/聚合等）会 `setData`。
* **用法**：

```js
map.drawPoint({
  hydrant: [
    { objCode: 'H1', gpsX: 13528430, gpsY: 3676466, alarm: 0, name: '栓1' },
    { objCode: 'H2', gpsX: 13528500, gpsY: 3676500, alarm: 1 }
  ]
}, true);
```

### clearPoint()

* **类型**：`Function`
* **参数**：无
* **返回值**：无
* **说明**：清空所有 `type === '1'`（云点层）的图形。

```js
map.clearPoint();
```

### removePoint(data)

* **类型**：`Function`
* **参数**：
  * `{Object<string, Array>} data` — 每层要移除的图形标识列表（交给 `removeGraphics`）
* **返回值**：无
* **用法**：

```js
map.removePoint({ hydrant: ['H1', 'H2'] });
```

### drawInspectionPoint(layerCode, data)

* **类型**：`Function`
* **参数**：
  * `{string} layerCode`
  * `{Object<string, Array<Object>>} data` — key 为要素 id；`data[id][0]` 含 `gpsX`/`gpsY` 等
* **返回值**：无
* **相关 OL**：`Feature` / `Point` / `source.addFeature` / `setGeometry`
* **用法**：

```js
map.drawInspectionPoint('patrol', {
  P1: [{ gpsX: 13528430, gpsY: 3676466 }]
});
```

### refreshAlarm(data)

* **类型**：`Function`
* **参数**：
  * `{Object<string, Array|Object>} data` — `{ [layerCode]: alarmPayload }`
* **返回值**：无
* **用法**：

```js
map.refreshAlarm({ hydrant: ['H1', 'H2'] });
```

### refreshPoint(data)

* **类型**：`Function`
* **参数**：
  * `{Object<string, *>} data` — 交给各层 `refreshData`
* **返回值**：无

```js
map.refreshPoint({ hydrant: updatedList });
```

### refreshGridPoint(data, polygon)

* **类型**：`Function`
* **参数**：
  * `{Object} data` — 网格点数据
  * `{Object|Array} polygon` — 网格范围
* **返回值**：无
* **说明**：若配置了 `relateLayerCodes`，会一并传入关联层。

---