Class: Map

Map

new Map(options)

document/mapCollection/Map.js, line 11

地图图层管理容器。

Map 与具体地图引擎解耦，负责统一组织底图、业务图层和覆盖物图层， 是 MapView、SceneView 等视图对象创建图层视图、转发图层事件和维护地图状态的核心数据容器。 业务代码通常通过该对象而不是直接通过底层引擎来管理图层。

Name Type Default Description
options Object {} 可选

构造参数。

Name Type Default Description
id String 可选

地图容器 ID。未传入时会自动生成唯一标识。
basemap Basemap | Object | null null 可选

地图底图对象或可转换为 Basemap 的 JSON 配置。存在底图时，地图会优先使用底图中的参考图层来确定空间参考系。
layers Array.<(Layer|Object)> 可选

初始业务图层数组。通过该参数传入的图层会加入 Map.layers 容器，并显示在底图之上、覆盖物图层之下。
overlayLayers Array.<(Layer|Object)> 可选

初始覆盖物图层数组。该容器中的图层始终位于业务图层上方，适合承载高亮、分析结果和临时标注等视图级内容。
spatialReference SpatialReference | Object | null null 可选

地图初始空间参考系。通常在图层加载后由底图或业务图层自动确定；显式传入时可作为初始参考系缓存。
fullExtent Extent | Object | null null 可选

地图初始全图范围。通常用于从持久化配置恢复地图状态。
Fires
Examples

创建空地图容器

// ES5引入方式
const { Map } = zondy

// ES6引入方式
import { Map } from '@mapgis/webclient-common'

const map = new Map()

创建带底图的地图容器

// ES5引入方式
const { Map, Basemap, Collection } = zondy
const { IGSTileLayer } = zondy.layer

// ES6引入方式
import { Map, Basemap, Collection, IGSTileLayer } from '@mapgis/webclient-common'

const map = new Map({
  basemap: new Basemap({
    baseLayers: new Collection([
      new IGSTileLayer({
        url: '服务地址'
      })
    ])
  })
})

Extends

Members

allLayersCollection.<Layer>

图层扁平后的容器。根据图层容器layers变化，会进行动态更新。如果是一个组图层，则会按照深度遍历的顺序排列

basemapCollection

基础地图

basemapBasemap null

当前地图关联的底图对象。

设置该属性时会同步更新底图组图层、触发底图变化逻辑，并刷新 allLayers 扁平图层集合。 传入 null 或 undefined 可清空当前底图。

fullExtentExtent

地图范围

fullExtentExtent null

当前地图的全图范围。

内部缓存以 4326 参考系保存，对外读取时会自动投影到 Map.spatialReference 对应的参考系。 该值通常在图层加载后通过 getFullExtent 计算得到。

layersCollection.<Layer>

图层容器。通过Map上add、addMany方法添加的图层会放到此容器中

overlayLayersGroupLayer

覆盖物组图层，如果想要将图层放置在地图内图层的最上层，可以通过此接口添加图层

spatialReferenceSpatialReference

地图参考系

spatialReferenceSpatialReference null

当前地图采用的空间参考系。

该值通常由底图参考图层或已加载图层确定，对外只读。 在调用 getFullExtent、坐标转换或构建视图时，可使用该属性判断地图当前参考系。

Events

basemap-change

document/mapCollection/Map.js, line 176

地图底图对象发生变化时触发。

当底图首次创建、替换或内部基础图层销毁时会触发该事件，detail 中记录了本次底图变更动作。

Properties:
Name Type Description
event BasemapChangeEvent

事件对象

Properties
Name Type Default Description
type String 'basemap-change' 可选

事件类型
basemap Basemap | null null 可选

当前关联的底图对象
detail Array.<Object> [] 可选

底图变化详情数组，例如 basemap-create、baseLayers-destroy。
Example

监听底图变化

map.on('basemap-change', (event) => {
  console.log('底图变化事件:', event.detail)
})

layer-add

document/mapCollection/Map.js, line 64

业务图层添加后触发的旧版兼容事件。

当调用 add 添加单个业务图层，且该图层被成功加入 Map.layers 后触发。 新逻辑中更推荐结合 map-layer-change 和 map-layer-loaded 事件判断图层变化与加载完成时机。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layer-add' 可选

事件类型
layer Layer null 可选

被添加的业务图层对象
Example

监听单个业务图层添加

map.on('layer-add', (event) => {
  console.log('添加图层事件:', event.layer)
})

layer-add-many

document/mapCollection/Map.js, line 80

批量添加业务图层后触发的旧版兼容事件。

当一次性添加多个业务图层时触发，常用于兼容旧项目中对 layer-add-many 的监听逻辑。 如需获取更完整的变更信息，推荐监听 map-layer-change。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layer-add-many' 可选

事件类型
layers Array.<Layer> [] 可选

本次被加入地图的业务图层数组
Example

监听多个业务图层添加

map.on('layer-add-many', (event) => {
  console.log('添加多个图层事件:', event.layers)
})

layer-remove

document/mapCollection/Map.js, line 96

单个业务图层移除后触发的旧版兼容事件。

当调用 remove 删除一个业务图层，且该图层已经从 Map.layers 中移除后触发。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layer-remove' 可选

事件类型
layer Layer null 可选

被移除的业务图层对象
Example

监听单个业务图层移除

map.on('layer-remove', (event) => {
  console.log('删除图层事件:', event.layer)
})

layer-remove-all

document/mapCollection/Map.js, line 126

业务图层全部移除后触发的旧版兼容事件。

当 Map.layers 容器被清空时触发，仅针对业务图层容器，不包含底图和覆盖物图层。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layer-remove-all' 可选

事件类型
layers Array.<Layer> [] 可选

被移除的图层数组
Example

监听业务图层全部移除

map.on('layer-remove-all', (event) => {
  console.log('移除所有图层事件:', event)
})

layer-remove-many

document/mapCollection/Map.js, line 111

多个业务图层移除后触发的旧版兼容事件。

当一次删除多个业务图层时触发，事件对象中的 layers 表示本次被移除的图层数组。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layer-remove-many' 可选

事件类型
layers Array.<Layer> [] 可选

被移除的业务图层数组
Example

监听多个业务图层移除

map.on('layer-remove-many', (event) => {
  console.log('移除多个图层事件:', event.layers)
})

map-layer-change

document/mapCollection/Map.js, line 141

地图图层结构发生变化时触发。

当底图组、业务图层组或覆盖物图层组发生添加、移除、排序等变化时都会触发该事件， 是监听地图图层集合变化的主事件。

Properties:
Name Type Description
event LayerChangeEvent

事件对象

Properties
Name Type Default Description
type String 'map-layer-change' 可选

事件类型
added Array.<Layer> [] 可选

本次新增的图层数组
removed Array.<Layer> [] 可选

本次移除的图层数组
moved Array.<Object> [] 可选

本次排序变更信息数组
sourceTarget GroupLayer 可选

触发本次变化的组图层对象
path Array.<GroupLayer> [] 可选

图层变化路径
Example

监听地图图层结构变化

map.on('map-layer-change', (event) => {
  console.log('图层变化详情:', event.added, event.removed, event.moved)
})

map-layer-loaded

document/mapCollection/Map.js, line 161

地图图层加载完成后触发。

当进入等待队列的图层完成 load 且可用于创建图层视图后触发，常用于在视图层安全执行图层操作。

Properties:
Name Type Description
event LayerLoadedEvent

事件对象

Properties
Name Type Default Description
type String 'map-layer-loaded' 可选

事件类型
addDetail Array.<Object> [] 可选

已完成加载的图层批次详情。每一项包含 added 图层数组和对应的 sourceTarget 组图层。
Example

监听地图图层加载完成

map.on('map-layer-loaded', (event) => {
  console.log('图层加载完成详情:', event.addDetail)
})

Methods

add(layer, index){void}

document/mapCollection/Map.js, line 322

向业务图层容器中添加一个图层。

图层加入 Map.layers 是同步完成的，但图层对应的视图创建通常要等到视图侧异步加载完成后才可用。 如需在图层真正可操作时继续处理，建议监听 map-layer-loaded 或图层自身的 layerview-created 事件。 如果一个layer被添加到多个map中，建议先调用layer的clone方法克隆出一个新的layer对象，再添加到其他map中，否则可能会出现一些意想不到的问题，例如事件触发异常等

Name Type Description
layer Object | Layer

要添加的图层对象或图层 JSON 配置。
index Number 可选

插入位置索引。不传时默认追加到业务图层容器末尾。
Fires
Returns:
Type Description
void
Example

添加一个业务图层

map.add(layer)

addMany(layers, index){void}

document/mapCollection/Map.js, line 346

批量向业务图层容器中添加多个图层。

连续添加多个图层时推荐优先使用该接口，可减少重复触发的中间处理过程， 通常比多次调用 add 更高效。 如果一个layer被添加到多个map中，建议先调用layer的clone方法克隆出一个新的layer对象，再添加到其他map中，否则可能会出现一些意想不到的问题，例如事件触发异常等

Name Type Description
layers Array.<(Object|Layer)>

要添加的图层数组。数组元素可为图层实例或图层 JSON 配置。
index Number 可选

插入起始位置索引。不传时默认从业务图层容器末尾开始追加。
Fires
Returns:
Type Description
void
Example

批量添加业务图层

map.addMany([layer1, layer2])

clone(){Map}

document/mapCollection/Map.js, line 310

克隆当前地图容器。

会基于当前实例的可序列化状态创建一个新的 Map 对象，适合在保留现有图层组织关系的前提下复制地图配置。

Returns:
Type Description
Map 新的地图容器实例。

destroy(){void}

document/mapCollection/Map.js, line 421

销毁当前地图容器。

调用后会移除全部业务图层并注销内部事件监听。销毁后的实例不应继续复用。

Returns:
Type Description
void
Example

销毁地图容器

map.destroy()

dispatchEvent(type, data, propagate){Map}

document/mapCollection/Map.js, line 468

向当前地图容器转发事件。

适用于框架内部或扩展能力向 Map 对象派发统一事件，通常业务代码无需直接调用。

Name Type Description
type String

事件类型。
data *

事件数据。
propagate Boolean 可选

是否允许事件继续传播。
Returns:
Type Description
Map 当前地图容器实例。

findLayerById(id){Layer|undefined}

document/mapCollection/Map.js, line 453

根据图层 ID 查询业务图层。

该方法基于 groupLayer 进行查找，可用于从地图容器中快速定位指定 ID 的业务图层或组图层。

Name Type Description
id String

图层 ID。
Returns:
Type Description
Layer | undefined 找到时返回对应图层对象，否则返回 undefined。
Example

根据图层 ID 查询业务图层

const layer = map.findLayerById('layer-id')

inherited fire(type, data, propagate){Object}

base/Evented.js, line 523

激发指定类型的事件

Name Type Description
type string 可选

事件类型
data Object 可选

待传递的数据
propagate Boolean 可选

是否传播到父级
Returns:
Type Description
Object 当前实例

getFullExtent(){Extent|null}

document/mapCollection/Map.js, line 484

计算并返回当前地图的全图范围。

该方法会综合底图、业务图层和覆盖物图层的范围计算结果， 同时更新内部缓存的 4326 参考系全图范围，对外返回值会与 Map.spatialReference 保持一致。

Returns:
Type Description
Extent | null 当前地图全图范围；无法计算时返回 null。

inherited off(types, fn, context){Object}

base/Evented.js, line 337

移除事件
示例如下:
[1、移除一个事件的指定回调函数]
[2、移除一个事件的所有回调函数]
[3、移除多个事件的同一个指定的回调函数]
[4、移除多个指定事件的回调函数]
[5、删除时指定上下文 - types类型为字符串]
[6、删除时指定上下文 - types类型为对象]

Name Type Description
types string 可选

移除指定事件类型上绑定的回调函数
当类型为字符串时，可以移除单个或多个事件类型绑定的回调函数，单个事件："click"，多个事件：以空格分割:"click double-click"；
当types为对象时，使用如下方式移除事件：{'click': onClickFun, 'mouse-move': onMouseMoveFun}
fn function 可选

事件回调函数，当types为字符串，且不指定要删除的回调函数时，删除该事件上的所有回调函数
context Object 可选

事件回调函数的this关键字将指向的对象
Returns:
Type Description
Object 当前实例
Examples

移除一个事件的指定回调函数

// 一个事件的回调函数
const clickFunction = function (event) {
  console.log("点击事件:", event)
}
// 调用MapView或SceneView的off方法移除一个事件的回调函数
view.off('click', clickFunction)

移除一个事件的所有回调函数

// 一个事件的回调函数1
const clickFunction1 = function (event) {
  console.log("点击事件1:", event)
}

// 一个事件的回调函数2
const clickFunction2 = function (event) {
  console.log("点击事件2:", event)
}

// 调用MapView或SceneView的off方法移除一个事件的所有回调函数
// 不指定回调函数，则移除该事件上的所有绑定的回调函数
view.off('click')

移除多个事件的同一个指定的回调函数

// 多个事件的同一个回调函数
const eventFunction = function (event) {
  console.log("事件:", event)
}
// 调用MapView或SceneView的off方法移除多个事件的同一个指定的回调函数
view.off('click double-click', eventFunction)

移除多个指定事件的回调函数

// 一个事件的回调函数
const clickFunction = function (event) {
  console.log("click事件:", event)
}
// 调用MapView或SceneView的off方法移除多个指定事件的回调函数
view.off({
   // 移除click事件上一个指定的函数
  "click": clickFunction,
  // 移除double-click上所有指定的函数
  "double-click": undefined
})

删除时指定上下文 - types类型为字符串

// 一个事件的回调函数
const clickFunction = function (event) {
  console.log("点击事件:", event)
}
// 调用MapView或SceneView的off方法移除一个事件的回调函数
view.off('click', clickFunction, view)
// 调用MapView或SceneView的off方法移除一个事件的所有回调函数
view.off('click', undefined, view)

删除时指定上下文 - types类型为对象

// 一个事件的回调函数
const clickFunction = function (event) {
  console.log("click事件:", event)
}
// 调用MapView或SceneView的off方法移除多个指定事件的回调函数
view.off({
   // 移除click事件上一个指定的函数
  "click": clickFunction,
  // 移除double-click上所有指定的函数
  "double-click": undefined
}, view)

inherited on(types, fn, context){Object}

base/Evented.js, line 240

注册一个新的监听事件;
示例如下：
[1、注册一个事件]
[2、一次注册多个事件 - 同一个回调函数]
[3、一次注册多个事件 - 分别指回调应函数]
[4、当types为字符串时 - 指定上下文]
[5、当types为对象时 - 指定上下文]

Name Type Default Description
types String | Object null 可选

事件类型
当types为字符串时，可以定义单个或多个事件，单个事件："click"，多个事件：以空格分割:"click double-click"；
当types为对象时，使用如下方式指定事件：{'click': onClickFun, 'mouse-move': onMouseMoveFun}
fn function null 可选

事件回调函数
context Object null 可选

事件回调函数的this关键字将指向的对象
Returns:
Type Description
Object 当前实例
Examples

注册一个事件

// 初始化一个点击事件回调函数
const clickFunction = function (event) {
  console.log("点击事件:", event)
}
// 调用MapView或SceneView的on方法注册一个点击事件
view.on('click', clickFunction)

一次注册多个事件 - 同一个回调函数

// 初始化一个事件回调函数
const eventFunction = function (event) {
  console.log("事件:", event)
}

// 调用MapView或SceneView的on方法注册多个事件
// 多个事件类型使用同一个回调函数
view.on('click right-click-down', eventFunction)

一次注册多个事件 - 分别指回调应函数

// 初始化一个左键点击事件回调函数
const clickFunction = function (event) {
  console.log("click事件:", event)
}

// 初始化一个右键按下事件回调函数
const rightClickFunction = function (event) {
  console.log("right-click-down事件:", event)
}

// 调用MapView或SceneView的on方法注册多个事件
// 每一个事件类型，使用单独的回调函数
// 注意使用此种方式，一种类型的事件仅能指定一个回调函数
view.on({
  "click": clickFunction,
  "right-click-down": rightClickFunction
})

指定上下文 - types类型为字符串

// 初始化一个点击事件回调函数
const clickFunction = function (event) {
  console.log("点击事件:", event)
  console.log("上下文对象:", this)
}
// 调用MapView或SceneView的on方法注册一个点击事件
// 指定view为回调函数的上下文对象
view.on('click', clickFunction, view)

指定上下文 - types类型为对象

// 初始化一个点击事件回调函数
const clickFunction = function (event) {
  console.log("点击事件:", event)
  console.log("上下文对象:", this)
}
// 调用MapView或SceneView的on方法注册一个点击事件
// 指定view为回调函数的上下文对象
view.on({
  "click": clickFunction,
  "right-click-down": clickFunction
}, view)

inherited once(types, fn, context){Object}

base/Evented.js, line 592

事件监听，仅触发一次

Name Type Description
types string 可选

将侦听器函数（fn）添加到对象的特定事件类型中。您还可以传递几个空格分隔的类型（例如“click dblclick”），也可以传入例如 {click: onClick, mousemove: onMouseMove}。
fn function 可选

侦听器函数
context Object 可选

指定侦听器的上下文（this关键字将指向的对象）
Returns:
Type Description
Object 当前实例

remove(layer){void}

document/mapCollection/Map.js, line 369

从业务图层容器中移除指定图层。

该方法只处理 Map.layers 中的业务图层；若要删除覆盖物图层，应直接操作 overlayLayers。

Name Type Description
layer Object | Layer

要移除的图层对象。
Fires
Returns:
Type Description
void
Example

移除指定业务图层

map.remove(layer)

removeAll(){void}

document/mapCollection/Map.js, line 405

移除全部业务图层。

仅清空 Map.layers 容器，不会影响底图和覆盖物图层容器。

Fires
Returns:
Type Description
void
Example

移除所有业务图层

map.removeAll()

removeMany(layers){void}

document/mapCollection/Map.js, line 387

批量移除多个业务图层。

适用于需要同时清理多个业务图层的场景。

Name Type Description
layers Array.<(Layer|Object)>

要移除的图层数组。
Fires
Returns:
Type Description
void
Example

批量移除业务图层

map.removeMany([layer1, layer2])

reorder(layer, index){void}

document/mapCollection/Map.js, line 436

调整业务图层在容器中的顺序。

排序结果会影响图层在视图中的叠加顺序；索引越大通常越靠上显示。

Name Type Description
layer Layer

要调整顺序的业务图层对象。
index Number

目标索引位置。
Fires
Returns:
Type Description
void
Example

调整业务图层顺序

map.reorder(layer, 2)

toJSON(){Object}

document/mapCollection/Map.js, line 285

导出当前地图容器为 JSON 配置对象。

结果中会包含底图、业务图层、空间参考系、全图范围等可序列化配置， 适合用于保存地图状态或后续通过 Map.fromJSON 恢复实例。

Returns:
Type Description
Object 地图配置对象。

Map.fromJSON(json){Map}

document/mapCollection/Map.js, line 270

通过 JSON 配置创建一个新的地图容器实例。

适用于从持久化配置恢复 Map 对象，通常与 toJSON 配套使用。

Name Type Default Description
json Object {} 可选

地图配置对象。
Returns:
Type Description
Map 新的地图容器实例。