# 地图💯
Map 对象代表页面上的地图。它暴露了一系列的方法和属性使得用户可以通过编程开发对地图进行修改，并在用户与地图交互时触发一系列的事件。
您可以创建Map，通过指定的container和其他可选参数。aimap.gl JS 会在页面上初始化地图并返回您的Map对象。
new Map(options: Object)
# 初始化参数
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| container | HTMLElement | AiMap GL JS 进行地图渲染的 HTML 元素，或该元素的字符串 id 。该指定元素不能有子元素。 | |
| projection | string | 'mercator' | 地图的投影方式，默认为mercator投影，可以指定为globe来实现球形效果。 |
| minZoom | number | 0 | 地图最小缩放级别（0-22） |
| maxZoom | number | 22 | 地图最大缩放级别（0-22） |
| minPitch | number | 0 | 地图最小倾角 |
| maxPitch | number | 85 | 地图最大倾角 |
| style | Object | string | 地图的 AiMap 配置样式。它必须是一个符合 AiMap 样式规范的 JSON 对象，或者是一个指向该 JSON 的 URL 地址。 要从AiMap API加载样式，您可以填写如下格式的 URL aimap://styles/:owner/:style， 其中 :owner 是您的 AiMap 账户名 :style 是样式 ID 。也可以使用以下预定义 AiMap 样式: aimap://styles/aimap/darkblue-v4 | |
| layerHeight | number | 0 | 地图中所有底图图层的高度，通过负值的高度与普通的底图搭配，可以实现指定区域拔高的效果。范围-5000 ~ 5000，单位米。 |
| hash | boolean | false | 如果为 true ，地图的位置 (包括缩放层级、中心纬度、中心经度、方位角和倾角) 将会与页面URL的哈希片段同步。例如， http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60 。 |
| interactive | boolean | true | 如果为 false ，地图将不会绑定对鼠标、触碰、键盘的监听，因此地图将不会响应任何用户交互。 |
| bearingSnap | number | 7 | 定义何时地图的方位将自动对齐到正北方向的阈值（以度为单位）。例如，当 bearingSnap 为 7 时，如果用户将地图转动到正北方向 7 度以内的范围时，地图将自动恢复对齐到正北方向。 |
| pitchWithRotate | boolean | true | 如果为 false ，将不会在"拖拽进行地图旋转"的同时控制地图的倾斜。 |
| clickTolerance | number | 3 | 当用户点击地图时能进行鼠标移动的最大像素范围，点击地图后鼠标在此像素范围内移动则被认为是一次有效的点击(而不是拖拽)。 |
| attributionControl | boolean | true | 如果为 true ， AttributionControl 将会被添加到地图上。 |
| customAttribution | string | Array<string> | 在 AttributionControl 中显示的字符串或字符串数组。仅当 options.attributionControl 为 true 时生效。 |
| logoControl | boolean | true | 如果为 true ， LogoControl 将会被添加到地图上。 |
| logoPosition | string | 'bottom-left' | 设置 'WAYZ' logo在地图上的位置。可选填以下值 top-left ， top-right ， bottom-left ， bottom-right 。 |
| failIfMajorPerformanceCaveat | boolean | false | 如果为 true ， 当 aimap.gl 的性能远远低于预期的时候，地图将创建失败。 (换句话说，此时可能是用的软件渲染器)。 |
| preserveDrawingBuffer | boolean | false | 如果为 true ，地图画布可通过 map.getCanvas().toDataURL() 输出 PNG 。出于性能优化考虑，该值默认为 false 。 |
| antialias | boolean | false | 如果为 true ，gl 渲染环境在创建时将开启多重采样抗锯齿模式（ MSAA ）, 这对自定义图层的抗锯齿十分有效。出于性能优化考虑，该值默认为 false 。 |
| refreshExpiredTiles | boolean | true | 如果为 false ，一旦切片的 HTTP cacheControl / expires headers 过期，地图将不会重新请求这些切片。 |
| maxBounds | LngLatBoundsLike | 如果设置，则地图将限制在给定范围内。 | |
| scrollZoom | Object | true | 如果为 true ，将开启 "滚轮缩放地图" 交互模式。如果传值为 Object 对象，对象可选参数参考 ScrollZoomHandler 。 |
| boxZoom | boolean | true | 如果为 true , 将开启 "框选缩放地图" 交互模式 (查阅 BoxZoomHandler )。 |
| dragRotate | boolean | true | 如果为 true , 将开启 "拖拽旋转地图" 交互模式 (查阅 DragRotateHandler )。 |
| dragPan | boolean | true | 如果为 true , 将开启 "拖拽移动地图" 交互模式 (查阅 DragPanHandler )。 |
| keyboard | boolean | true | 如果为 true ，将启用键盘快捷键功能 (查阅 KeyboardHandler )。 |
| doubleClickZoom | boolean | true | 如果为 true ，将开启 "双击缩放地图" 交互模式 (查阅 DoubleClickZoomHandler )。 |
| touchZoomRotate | Object | true | 如果为 true ，将开启 "捏合旋转、缩放" 交互模式。如果传值为 Object 对象，对象可选参数参考 TouchZoomRotateHandler 。 |
| trackResize | boolean | true | 如果为 true ，地图将自适应窗口大小变化。 |
| center | LngLat | [0,0] | 地图初始化时的地理中心点。如果构造函数的参数中没有设置 center ，AiMap GL JS 会在地图样式中进行查找。如果样式中也没定义的话，那么它将默认为 [0, 0] 注意: 为了与 GeoJSON 保持一致，AiMap GL 采用经度，纬度的顺序。 |
| zoom | number | 0 | 地图初始化时的层级。如果构造函数的参数中没有设置 zoom AiMap GL JS 会在地图样式中进行查找。如果样式中也没定义的话，那么它将默认为 0 。 |
| bearing | number | 0 | 地图初始化时的方位角（旋转角度），以正北方的逆时针转动度数计量。如果构造函数的参数中没有设置 bearing ，AiMap GL JS 会在地图样式中进行查找。如果样式中也没定义的话，那么它将默认为 0 。 |
| pitch | number | 0 | 地图初始化时的倾角，按偏离屏幕水平面的度数计量（0-60）。如果构造函数的参数中没有设置 pitch ，AiMap GL JS 会在地图样式中进行查找。如果样式中也没定义的话，那么它将默认为 0 。 |
| bounds | LngLatBoundsLike | 地图初始化时的限制范围。如果设置了 bounds 将会覆盖掉 center 和 zoom 在构造函数中的参数设置。 | |
| fitBoundsOptions | Object | fitBounds 仅用于 初始化地图时自适应设置的 bounds 范围时的情况。 | |
| renderWorldCopies | boolean | true | 如果为 true ，地图缩小时将渲染多个全局地图的副本。 |
| maxTileCacheSize | number | null | 设置当前数据源存储在切片缓存中的最大切片数目。如果不设置，将基于当前视角动态计算切片缓存大小。 |
| localIdeographFontFamily | string | sans-serif | 定义一个用于在本地替代通用‘中日韩越统一表意文字’，’平假名’，‘片假名’和‘朝鲜文音节’字形的 CSS 字体系列。 在上述字体在地图样式中的设置，除字体粗细（light/regular/medium/bold）外，都将被忽略。 当设置为 false ，上述字体则使用地图样式中的设置。 该参数的目的是为了避免超带宽的字形请求。 |
| transformRequest | RequestTransformFunction | 地图发送外部 URL 请求前执行的回调函数。回调函数中可修改 URL 、设置请求头或设置跨源请求的相关身份凭证。回调返回的对象参数包含 url 属性和可选的 headers 以及 credentials 属性。 | |
| collectResourceTiming | boolean | false | 如果为 true ，那么将为 GeoJSON 和 Vector Tile web workers 发出的请求搜集资源耗时API信息（通常无法从 Javascript 主线程中访问此信息）。该信息将在 resourceTiming 属性中返回（对应于 data 事件）。 |
| fadeDuration | number | 300 | 控制标注冲突时，淡入淡出的动画过渡时间, 单位为毫秒。该设置将应用于所有 symbol 图层。对于运行时的样式变化和栅格切片的淡入淡出，此设置不生效。 |
| crossSourceCollisions | boolean | true | 如果为 true ，来自不同数据源的符号将共同参与到碰撞检测中。如果为 false ，仅在各自的数据源中相互独立的进行符号的碰撞检测。 |
| accessToken | string | null | 设置之后，地图将用此 token 替换掉在 aimap.accessToken 中设置的值。 |
| layers | Array<Layer> | 预定义图层，详细使用说明请参考图致服务。 |
# 示例
const map = new aimap.Map({
container: 'map',
center: [121.612846, 31.205494],
zoom: 13,
minZoom: 3,
maxZoom: 20,
pitch: 0,
bearing: 0,
style: 'aimap://styles/aimap/darkblue-v4',
localIdeographFontFamily: "'Microsoft YaHei'",
});
2
3
4
5
6
7
8
9
10
11
# 实例方法
# 图像管理
可用于向地图中添加图片，移除图片。这些图片资源可以用于二维可视化图层中icon-image。
addImage(id, image, options)
给样式添加图像。图像可用于 icon-image， background-pattern， fill-pattern，和 line-pattern。 如果sprite中没有足够的空间用于添加此图像会触发一个 Map#error 事件。
参数
id(string): 图像的 id。
image((HTMLImageElement | ImageData | URL | Base64 string)): 格式为 HTMLImageElement ，ImageData 的图像，一个图像的在线链接，或者是 Base64 编码的图像。
options(any):
| Name | Description |
|---|---|
options.type string? | 可选png，gif，svg，frames，不写则默认为浏览器支持的静态图片格式，比如png，jpg等。 |
options.frameWidth number? | 当 type 为 frames 时，需要通过本字段指定每一帧的宽度，如不指定，则默认为每一帧的宽度等于图像的高度，即每一帧的图像为正方形。 |
options.pixelRatio number? default 1 | 图像像素与屏幕真实像素的比例。 |
options.sdf boolean default false | 图像是否应该被解析为SDF图像，SDF图像可以被 icon-color 着色。 |
options.content [number, number, number, number]? | 表示[x1, y1, x2, y2]。如果在样式中配置了 icon-text-fit，那么 text-field 将只会覆盖图像的[x1, y1, x2, y2]部分。 |
options.stretchX Array<[number, number]>? | 表示[[x1, x2], ...]。如果在样式中配置了 icon-text-fit，那么图像在指定的水平区间内会进行拉伸。 |
options.stretchY Array<[number, number]>? | 表示[[y1, y2], ...]。如果在样式中配置了 icon-text-fit，那么图像在指定的垂直区间内会进行拉伸。 |
返回值
Map: this
updateImageOptions(id, options)
更新图像的
参数
id(string): 图像的 id。
options(any):
| Name | Description |
|---|---|
options.speed number? default 1 | 对类别为 gif，frames 的图像，可以指定其播放的速度，大于1表示加快播放，小于1表示减缓。 |
返回值
Map: this
示例
map.updateImageOptions('spin', {speed: 2});
hasImage(id)
判断 id 对应的图像是否存在。
参数
id(string): 图像的 id。
返回值
boolean
removeImage(id)
根据 id 删除对应的图像（例如 icon-image 或 background-pattern使用的图像）。
参数
id(string): 图像的 id。
# 视角控制
可以控制地图的中心点，缩放级别，倾角，旋转角度等参数。或者控制地图视角进行跳转。
getCenter()
返回地图的地理中心点。
返回值
LngLat: 地图的地理中心点。
setCenter(center, eventData)
设置地图的地理中心点。等同于 jumpTo({center: center})。
参数
center(LngLatLike): 需要设置的中心点。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
map.setCenter([121, 31]);
panBy(offset, options, eventData)
按指定偏移值平移地图。
参数
offset(PointLike): x 和 y 坐标。用于平移地图
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
panTo(lnglat, options, eventData)
用动画将地图平移到指定的位置。
参数
lnglat(LngLatLike): 地图需要移动到的位置。
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
getZoom()
返回地图当前的缩放级别。
返回值
number: 地图的当前缩放级别。
setZoom(zoom, eventData)
设置地图的缩放级别。等同于 jumpTo({zoom: zoom})。
参数
zoom(number): 要设置的缩放级别 （0-20）。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
// 将地图缩放到级别 5
map.setZoom(5);
2
zoomTo(zoom, options, eventData)
以动态转换的方式将地图缩放到指定级别。
参数
zoom(number): 需要转换到的目标缩放级别。
options(AnimationOptions?): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
zoomIn(options, eventData)
将地图的缩放级别增加 1 级。
参数
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object)该方法触发的事件对象的其它属性。
返回值
Map: this
zoomOut(options, eventData)
将地图的缩放级别降低 1 级。
参数
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object)该方法触发的事件对象的其它属性。
返回值
Map: this
getBearing()
返回地图当前的方位角。方位角是指南针方向的指向，例如地图方位角为 90° 对应正东指向。
返回值
number: 地图当前的方位角。
setBearing(bearing, eventData)
设置地图的方位角（旋转度）。方位角是指南针方向的指向，例如地图方位角为 90° 对应正东指向。
等同于 jumpTo({bearing: bearing})。
参数
bearing(number): 需要设置的方位角。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
// 将地图旋转 90 度
map.setBearing(90);
2
getPadding()
返回地图当前的内边距。
返回值
PaddingOptions: PaddingOptions地图当前的内边距。
示例
const padding = map.getPadding();
setPadding(padding, eventData)
设置地图的内边距，以像素为单位。
等同于 jumpTo({padding: padding})。
参数
padding(PaddingOptions): PaddingOptions地图的内边距。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
map.setPadding({left: 300, top: 50});
rotateTo(bearing, options, eventData)
以动态转换的方式将地图旋转到指定方位角。方位角是指南针方向的指向，例如地图方位角为 90° 对应正东指向。
参数
bearing(number): 需要将地图旋转到的方位角。
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
resetNorth(options, eventData)
以动态转换的方式将地图旋转到 0 度方位角（正北方）。
参数
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
resetNorthPitch(options, eventData)
以动态转换的方式将地图旋转到 0 度方位角（正北方）和 0 度倾斜角。
参数
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
snapToNorth(options, eventData)
前方位角足够接近 0 度时（也就是说位于 bearingSnap 域内时），将其自动调整到 0 度（正北方）。
参数
options(AnimationOptions): AnimationOptions 地图移动方法的选项。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
getPitch()
返回地图当前的倾斜度。
返回值
number: 地图当前的倾斜度，按照偏离屏幕水平面的度数计算。
setPitch(pitch, eventData)
设置地图的倾斜度。等同于 jumpTo({pitch: pitch})。
参数
pitch(number): 需要设置的倾斜度，按照偏离屏幕水平面的度数计算（0-60）。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
cameraForBounds(bounds, options)
通过一个边界参数，计算这个边界所对应的相机参数。
参数
bounds(LatLngBoundsLike): 将这些边界设在视口中心，使用最大的缩放级别和 Map.getMaxZoom() 使其适应该视口。 LatLngBounds表示一个总是对齐坐标轴且方位角为 0 的范围。
options(CameraOptions):
| Name | Description |
|---|---|
options.padding (number | PaddingOptions)? | 以给定边界添加的以像素为单位的填充量。 |
options.offset PointLike default [0,0] | 给定边界中心到地图中心的偏移距离，以像素为单位。 |
options.maxZoom number? | 地图视图转换到指定边界时允许的最大缩放级别。 |
返回值
(CameraOptions | void): 如果地图可以适应到给定的边界，返回 CameraOptions 以及 center ， zoom ，和 bearing 。否则方法会出现警告个返回 undefined。
示例
var bbox = [[118, 31], [121, 34]];
var newCameraTransform = map.cameraForBounds(bbox, {
padding: {top: 10, bottom:25, left: 15, right: 5}
});
2
3
4
fitBounds(bounds, fitBoundsOptions?, eventData?)
在指定的地理边界内平移和缩放地图，以包含其可见区域。 当地图方位角不为 0 的时候，该函数会将方位角重置为 0。
参数
bounds(LngLatBoundsLike): 将这些边界设在视口中心，使用最大的缩放级别和 Map#getMaxZoom() 使其适应该视口。
fitBoundsOptions(Object?): 选项支持所有来自 AnimationOptions 和 CameraOptions 的属性，除了下面提及的字段。
| Name | Description |
|---|---|
options.padding (number | PaddingOptions)? | 以给定边界添加的以像素为单位的填充量。 |
options.linear boolean default false | 如果 true ， 地图将使用 Map#easeTo 。 如果 false ， 地图将使用 Map#flyTo 进行转换。查看这些函数及 AnimationOptions 了解可用的选项信息。 |
options.easing Function? | 动态转换的缓冲函数。点击查看 AnimationOptions 。 |
options.offset PointLike default [0,0] | 给定边界中心到地图中心的偏移距离，以像素为单位。 |
options.maxZoom number? | 地图视图转换到指定边界时允许的最大缩放级别。 |
eventData(Object?): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
var bbox = [[118, 31], [121, 34]];
map.fitBounds(bbox, {
padding: {top: 10, bottom:25, left: 15, right: 5}
});
2
3
4
fitScreenCoordinates(p0, p1, bearing, options, eventData)
一旦地图旋转到指定方位角，就平移、旋转与缩放地图到由点 p0 与 p1 确定的限位框。 在不旋转下缩放，只需传入当前地图的方位角。
参数
p0(PointLike): 屏幕上第一个点，用像素坐标。
p1(PointLike): 屏幕上第二个点，用像素坐标。
bearing(number): 转换完成后期望的地图方位角，单位为度。
options(any):
| Name | Description |
|---|---|
options.padding (number | PaddingOptions)? | 以给定边界添加的以像素为单位的填充量。 |
options.linear boolean default false | 如果 true ，地图将使用 Map#easeTo 。如果 false ，地图将使用 Map#flyTo 进行转换。查看这些函数及 AnimationOptions 了解可用的选项信息。 |
options.easing Function? | 动态转换的缓冲函数。点击查看 AnimationOptions 。 |
options.offset PointLike default [0,0] | 给定边界中心到地图中心的偏移距离，以像素为单位。 |
options.maxZoom number? | 地图视图转换到指定边界时允许的最大缩放级别。 |
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
var p0 = [220, 400];
var p1 = [500, 900];
map.fitScreenCoordinates(p0, p1, map.getBearing(), {
padding: {top: 10, bottom:25, left: 15, right: 5}
});
2
3
4
5
jumpTo(options, eventData)
不用动态转换的情况下改变中心点、 缩放级别、方位角和倾斜度的任意组合。地图将保留 options 没有指定的当前值。
参数
options(CameraOptions):
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
easeTo(options, eventData)
使用动态转换，将中心点、缩放级别、方位角和倾斜度组合的原有数值改为新数值。地图将保留 options 没有指定的当前值。
注意：转换将会瞬间触发如果用户的操作系统启用了 reduced motion 可访问特性。
参数
options(any): 描述转换目标和动态效果的选项。接受 CameraOptions 和 AnimationOptions 。
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
flyTo(options, eventData)
对地图中心、缩放级别、方位角和倾斜度做任意组合改变， 使其沿着一条曲线动态地变化并引发飞行效果。该动态转换能够无缝引入缩放和平移，使用户即使在穿越了很长的距离后也能保持方位角不变。
注意：此动画或被跳过，且行为等同于 jumpTo 如果用户操作系统启用了 reduced motion 可访问特性。
参数
options(Object): 描述转换目标和动态效果的选项。接受 CameraOptions ， AnimationOptions ， 以及以下选项。
| Name | Description |
|---|---|
options.curve number default 1.42 | 随着飞行路径出现的缩放“曲线”。要获得类似 Map#easeTo 的效果，大幅度移动时会出现较高的缩放值，较小移动时有较低的缩放值。 van Wijk (2003) (opens new window) 进行的用户调查中 显示用户选择的平均值为 1.42。 Math.pow(6, 0.25) 的值与均方根平均速率相同。值为 1 时会出现圆周运动。 |
options.minZoom number? | 位于飞行路径顶点的以 0 为起点的缩放级别。如果指定了 options.curve 可忽略这一选项。 |
options.speed number default 1.2 | 与 options.curve 相关的动态转换的平均速率。速率为 1.2 指，地图每秒以 1.2 倍于 options.curve 可见整屏（screenful）的速度随着飞行路径移动。 screenful 指地图的可见屏幕跨度区域。它不对应固定的物理距离，而是随缩放级别变化。 |
options.screenSpeed number? | 线性时间曲线情况下，动态转换的平均速率，按照每秒的移动的 screenful 数量计算。 如果指定了 options.speed 则忽略该选项。 |
options.maxDuration number? | 动效的最长持续时间，单位为微秒。如果持续时间超过此最大值，会重置为0。 |
eventData(Object): 该方法触发的事件对象的其它属性。
返回值
Map: this
示例
// fly with default options to null island
map.flyTo({center: [0, 0], zoom: 9});
// using flyTo options
map.flyTo({
center: [0, 0],
zoom: 9,
speed: 0.2,
curve: 1,
easing(t) {
return t;
}
});
2
3
4
5
6
7
8
9
10
11
12
# 视角变化状态
可用于判断地图视角是否正在发生变化，或者强制停止视角变化效果。
isMoving()
如果地图由于摄像机动画或用户手势而平移、缩放、旋转或俯仰，则返回true。
返回值
boolean
isZooming()
如果地图因摄像机动画或用户手势而缩放，则返回true。
返回值
boolean
isRotating()
如果地图由于摄像机动画或用户手势而旋转，则返回true。
返回值
boolean
stop()
停止所有进行中的动态转换。
返回值
Map: this
# 视角约束
用于获取或者指定地图视角的相关参数，比如缩放层级的最大值最小值，倾角的最大值最小值等。
resize(eventData)
根据其 container 元素的尺寸调整地图的大小。
此方法必须在地图的container被另一个脚本重新调整大小后调用，或者在CSS初始时隐藏后再显示地图。
参数
eventData(Object): 附加属性被添加到被该方法触发的事件对象。
返回值
Map: this
getBounds()
返回地图的地理边界。当 bearing 或 pitch 非零， 可视区域不是轴对齐的矩形，结果是包含可视区域的最小边界。
返回值
LngLatBounds
getMaxBounds()
返回地图限制的最大地理边界，如果没有设置，则返回null 。
返回值
(LngLatBounds | null)
setMaxBounds(bounds)
设置或清除地图的地理边界。
平移和缩放都必须在这些范围内进行。如果平移或缩放的位置超出了范围，系统将按操作者的请求，选择范围内最接近的一个点或缩放级别显示。
参数
bounds((LngLatBoundsLike | null | undefined)): 设置最大边界。如果提供值为 null 或 undefined ，函数将移除地图的最大边界。
返回值
Map: this
setMinZoom(minZoom)
设置或清除地图的最小缩放等级。如果地图现在的缩放等级低于新的最小值，地图将缩放到新的最小值。
参数
minZoom((number | null | undefined)): 设置最小缩放等级（0-24）。如果提供值为 null 或 undefined ，函数将移除当前的最小缩放值（即设置为0）。
返回值
Map: this
getMinZoom()
返回地图允许的最小缩放级别。
返回值
number: 最小缩放级别。
setMaxZoom(maxZoom)
设置或清除地图的最大缩放等级。如果地图现在的缩放等级高于新的最大值，则地图将缩放到新的最大值。
参数
maxZoom((number | null | undefined)): 设置最大缩放等级。如果提供值为 null 或 undefined ，函数将移除当前的最大缩放值（设置为22）。
返回值
Map: this
getMaxZoom()
返回地图允许的最大缩放级别。
返回值
number: 最大缩放级别。
setMinPitch(minPitch)
设置或清除地图的最小倾斜角度。如果地图现在的倾斜角度低于新的最小值，地图将倾斜到新的最小值。
参数
minPitch((number | null | undefined)): 设置最小倾斜角度（0-85）。如果提供值为 null 或 undefined ，函数将移除当前的最小倾斜角度（即设置为0）。
返回值
Map: this
getMinPitch()
返回地图允许的最小倾斜角度。
返回值
number: 最小倾斜角度。
setMaxPitch(maxPitch)
设置或清除地图的最大倾斜角度。如果地图现在的倾斜角度高于新的最大值，地图将倾斜到新的最大值。
参数
minPitch((number | null | undefined)): 设置最大倾斜角度（0-85）。如果提供值为 null 或 undefined ，函数将移除当前的最大倾斜角度（即设置为85）。
返回值
Map: this
getMaxPitch()
返回地图允许的最大倾斜角度。
返回值
number: 最大倾斜角度。
getRenderWorldCopies()
返回 renderWorldCopies 的状态。
返回值
boolean: renderWorldCopies
setRenderWorldCopies(renderWorldCopies)
设置 renderWorldCopies 的状态。
参数
renderWorldCopies(boolean): 如果为 true ，地图缩小时将渲染多个全局地图的副本。 undefined 被视为 true ， null 被视为 false。
返回值
Map: this
# 样式操作
用于控制地图的样式，可以切换地图的风格。
setStyle(style, options?)
指定一个新的地图样式。如果样式已经设置并且 options.diff 是 true，则会将样式与地图的当前状态进行比较，并仅执行使地图样式与所需状态匹配所需的更改。
参数
style((StyleSpecification | string | null)): JSON 对象遵从在 aimap样式说明 描述的模式或者指向一个这样JSON的URL。
options(Object?):
| Name | Description |
|---|---|
options.diff boolean default true | 如果为false，则强制执行“完整”更新，删除当前样式并构建给定的样式，而不是尝试基于差异的更新。 |
options.localIdeographFontFamily string default 'sans-serif' | 定义一个CSS字体系列，用于在'CJK Unified Ideographs', 'Hiragana', 'Katakana' 和 'Hangul Syllables' 范围内本地覆盖字形的生成。在这些范围内，除了字体权重关键字(light/regular/medium/bold)之外，地图样式的字体设置将被忽略。设置为 false false，为这些字形范围启用地图样式中的字体设置。强制执行完整的更新。 |
返回值
Map: this
getStyle()
返回地图的Mapbox样式对象，它能被用于重建地图样式。
返回值
Object: 地图的样式对象。
isStyleLoaded()
返回一个布尔值来指示地图样式是否完全加载。
返回值
boolean: 一个布尔值指示样式是否完全加载。
clear(layers?)
移除创建地图后添加过的所有图层，可以通过参数来保留指定的图层。
参数
layers(Array<string>): 需要保留的图层的 name 。
示例
// 清除除了 'township-pudong' 以外的所有图层
map.clear(['township-pudong'])
2
# 控件及容器
用于向地图中添加控件，或者获取地图的容器。
addControl(control, position?)
将IControl 添加到地图，调用control.onAdd(this)。
参数
control(IControl): 要添加的 IControl 。
position(string?): 控件添加到地图的位置。 有效值包括： 'top-left' ， 'top-right' ， 'bottom-left' ，和 'bottom-right' 。默认为 'top-right' 。
返回值
Map: this
getContainer()
返回地图的 HTML 嵌套元素。
返回值
HTMLElement: 地图容器（container）。
getCanvasContainer()
返回包含地图 <canvas> 标签的 HTML 元素。
如果想给地图上添加非 GL 叠加图层，可以将其追加（append）在这一元素结尾。
该元素用于给地图交互性（如平移和缩放）进行事件绑定。它接受来自子元素 <canvas>， 但不接受来自地图控件的冒泡事件。
返回值
HTMLElement: 地图 <canvas> 的容器。
getCanvas()
返回地图的 <canvas> 元素。
返回值
HTMLCanvasElement: 地图的 <canvas> 元素。
# 坐标转换
用于在地图中的地理坐标和屏幕坐标之间互相转换。
project(lnglat)
返回一个表示像素坐标的Point，相对于地图的container，与指定的地理位置相对应。
参数
lnglat(LngLatLike): 投影的地理学坐标。
返回值
Point: Point 对应于 lnglat ，跟地图的 container 相关。
unproject(point)
返回一个LngLat，代表与指定像素坐标对应的地理坐标。
参数
point(PointLike): 未投影的像素坐标。
返回值
LngLat: LngLat 对应于 point 。
# 交互控制
用于配置地图的控制方式，例如是否可以拖动，是否可以旋转，滚轮操作时的缩放速度。
scrollzoom
地图的ScrollZoomHandler，它使用滚轮或触控板实现放大和缩小。
boxZoom
地图的BoxZoomHandler，它使用按住 Shift 键拖动手势实现缩放。
dragRotate
地图的DragRotateHandler，它实现了用鼠标右键或按住 Ctrl 键拖动时旋转地图。
dragPan
地图的DragPanHandler，它实现用鼠标或触摸手势拖拽地图。
keyboard
地图的KeyboardHandler，它允许用户使用键盘快捷键缩放、旋转和平移地图。
doubleClickZoom
地图的DoubleClickZoomHandler，它允许用户通过双击来缩放。
touchZoomRotate
地图的TouchZoomRotateHandler，它允许用户使用触摸手势缩放或旋转地图。
# 生命周期
获取地图的状态信息，例如：地图样式是否加载完成。
loaded()
返回一个表示地图是否载入完毕的布尔值。
返回 false 如果样式尚未完全载入，或者正在载入的数据源或样式的改动尚未完全载入。
返回值
boolean: 一个用来表示地图是否完全加载的布尔值。
remove()
清理并释放和地图相关的所有内部数据源。包括 DOM 元素，事件绑定，工作线程，和 WebGL 资源。当你使用完地图并希望不再占用浏览器资源时可以使用该方法。之后你将不能在地图上调用任何方法。
triggerRepaint()
触发一个显示框的渲染。使用自定义图层时，当图层发生改变，使用此方法去重渲染。 在下一个显示框渲染前多次调用此方法也只会渲染一次。
# 事件监听
用于为地图绑定或者解绑操作事件。
on(type, listener)
为特定类型的事件添加监听器。
参数
type(string): 添加监听器的事件类型。
listener(Function): 事件被触发时调用的函数。使用传递给 fire 的数据对象调用监听函数，并使用 target 和 type 属性进行扩展。
返回值
Map: this
off(type, listener)
移除先前用Map#on添加的事件监听器。
参数
type(string): 之前用来安装监听器的事件类型。
listener(Function): 之前安装的监听器函数。
返回值
Map: this
# 全局图层高度
用于对全局的底图图层指定高度。
setLayerHeight(layerHeight)
指定全局的图层高度。
参数
layerHeight(number): 全局图层高度，范围-5000~5000，单位米。
返回值
Map: this
getLayerHeight()
获取全局的图层高度。
返回值
number: 全局的图层高度。
# Debug 信息
用于显示地图相关的 Debug 信息，例如显示所有瓦片的边界及编号。
showTileBoundaries
获取并设置一个布尔值，用以表示地图是否会渲染切片边界。这些切片边界有助于查错。
第一个矢量数据源的未压缩文件大小会被渲染到每一个切片的左上角，且在切片 ID 旁边。
showCollisionBoxes
获取并设置一个布尔值，指示地图是否会渲染数据源中所有符号周围的框，以及哪些符号已经被渲染，哪些因为冲突而被隐藏。这些信息有助于查错。
repaint
获得并设置一个布尔值，用于指示地图是否将继续再渲染。该信息有助于分析效果。
# 实例变量
# accessToken
获取和设置地图的访问令牌 accessToken。
# 示例
aimap.accessToken = '你的访问令牌';
# baseApiUrl
获取和设置地图默认的API URL用来请求切片、样式、雪碧图和字体。
# 示例
// 具体使用方式，可參考示例写法
aimap.baseApiUrl = 'an-aimap-server';
2
# workerCount
获取和设置GL JS 地图页面上实例化的 web workers 数量。该数量默认是CPU核数量的一半（最多为6）。请在创建地图实例前设置该属性，以使其生效。
# 示例
aimap.workerCount = 2;
# maxParallelImageRequests
获取或者设置并行加载图片（raster tiles, sprites, icons等）的最大值， 该值将影响加载较多栅格瓦片的地图的性能。默认值为16。
# 示例
aimap.maxParallelImageRequests = 10;
# supported
返回一个布尔值，用于测试浏览器是否支持 aimap.gl。
# 参数
options(Object?)
| Name | Description |
|---|---|
options.failIfMajorPerformanceCaveat boolean default false | 预期为 true ，此方法将返回 false 时，则表明当前浏览器下 aimap.gl 的性能大大低于预期（即使用软件渲染器）。 |
# 返回值
boolean:是否支持。
# 示例
aimap.supported() // = true
# version
当前使用的 aimap.gl 版本。
# clearStorage
清除浏览器中被 aimap.gl 库使用过的存储。使用该方法冲洗掉正在被这个库所管理的瓦片缓存。在某些情况下，瓦片或许仍旧缓存在浏览器中。
# 参数
callback(Function)有错误时该方法会被调用，同时错误信息将作为参数传入。
# AnimationOptions
地图移动方法所共有的选项，比如Map#panBy and Map#easeTo,能够控制动态转换的持续时间和缓动函数。 所有属性均可选。
# 属性
duration(number): 动态转换的持续时间，按毫秒计算。
easing(Function): 该函数持续的时间在 0~1 之间， 返回一个表示状态的数字，初始状态为 0，最终状态为 1
offset(PointLike): 动态转换结束后，目标中心与实际地图容器中心间的偏差。
animate(boolean): If false , no animation will occur.
# CameraOptions
共有选项 Map#jumpTo，Map#easeTo，和Map#flyTo， 控制默认位置、缩放级别、方位角和倾斜度。 所有属性均可选。 未指定的选项将默认设为当前地图该属性的值。
# 属性
center(LngLatLike): 预设的中心。
zoom(number): 预设的缩放级别。
bearing(number): 预设的方位角（bearing，rotation），按照逆时针偏离正北方的度数计算。
pitch(number): 预设的倾斜度（pitch），单位为度。
around(LngLatLike): 如果 zoom 是确定的 around 将决定缩放中心（默认为地图中心）。
# PaddingOptions
用于设置内边距(padding)的选项当调用 Map#fitBounds. 所有这个对象的属性必须为非负整数。
# 属性
top(number): 距地图画布顶端的内边距，以像素为单位。
bottom(number): 距地图画布底部的内边距，以像素为单位。
left(number): 距地图画布左端的内边距，以像素为单位。
right(number): 距地图画布右端的内边距，以像素为单位。
# RequestParameters
一个RequestParameters 对象会被Map.options.transformRequest回调方法返回。
# 属性
url(string): 待请求的URL。
headers(Object): 随请求发送的请求头(headers)。
credentials(string): 'same-origin'|'include' 使用'include'来发送带有跨域请求的cookies。
# StyleImageInterface
用于动态生成样式图像的接口。实现此接口应遵循的规范是：它不是导出的方法或类。
所有实现此接口的图像将重新绘制每一帧。它们可以用于生成动态图标和样式，或根据用户输入的内容进行响应。样式图像可以实现一个StyleImageInterface#render 方法，图像每一帧的渲染都将调用此方法，可用于更新图像。
# 属性
width(number)
height(number)
data((Uint8Array | Uint8ClampedArray))
# 示例
var flashingSquare = {
width: 64,
height: 64,
data: new Uint8Array(64 * 64 * 4),
onAdd: function(map) {
this.map = map;
},
render: function() {
// keep repainting while the icon is on the map
this.map.triggerRepaint();
// alternate between black and white based on the time
var value = Math.round(Date.now() / 1000) % 2 === 0 ? 255 : 0;
// check if image needs to be changed
if (value !== this.previousValue) {
this.previousValue = value;
var bytesPerPixel = 4;
for (var x = 0; x < this.width; x++) {
for (var y = 0; y < this.height; y++) {
var offset = (y * this.width + x) * bytesPerPixel;
this.data[offset + 0] = value;
this.data[offset + 1] = value;
this.data[offset + 2] = value;
this.data[offset + 3] = 255;
}
}
// return true to indicate that the image changed
return true;
}
}
}
map.addImage('flashing_square', flashingSquare);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# 实例成员
render()
此方法将在渲染图标的每帧前调用一次。此方法data 可使用一个新图像去更新图像数据。
如果此方法更新了图像，它必将返回true 以提交修改。如果此方法返回 false 或无返回，则可假定图像没有发生变化。
如果更新图像不频繁，选择 Map#updateImage 更新图像将比实现此方法更方便。
返回值
boolean: true 表明此方法更新了图像。 false 表明图像没有发生变化。
onRemove()
可选方法。当通过 Map#removeImage方法从地图移除图标时触发。可用于清理图像资源以及相关的事件监听。
# 其他方法
# 日照分析
该功能需要先启用 threeBox 插件，启用方式：
// 在创建地图之前
aimap.Plugin(["threeBox"]);
2
# 代码示例
map.on('load', () => {
map.tb.setBuildingShadows({layerId: 'building-shadows', buildingsLayerId: 'building'});
});
2
3
# 参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| layerId | string | 创建的阴影图层的 id。 |
| buildingsLayerId | string | 当前地图中，建筑物图层的 id，这个 id 可以在底图的样式中看到。 |