# Map 构造与属性

## 全局配置 · `Map` 构造函数

### new Map(domId, options)

* **类型**：`constructor`
* **归属**：自定义（内部创建 **OL** `Map` / `View`）
* **参数**：
  * `{string} domId` — 地图容器元素的 `id`（传给 `ol/Map` 的 `target`）
  * `{Object} options` — 见下方选项表。**融合**：会 `Object.assign` 进 `ol/View`，因此 OL View 合法字段（如 `maxZoom`）也可直接传入
* **返回值**：`Map` 业务实例
* **用法**：

```js
const map = new Map('map', {
  centerX: 116.4,
  centerY: 39.9,
  zoom: 12,
  wkid: 3857,
  maxZoom: 18,          // 同时作为 OL View 选项
  overview: true,
  callback: { layersReadyCallback() {} }
});
```

* **融合说明**：
  * `this.map = new ol/Map(...)`
  * `this.map.business = this`（事件反查）
  * `viewOptions = Object.assign({ center, constrainResolution, enableRotation, maxZoom }, options)`

#### options 选项

##### centerX / centerY

* **类型**：`number`
* **必填**：是（常规用法）
* **说明**：初始中心坐标，写入 View 的 `center: [centerX, centerY]`。在 `wkid: 3857` 下一般为 Web 墨卡托米制坐标。

##### zoom

* **类型**：`number`
* **归属**：融合（OL View）
* **说明**：初始缩放级别。

##### wkid

* **类型**：`number | string`
* **默认值**：业务侧通常传 `3857`
* **说明**：
  * `3857`：Web 墨卡托，不注册自定义投影
  * `4326` / `4490` / `4549`：内置 proj4 定义，注册为 `custom`
  * 其它：当作 proj4 定义串使用
* **用法**：

```js
new Map('map', { centerX: 120.1, centerY: 30.2, zoom: 10, wkid: 4326 });
```

##### origin

* **类型**：`number[]`
* **说明**：自定义投影下瓦片原点，挂到 `projection.origin`，供 ArcGIS 切片等使用。

##### maxZoom / minZoom / constrainResolution / enableRotation / …

* **类型**：见 [OL View](https://openlayers.org/en/latest/apidoc/module-ol_View-View.html)
* **归属**：OL（经 `Object.assign` 传入）
* **默认值**：本库默认 `constrainResolution: true`、`enableRotation: false`、`maxZoom: 18`

##### baseLayers

* **类型**：`{ [baseKey: string]: Array<BaseLayerOption> }`
* **说明**：底图分组。每个 `BaseLayerOption` 至少含 `type`（如 `OSMLayer`、`GaodeLayer`、`TDTLayer`）。
* **用法**：

```js
baseLayers: {
  osm: [{ type: 'OSMLayer', layerType: 'org' }],
  gaode: [{ type: 'GaodeLayer', layerType: 'raster' }]
},
initBaseLayer: 'osm'
```

##### initBaseLayer

* **类型**：`string`
* **说明**：初始可见的底图组 key，对应 `baseLayers` 的键名。

##### fixedLayers / fixedLayerCodes

* **类型**：`Array<Object>` / `Array<string>`
* **说明**：固定叠加层及其初始可见 code 列表。

##### overview

* **类型**：`boolean | string`
* **默认值**：不启用
* **说明**：为真时创建 **OL** `OverviewMap`；若为字符串，追加到 CSS class。实例挂在 `map.overview`，并带自定义 `overview.baseLayers`。

##### callback

* **类型**：`Object`
* **说明**：业务回调集合，见下一节。

##### codeField

* **类型**：`string`
* **默认值**：`'objCode'`
* **说明**：要素业务主键字段名，点查 / 高亮 / 编辑共用。

##### allFields

* **类型**：`boolean | string`
* **默认值**：`false`
* **说明**：
  * `true`：点查返回全部字段
  * `false`：仅查 `codeField`
  * `string`：作为 WFS `propertyName`

##### imageBase

* **类型**：`string`
* **说明**：图标等静态资源基路径。

##### postGIS

* **类型**：`boolean`
* **说明**：写服务 / GeoServer 相关行为开关。

##### refreshLayers

* **类型**：`boolean`
* **说明**：为真时，分辨率变化清空矢量瓦片 source（`initLayers` 内绑定）。

---

### callback 选项

业务回调挂在构造函数 `options.callback` 上。

#### layersReadyCallback

* **类型**：`Function`
* **参数**：无
* **说明**：`initLayers` 完成建层、创建测量/绘制工具后调用。
* **用法**：

```js
callback: {
  layersReadyCallback() {
    map.showLayers(['pipe', 'valve']);
  }
}
```

#### clickCallback

* **类型**：`Function`
* **参数**：
  * `{Array} features` — 命中的业务要素摘要（实现依赖内部 `_clickFun`）
* **说明**：地图点击查询到要素后回调（需 `clickMap === true`）。

#### extentChangeCallback

* **类型**：`Function`
* **说明**：若提供，则监听 View `change`，视野变化时触发。

---

## 实例属性

以下属性在 `new Map` 之后可用。

### map

* **类型**：`ol/Map`
* **归属**：OL
* **说明**：底层 OpenLayers 地图。完整 OL API 均可通过它调用。
* **用法**：

```js
const view = map.map.getView();
map.map.on('moveend', () => console.log(view.getZoom()));
```

* **注意**：直接 `map.map.addLayer(layer)` **不会**写入 `map.layers`，业务方法可能找不到该层。业务图层请用 `initLayers` / `addLayer`。

### layers

* **类型**：`Object`
* **归属**：自定义
* **说明**：图层字典。常见键：
  * `baseLayers`：`{ [type]: ol/layer/Layer[] }`
  * `highlight`：高亮层
  * `geoserver` / `arcgis`：聚合服务层
  * `[layerCode]`：业务图层实例
* **用法**：

```js
map.layers['valve'].setVisible(true); // OL 方法挂在自定义图层实例上
```

### businessLayers

* **类型**：`Object | undefined`
* **说明**：`initLayers` 之后按 `code` 存储的业务配置（含 `type`、`serviceAddress`、`parameter` 等）。

### projection

* **类型**：`proj4.Proj | undefined`
* **归属**：融合
* **说明**：`wkid !== 3857` 时存在；可能带自定义 `origin`。

### overview

* **类型**：`ol/control/OverviewMap | undefined`
* **归属**：融合
* **说明**：鹰眼控件；另有自定义 `overview.baseLayers`。

### initView

* **类型**：`{ center: number[], zoom: number }`
* **说明**：初始视图，供 `resetMap()` 使用。

### codeField

* **类型**：`string`
* **默认值**：`'objCode'`
* **说明**：要素业务主键字段名。点查、高亮、编辑等共用。构造时由 `options.codeField` 写入。

### allFields

* **类型**：`boolean | string`
* **默认值**：`false`
* **说明**：
  * `true`：点查返回全部字段
  * `false`：仅查 `codeField`
  * `string`：作为 WFS `propertyName`
* **来源**：构造选项 `options.allFields`

### imageBase

* **类型**：`string | undefined`
* **说明**：图标等静态资源基路径。构造时由 `options.imageBase` 写入；未传则为 `undefined`。

### postGIS

* **类型**：`boolean | undefined`
* **说明**：为 `true` 时启用与 GeoServer/PostGIS 写服务相关的行为。仅当构造传入 `options.postGIS` 时存在。

### refreshLayers

* **类型**：`boolean | undefined`
* **说明**：为 `true` 时，`initLayers` 后会在分辨率变化时清空矢量瓦片 source。仅当构造传入 `options.refreshLayers` 时存在。

### clickMap

* **类型**：`boolean`
* **默认值**：`true`
* **说明**：为 `false` 时抑制地图点查（绘制/分析过程中常被临时关闭）。

### callback

* **类型**：`Object`
* **说明**：构造传入的回调引用。

### measureTool / drawSearchTool

* **类型**：`Measure` / `DrawSearch`
* **说明**：`initLayers` 后创建。

### track / pipeInspectionTool

* **类型**：`Track` / `Inspection | undefined`
* **说明**：对应工厂方法创建后挂载。

---