你正要离开Mapbox中国网站

并非所有mapbox.com的服务在中国提供

Mapbox GL JS

Current version: mapbox-gl.js v1.1.1

Mapbox GL JS 是一个 JavaScript 库,它使用 WebGL,以 vector tilesMapbox styles 为来源,将它们渲染成互动式地图。它是 Mapbox GL 生态系统的一部分,其中还包括 Mapbox Mobile,它是一个用 C++ 编写的兼容桌面和移动平台的渲染引擎。

Map 对象代表页面上的地图。它暴露了一系列的方法和属性使得用户可以通过编程开发对地图进行修改,并在用户与地图交互时触发一系列的事件。

您可以创建Map,通过指定的container和其他可选参数。Mapbox GL JS 会在页面上初始化地图并返回您的Map对象。

Extends Evented.

new Map(options: Object)
Parameters
options(Object)
NameDescription
options.container
(HTMLElement | string)
Mapbox GL JS 进行地图渲染的 HTML 元素,或该元素的字符串 id 。该指定元素不能有子元素。
options.minZoom
number
default 0
地图最小缩放级别(0-24)。
options.maxZoom
number
default 22
地图最大缩放级别(0-24)。
options.style
(Object | string)?
地图的 Mapbox 配置样式。它必须是一个符合 Mapbox 样式规范 的 JSON 对象,或者是一个指向该 JSON 的 URL 地址。

要从Mapbox API加载样式,您可以填写如下格式的 URLmapbox://styles/:owner/:style, 其中 :owner 是您的 Mapbox 账户名 :style 是样式 ID 。或者您可以使用以下 预定义 Mapbox 样式:

  • mapbox://styles/mapbox/streets-v10
  • mapbox://styles/mapbox/outdoors-v10
  • mapbox://styles/mapbox/light-v9
  • mapbox://styles/mapbox/dark-v9
  • mapbox://styles/mapbox/satellite-v9
  • mapbox://styles/mapbox/satellite-streets-v10
  • mapbox://styles/mapbox/navigation-preview-day-v2
  • mapbox://styles/mapbox/navigation-preview-night-v2
  • mapbox://styles/mapbox/navigation-guidance-day-v2
  • mapbox://styles/mapbox/navigation-guidance-night-v2

由 Mapbox 托管的切片集合可进行样式优化,只需将 ?optimize=true 添加到样式 URL 的末尾即可,例如 mapbox://styles/mapbox/streets-v9?optimize=true。 更多关于矢量切片样式优化的内容,请查阅API 文档.

options.hash
boolean
default false
如果为 true ,地图的位置 (包括缩放层级、中心纬度、中心经度、方位角和倾角) 将会与页面URL的哈希片段同步。例如, http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60
options.interactive
boolean
default true
如果为 false ,地图将不会绑定对鼠标、触碰、键盘的监听,因此地图将不会响应任何用户交互。
options.bearingSnap
number
default 7
定义何时地图的方位将自动对齐到正北方向的阈值(以度为单位)。例如,当 bearingSnap 为 7 时,如果用户将地图转动到正北方向 7 度以内的范围时,地图将自动恢复对齐到正北方向。
options.pitchWithRotate
boolean
default true
如果为 false ,将不会在"拖拽进行地图旋转"的同时控制地图的倾斜。
options.clickTolerance
number
default 3
当用户点击地图时能进行鼠标移动的最大像素范围,点击地图后鼠标在此像素范围内移动则被认为是一次有效的点击(而不是拖拽)。
options.attributionControl
boolean
default true
如果为 trueAttributionControl 将会被添加到地图上。
options.customAttribution
(string | Array<string>)?
AttributionControl 中显示的字符串或字符串数组。仅当 options.attributionControltrue 时生效。
options.logoPosition
string
default 'bottom-left'
设置 Mapbox 文字商标在地图上的位置。可选填以下值 top-lefttop-rightbottom-leftbottom-right
options.failIfMajorPerformanceCaveat
boolean
default false
如果为 true , 当 Mapbox GL JS 的性能远远低于预期的时候,地图将创建失败。 (换句话说,此时可能是用的软件渲染器)。
options.preserveDrawingBuffer
boolean
default false
如果为 true ,地图画布可通过 map.getCanvas().toDataURL() 输出 PNG 。出于性能优化考虑,该值默认为 false
options.antialias
boolean?
如果为 true ,gl 渲染环境在创建时将开启多重采样抗锯齿模式( MSAA ), 这对自定义图层的抗锯齿十分有效。出于性能优化考虑,该值默认为 false
options.refreshExpiredTiles
boolean
default true
如果为 false ,一旦切片的 HTTP cacheControl / expires headers 过期,地图将不会重新请求这些切片。
options.maxBounds
LngLatBoundsLike?
设置之后,地图将限制在给定的最大范围内。
options.scrollZoom
(boolean | Object)
default true
如果为 true ,将开启 "滚轮缩放地图" 交互模式。如果传值为 Object 对象,对象可选参数参考 ScrollZoomHandler#enable
options.boxZoom
boolean
default true
如果为 true , 将开启 "框选缩放地图" 交互模式 (查阅 BoxZoomHandler )。
options.dragRotate
boolean
default true
如果为 true , 将开启 "拖拽旋转地图" 交互模式 (查阅 DragRotateHandler )。
options.dragPan
boolean
default true
如果为 true , 将开启 "拖拽移动地图" 交互模式 (查阅 DragPanHandler )。
options.keyboard
boolean
default true
如果为 true ,将启用键盘快捷键功能 (查阅 KeyboardHandler )。
options.doubleClickZoom
boolean
default true
如果为 true ,将开启 "双击缩放地图" 交互模式 (查阅 DoubleClickZoomHandler )。
options.touchZoomRotate
(boolean | Object)
default true
如果为 true ,将开启 "捏合旋转、缩放" 交互模式。如果传值为 Object 对象,对象可选参数参考 TouchZoomRotateHandler#enable
options.trackResize
boolean
default true
如果为 true ,地图将自适应窗口大小变化。
options.center
LngLatLike
default [0,0]
地图初始化时的地理中心点。如果构造函数的参数中没有设置 center ,Mapbox GL JS 会在地图样式中进行查找。如果样式中也没定义的话,那么它将默认为 [0, 0] 注意: 为了与 GeoJSON 保持一致,Mapbox GL 采用经度,纬度的顺序 (而不是纬度,经度)。
options.zoom
number
default 0
地图初始化时的层级。如果构造函数的参数中没有设置 zoom Mapbox GL JS 会在地图样式中进行查找。如果样式中也没定义的话,那么它将默认为 0
options.bearing
number
default 0
地图初始化时的方位角(旋转角度),以正北方的逆时针转动度数计量。如果构造函数的参数中没有设置 bearing ,Mapbox GL JS 会在地图样式中进行查找。如果样式中也没定义的话,那么它将默认为 0
options.pitch
number
default 0
地图初始化时的倾角,按偏离屏幕水平面的度数计量(0-60)。如果构造函数的参数中没有设置 pitch ,Mapbox GL JS 会在地图样式中进行查找。如果样式中也没定义的话,那么它将默认为 0
options.bounds
LngLatBoundsLike?
地图初始化时的限制范围。如果设置了 bounds 将会覆盖掉 centerzoom 在构造函数中的参数设置。
options.fitBoundsOptions
Object?
fitBounds 仅用于 初始化地图时自适应设置的 bounds 范围时的情况。
options.renderWorldCopies
boolean
default true
如果为 true ,地图缩小时将渲染多个全局地图的副本。
options.maxTileCacheSize
number
default null
设置当前数据源存储在切片缓存中的最大切片数目。如果不设置,将基于当前视角动态计算切片缓存大小。
options.localIdeographFontFamily
string
default 'sans-serif'
定义一个用于在本地替代通用‘中日韩越统一表意文字’,’平假名’,‘片假名’和‘朝鲜文音节’字形的 CSS 字体系列。 在上述字体在地图样式中的设置,除字体粗细(light/regular/medium/bold)外,都将被忽略。 当设置为 false ,上述字体则使用地图样式中的设置。 该参数的目的是为了避免超带宽的字形请求。(查阅 Use locally generated ideographs
options.transformRequest
RequestTransformFunction
default null
地图发送外部 URL 请求前执行的回调函数。回调函数中可修改 URL 、设置请求头或设置跨源请求的相关身份凭证。回调返回的对象参数包含 url 属性和可选的 headers 以及 credentials 属性。
options.collectResourceTiming
boolean
default false
如果为 true ,那么将为 GeoJSON 和 Vector Tile web workers 发出的请求搜集资源耗时API信息(通常无法从 Javascript 主线程中访问此信息)。该信息将在 resourceTiming 属性中返回(对应于 data 事件)。
options.fadeDuration
number
default 300
控制标注冲突时,淡入淡出的动画过渡时间, 单位为毫秒。该设置将应用于所有 symbol 图层。对于运行时的样式变化和栅格切片的淡入淡出,此设置不生效。
options.crossSourceCollisions
boolean
default true
如果为 true ,来自不同数据源的符号将共同参与到碰撞检测中。如果为 false ,仅在各自的数据源中相互独立的进行符号的碰撞检测。
options.accessToken
string
default null
设置之后,地图将用此 token 替换掉在 mapboxgl.accessToken 中设置的值。
Example
var map = new mapboxgl.Map({
  container: 'map',
  center: [-122.420679, 37.772537],
  zoom: 13,
  style: style_object,
  hash: true,
  transformRequest: (url, resourceType)=> {
    if(resourceType === 'Source' && url.startsWith('http://myHost')) {
      return {
       url: url.replace('http', 'https'),
       headers: { 'my-custom-header': true},
       credentials: 'include'  // Include cookies for cross-origin requests
     }
    }
  }
});
Instance Members
Events

获取和设置地图的访问令牌access token.

Example
mapboxgl.accessToken = myAccessToken;
Related

获取和设置地图默认的API URL用来请求切片、样式、雪碧图和字体

Example
mapboxgl.baseApiUrl = 'https://api.mapbox.com';

获取和设置GL JS 地图页面上实例化的 web workers 数量。该数量默认是CPU核数量的一半(最多为6)。请在创建地图实例前设置该属性,以使其生效。

Example
mapboxgl.workerCount = 2;

获取或者设置并行加载图片(raster tiles, sprites, icons等)的最大值, 该值将影响加载较多栅格瓦片的地图的性能。默认值为16。

Example
mapboxgl.maxParallelImageRequests = 10;

返回一个布尔值,用于测试浏览器是否 支持 Mapbox GL JS。

Parameters
options(Object?)
NameDescription
options.failIfMajorPerformanceCaveat
boolean
default false
预期为 true ,此方法将返回 false 时,则表明当前浏览器下Mapbox GL JS 的性能大大低于预期(即使用软件渲染器)。
Returns
boolean:
Example
mapboxgl.supported() // = true

当前使用的Mapbox GL JS 版本说明位于package.json, CHANGELOG.md, 和 GitHub release中。

设置当前地图的 RTL text plugin. 用于支持从右向左书写的语言(如阿拉伯语和希伯来语)。Mapbox Studio 默认情况下加载此插件。

Parameters
pluginURL(string)指向Mapbox RTL文本插件源的URL。
callback(Function)当出现错误时,使用错误参数回调。
Example
mapboxgl.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.0/mapbox-gl-rtl-text.js');

清除浏览器中被mapbox js库使用过的存储。使用该方法冲洗掉正在被这个库所管理的瓦片缓存。在某些情况下,瓦片或许仍旧缓存在浏览器中。

Parameters
callback(Function)有错误时该方法会被调用,同时错误信息将作为参数传入。

地图移动方法所共有的选项,比如Map#panBy and Map#easeTo,能够控制动态转换的持续时间和缓动函数。 所有属性均可选。

Properties
duration(number): 动态转换的持续时间,按毫秒计算。
easing(Function): 该函数持续的时间在 0~1 之间, 返回一个表示状态的数字,初始状态为 0,最终状态为 1
offset(PointLike): 动态转换结束后,目标中心与实际地图容器中心间的偏差。
animate(boolean): If false , no animation will occur.

共有选项 Map#jumpToMap#easeTo,和Map#flyTo, 控制默认位置、缩放级别、方位角和倾斜度。 所有属性均可选。 未指定的选项将默认设为当前地图该属性的值。

Properties
center(LngLatLike): 预设的中心。
zoom(number): 预设的缩放级别。
bearing(number): 预设的方位角(bearing,rotation),按照逆时针偏离正北方的度数计算。
pitch(number): 预设的倾斜度(pitch,tilt),单位为度。
around(LngLatLike): 如果 zoom 是确定的 around 将决定缩放中心(默认为地图中心)。

用于设置内边距(padding)的选项当调用 Map#fitBounds. 所有这个对象的属性必须为 非负整数.

Properties
top(number): 距地图画布顶端的内边距,以像素为单位.
bottom(number): 距地图画布底部的内边距,以像素为单位.
left(number): 距地图画布左端的内边距,以像素为单位.
right(number): 距地图画布右端的内边距,以像素为单位.

一个RequestParameters 对象会被Map.options.transformRequest回调方法返回.

Properties
url(string): 待请求的URL.
headers(Object): 随请求发送的请求头(headers).
credentials(string): 'same-origin'|'include' 使用'include'来发送带有跨域请求的cookies.

用于动态生成样式图像的接口。实现此接口应遵循的规范是:它不是导出的方法或类。

所有实现此接口的图像将重新绘制每一帧。它们可以用于生成动态图标和样式,或根据用户输入的内容进行响应。样式图像可以实现一个StyleImageInterface#render 方法,图像每一帧的渲染都将调用此方法,可用于更新图像。

Properties
width(number)
height(number)
Example
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);
Instance Members

为自定义样式的图层提供的接口。这是一个为模型实现者提供的规范:它不是一个导出的方法或者类。

自定义图层允许用户直接使用地图的相机渲染到地图的GL上下文中。 这些图层也可以通过Map#addLayer方法添加到任意普通的图层之间。

自定义图层必须有一个唯一的id 并且必须有 type 属于 "custom"。 它们必须实现 render并且或许还要实现 prerender, onAddonRemove。 它们通过 Map#triggerRepaint触发渲染, 并且它们应该恰当地处理 Map.event:webglcontextlostMap.event:webglcontextrestored

renderingMode 属性控制一个图层是按照 "2d""3d"的地图图层来处理。 使用方式如下:

  • "renderingMode": "3d" 为了使用深度缓冲并且和其他图层共享深度缓冲
  • "renderingMode": "2d" 为了添加不带深度的图层。 如果你需要在 "2d" 图层中使用深度缓冲, 你必须使用离屏帧缓冲和 CustomLayerInterface#prerender
Properties
id(string): 一个唯一的图层标识。
type(string): 图层的类型。 必须是 "custom"
renderingMode(string): 要么是 "2d" 要么是 "3d" 。 默认值为 "2d"
Example
// 用ES6类的形式实现的自定义图层
class NullIslandLayer {
    constructor() {
        this.id = 'null-island';
        this.type = 'custom';
        this.renderingMode = '2d';
    }

    onAdd(map, gl) {
        const vertexSource = `
        uniform mat4 u_matrix;
        void main() {
            gl_Position = u_matrix * vec4(0.5, 0.5, 0.0, 1.0);
            gl_PointSize = 20.0;
        }`;

        const fragmentSource = `
        void main() {
            gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
        }`;

        const vertexShader = gl.createShader(gl.VERTEX_SHADER);
        gl.shaderSource(vertexShader, vertexSource);
        gl.compileShader(vertexShader);
        const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
        gl.shaderSource(fragmentShader, fragmentSource);
        gl.compileShader(fragmentShader);

        this.program = gl.createProgram();
        gl.attachShader(this.program, vertexShader);
        gl.attachShader(this.program, fragmentShader);
        gl.linkProgram(this.program);
    }

    render(gl, matrix) {
        gl.useProgram(this.program);
        gl.uniformMatrix4fv(gl.getUniformLocation(this.program, "u_matrix"), false, matrix);
        gl.drawArrays(gl.POINTS, 0, 1);
    }
}

map.on('load', function() {
    map.addLayer(new NullIslandLayer());
});
Instance Members

Geography & Geometry

LngLatLngLatBounds 表示地理世界中的点和面 坐标。Point 表示屏幕坐标系中的点。

LngLat对象表示一个指定的经纬度坐标,单位为度。

为了与 GeoJSON 格式匹配,Mapbox GL 使用经度、纬度(而不是纬度、经度)的坐标顺序。

需注意,任何接受LngLat对象作为参数或选项的 Mapbox GL 方法,同样也可以接受两个数字组成的Array,并且会进行隐式转换。这个灵活的类型被记录为LngLatLike

new LngLat(lng: number, lat: number)
Parameters
lng(number)经度,单位为度。
lat(number)纬度,单位为度。
Example
var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
Static Members
Instance Members

一个LngLat对象,或者是表示经度和纬度的两个数字组成的数组, 也可以是一个具有lnglat或者lonlat属性的对象。

Example
var v1 = new mapboxgl.LngLat(-122.420679, 37.772537);
var v2 = [-122.420679, 37.772537];
var v3 = {lon: -122.420679, lat: 37.772537};

LngLatBounds对象表示一个地理边界框,由经纬度表示的西南和东北点来定义。

如果没有给构造函数提供参数,则创建一个null边界框。

注意,任何接受LngLatBounds对象作为参数或选项的 Mapbox GL 方法,同样也可以接受由两个LngLatLike组成的Array,并会执行隐式转换。这种灵活的类型被记录为LngLatBoundsLike

new LngLatBounds(sw: LngLatLike?, ne: LngLatLike?)
Parameters
sw(LngLatLike?)范围框的西南角。
ne(LngLatLike?)范围框的东北角。
Example
var sw = new mapboxgl.LngLat(-73.9876, 40.7661);
var ne = new mapboxgl.LngLat(-73.9397, 40.8002);
var llb = new mapboxgl.LngLatBounds(sw, ne);
Static Members
Instance Members

一个LngLatBounds对象,或者是一个LngLatLike对象的数组以[西南,东北]为顺序, 也可以是一个数字组成的数组以[西,南,东,北]为顺序。

Example
var v1 = new mapboxgl.LngLatBounds(
  new mapboxgl.LngLat(-73.9876, 40.7661),
  new mapboxgl.LngLat(-73.9397, 40.8002)
);
var v2 = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
var v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];

一个 Point geometry 对象, 具有 xy 属性, 代表屏幕上像素坐标.

一个 Point对象或者一个数组包含了 xy 屏幕像素坐标.

一个 MercatorCoordinate 实例表示一个三维投影坐标。

MercatorCoordinate 使用Web墨卡托投影(EPSG:3857) 但在单位处理上略微不同:

  • 单位1表示投影后世界的宽度而不是原来定义的墨卡托坐标中的米
  • 坐标空间的原点为西北角而不是原来的中心点

例如, MercatorCoordinate(0, 0, 0) 表示墨卡托空间的西北角, MercatorCoordinate(1, 1, 0) 表示东南角。如果你熟悉 vector tiles 可以认为该坐标空间等同于extent为1的 0/0/0 矢量瓦片的坐标空间

z 轴在 MercatorCoordinate 中与其它轴是等比例共形相似的。墨卡托坐标中的立方体渲染出来仍是立方体。

new MercatorCoordinate(x: number, y: number, z: number)
Parameters
x(number)x轴上的位置。
y(number)y轴上的位置。
z(number)(default 0)z轴上的位置。
Example
var nullIsland = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
Static Members
Instance Members

User Interface

Controls, markers, 和 popups 为地图添加了新的用户界面元素。

添加地图交互控件的接口。 这是一份 开发者编写模块的规范:这不是 一个 exported 方法或者类

控件必须实现onAddonRemove方法,并且必须要自带一个 元素,通常是一个div元素。 为了使用Mapbox GL JS 默认的控件样式,需要添加mapboxgl-ctrl 类到你的控件 节点中。

Example
// 用ES6标准实现控件类
class HelloWorldControl {
    onAdd(map) {
        this._map = map;
        this._container = document.createElement('div');
        this._container.className = 'mapboxgl-ctrl';
        this._container.textContent = 'Hello, world';
        return this._container;
    }

    onRemove() {
        this._container.parentNode.removeChild(this._container);
        this._map = undefined;
    }
}

// 用ES5标准实现控件的原型类
function HelloWorldControl() { }

HelloWorldControl.prototype.onAdd = function(map) {
    this._map = map;
    this._container = document.createElement('div');
    this._container.className = 'mapboxgl-ctrl';
    this._container.textContent = 'Hello, world';
    return this._container;
};

HelloWorldControl.prototype.onRemove = function () {
     this._container.parentNode.removeChild(this._container);
     this._map = undefined;
};
Instance Members

A NavigationControl 控件包括缩放按钮和一个指南针.

new NavigationControl(options: Object?)
Parameters
options(Object?)
NameDescription
options.showCompass
Boolean
default true
If true 引入指南针按钮.
options.showZoom
Boolean
default true
If true 引入放大和缩小按钮.
options.visualizePitch
Boolean
default false
If true 旋转指南针的Y轴来显示俯仰角度.
Example
var nav = new mapboxgl.NavigationControl();
map.addControl(nav, 'top-left');

A GeolocateControl GeolocateControl 提供了一个按钮,使用浏览器自带的地理定位API, 在地图上定位用户。

部分浏览器可能不支持地理定位功能, 也有部分用户禁用了浏览器的该功能。 包括Chrome在内的现代浏览器,要求那些调用浏览器地理定位功能的网站使用HTTPS协议。 如果浏览器的地理定位功能不可用,GeolocateControl按钮将不可见。

实际采用的缩放层级将取决于终端设备所提供定位服务的精度。

GeolocateControl 支持两种模式。如果trackUserLocationfalse (默认) 那么控件将变成一个按钮, 初次点击按钮会把地图的镜头设置为指向用户所在的位置。如果用户移动了,地图镜头状态不会更新。对桌面端用户来说这样是非常合适的。如果trackUserLocationtrue 那么控件将变成一个切换按钮,当用户的位置处于活动状态时,将对其位置的更改进行主动监视。 在这个模式下,the GeolocateControl有三种状态:

  • active - 当用户的位置发生变化时,地图的相机焦点会自动更新,将其保持在地图的中心位置。
  • passive - 用户的位置点会自动更新,但是地图的相机焦点不会变化。
  • disabled

Extends Evented.

new GeolocateControl(options: Object?)
Parameters
options(Object?)
NameDescription
options.positionOptions
Object
default {enableHighAccuracy:false,timeout:6000}
A Geolocation API PositionOptions 对象.
options.fitBoundsOptions
Object
default {maxZoom:15}
A fitBounds 当地图平移缩放到用户位置时,使用这个可选对象。默认是把 maxZoom 设置成15,来限制地图的最大缩放精度。
options.trackUserLocation
Object
default false
If true Geolocate控件变成一个切换按钮,当激活时,地图将在用户位置发生更改时接收到更新。
options.showUserLocation
Object
default true
默认情况下,地图会在用户所在位置上显示一个点。设置为 false 禁用。
Example
map.addControl(new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true
}));
Instance Members
Events
Related

一个 AttributionControl 控制展示地图的属性信息

new AttributionControl(options: Object?)
Parameters
options(Object?)(default {})
NameDescription
options.compact
boolean?
如果 true 鼠标悬停时将强制显示一个简洁版的属性信息 false 强制显示完整属性控件。默认为一个响应属性控件,当地图宽度低于640像素的时候该控件会折叠起来。
options.customAttribution
(string | Array<string>)?
用来表达额外的属性字符串。
Example
var map = new mapboxgl.Map({attributionControl: false})
    .addControl(new mapboxgl.AttributionControl({
        compact: true
    }));

ScaleControl 控件用于显示图上距离和实际距离的比值(比例尺)。

new ScaleControl(options: Object?)
Parameters
options(Object?)
NameDescription
options.maxWidth
number
default '100'
ScaleControl控件的最大长度,以像素为单位。
options.unit
string
default 'metric'
距离的单位 ( 'imperial' , 'metric''nautical' )。
Example
var scale = new mapboxgl.ScaleControl({
    maxWidth: 80,
    unit: 'imperial'
});
map.addControl(scale);

scale.setUnit('metric');
Instance Members

A FullscreenControl 全屏控件,包含一个切换地图进入和退出全屏模式的按钮。

new FullscreenControl(options: Object?)
Parameters
options(Object?)
NameDescription
options.container
HTMLElement?
container兼容DOM元素 它应当被全屏显示。默认情况下,地图容器元素会被全屏显示。
Example
map.addControl(new mapboxgl.FullscreenControl({container: document.querySelector('body')}));

弹窗组件。

Extends Evented.

new Popup(options: Object?)
Parameters
options(Object?)
NameDescription
options.closeButton
boolean
default true
如果为 true ,弹窗右上角 将出现关闭按钮。
options.closeOnClick
boolean
default true
如果为 true ,点击地图时 弹窗将关闭。
options.anchor
string?
表示弹窗位置的字符,通过 Popup#setLngLat 与坐标集关联。 选项有 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' ,以及 'bottom-right' 。如未设置,将对锚点 进行动态设置,以保证弹窗落在地图容器内, 并偏向 'bottom'
options.offset
(number | PointLike | Object)?
对应到弹窗位置的像素偏移具体为:
  • 表示离弹窗位置距离的一个数字
  • 表示常数偏移的 PointLike
  • 表示每个锚点位置偏移程度的Point对象 负偏移表示向左和向上。
options.className
string?
添加到弹窗容器的以空格分隔的CSS类名。
options.maxWidth
string
default '240px'
设置弹窗CSS属性中最大宽度的字符串,例如 '300px' 。 为确保弹窗在缩放后能容纳内容,应设置此属性为 'none' 。 有效值请参考该链接: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
Example
var markerHeight = 50, markerRadius = 10, linearOffset = 25;
var popupOffsets = {
 'top': [0, 0],
 'top-left': [0,0],
 'top-right': [0,0],
 'bottom': [0, -markerHeight],
 'bottom-left': [linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
 'bottom-right': [-linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
 'left': [markerRadius, (markerHeight - markerRadius) * -1],
 'right': [-markerRadius, (markerHeight - markerRadius) * -1]
 };
var popup = new mapboxgl.Popup({offset: popupOffsets, className: 'my-class'})
  .setLngLat(e.lngLat)
  .setHTML("<h1>Hello World!</h1>")
  .setMaxWidth("300px")
  .addTo(map);
Instance Members
Events

创建标记组件

Extends Evented.

new Marker(options: Object?, legacyOptions: Options)
Parameters
options(Object?)
NameDescription
options.element
HTMLElement?
作为标记的DOM元素,默认是一个浅蓝色、水滴状的SVG标记。
options.anchor
string
default 'center'
一个字符串,用来表示标记的哪个部位距离坐标点最近,该坐标点可通过 Marker#setLngLat 设置。 字符串的值可以是 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' .
options.offset
PointLike?
通过 PointLike 对象表示相对于元素中心偏移的像素数,左和上分别为负方向。
options.color
string
default '#3FB1CE'
默认标记的颜色(在没有给出options.element时),其默认值是浅蓝色。
options.draggable
boolean
default false
一个布尔值,表示标记是否可以在地图上拖动。
legacyOptions(Options)
Example
var marker = new mapboxgl.Marker()
  .setLngLat([30.5, 50.5])
  .addTo(map);
Instance Members
Events

User Interaction Handlers

Handlers 为地图提供了多种交互功能 - 鼠标交互, 触摸交互, 以及其他 手势交互功能。

BoxZoomHandler 允许用户将地图缩放到适合限位框的大小。 可以通过按住shift键并拖动光标定义限位框。shift

Instance Members

ScrollZoomHandler 能够让用户通过滚动来缩放地图。

Instance Members

DragPanHandler 允许用户通过点击并且拖拽光标来平移地图。

Instance Members

DragRotateHandler 允许用户通过按住鼠标右键并拖拽光标来旋转地图,或按下ctrl 键并拖拽光标来旋转地图。

Instance Members

KeyboardHandler 允许用户使用下列键盘快捷键对地图进行缩放、旋转以及平移:

  • = / +:缩放级别增加 1 级。
  • Shift-= / Shift-+:缩放级别增加 2 级。
  • -:缩放级别减小 1 级。
  • Shift--:缩放级别减小 2 级。
  • Arrow keys:平移 100 像素。
  • Shift+⇢:增加 15 度旋转。
  • Shift+⇠:减少 15 度旋转。
  • Shift+⇡:增加 10 度倾斜角。
  • Shift+⇣:减少 10 度倾斜角。
Instance Members

DoubleClickZoomHandler 允许用户通过在地图上双击缩放地图。

Instance Members

The TouchZoomRotateHandler 允许用户通过捏合触摸屏来缩放和旋转地图

Instance Members

Sources

Sources用于指定将在地图中渲染的地理要素。 Source对象可通过 Map#getSource获得。

一种包含geojson数据的数据源。 (点击 GeoJson数据组织规范 更详细的配置项文档.)

Extends Evented.

Example
map.addSource('some id', {
    type: 'geojson',
    data: 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_ports.geojson'
});
map.addSource('some id', {
   type: 'geojson',
   data: {
       "type": "FeatureCollection",
       "features": [{
           "type": "Feature",
           "properties": {},
           "geometry": {
               "type": "Point",
               "coordinates": [
                   -76.53063297271729,
                   39.18174077994108
               ]
           }
       }]
   }
});
map.getSource('some id').setData({
  "type": "FeatureCollection",
  "features": [{
      "type": "Feature",
      "properties": { "name": "Null Island" },
      "geometry": {
          "type": "Point",
          "coordinates": [ 0, 0 ]
      }
  }]
});
Instance Members

包含视频的数据源 (查看 Style Specification 了解更详尽的选项文档.)

Extends ImageSource.

Example
// 添加到地图
map.addSource('some id', {
   type: 'video',
   url: [
       'https://www.mapbox.com/blog/assets/baltimore-smoke.mp4',
       'https://www.mapbox.com/blog/assets/baltimore-smoke.webm'
   ],
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

/ 更新
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

map.removeSource('some id');  / 删除
Instance Members
Related

包含图像的数据源。 (请参阅 Style Specification 查看有关选项的详细文档。)

Extends Evented.

Example
// 添加至地图
map.addSource('some id', {
   type: 'image',
   url: 'https://www.mapbox.com/images/foo.png',
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

// 更新坐标点
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

// 同时更新图像地址和坐标点
mySource.updateImage({
   url: 'https://www.mapbox.com/images/bar.png',
   coordinates: [
       [-76.54335737228394, 39.18579907229748],
       [-76.52803659439087, 39.1838364847587],
       [-76.5295386314392, 39.17683392507606],
       [-76.54520273208618, 39.17876344106642]
   ]
})

map.removeSource('some id');  // 移除
Instance Members
Related

包含 HTML 画布内容的数据源。 参考 CanvasSourceOptions 查看更多详细的配置信息。

Extends ImageSource.

Example
// add to map
map.addSource('some id', {
   type: 'canvas',
   canvas: 'idOfMyHTMLCanvas',
   animate: true,
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

// update
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

map.removeSource('some id');  // remove
Instance Members

给地图添加画布数据源类型的配置

Properties
type(string): 数据源类型,必须是 画布
canvas((string | HTMLCanvasElement)): 从像素值中读取到画布的数据源。可以是代表画布元素ID的字符串,或 HTMLCanvasElement 元素本身。
coordinates(Array<Array<number>>): 四个地理坐标表示画布的四个角,使用 [longitude, latitude] 坐标对。
animate(boolean?): 代表该画布的数据源是否被激活。人工画布是静态的(不用在每个框架下去读取像素值) animate 应当被设置为 false 来增强显示。

Events

Map (和其他类) 状态改变或地图交互中会派发各类事件。Evented 是用来绑定或者解绑这些事件的接口.

根据事件功能被混合到其他类的方法。

Instance Members

MapMouseEvent 和鼠标指针相关的地图事件类型。

Extends Object.

Instance Members

MapTouchEvent 是与触摸相关的地图事件的事件类型。

Extends Object.

Instance Members
Properties
originalEvent(MouseEvent)

MapDataEvent 对象同 Map.event:dataMap.event:dataloading 事件一起被触发。 dataType的值包括:

  • 'source':与任何数据源相关联的非切片数据
  • 'style':地图所使用的样式 style
Properties
type(string): 事件类型。
dataType(string): 已修改的数据类型,值取 'source''style' 之一。
isSourceLoaded(boolean?): 如果事件里有 dataTypesource 的,且`source`没有未完成的网络请求,则为True。
source(Object?): 数据源的规范样式 ,如果事件里 dataTypesource 的。
sourceDataType(string?): 该属性包含在内,如果如果事件里 dataTypesource 的,且事件表明了内部数据已被接收或修改。可能的值是 metadatacontent
tile(Object?): 已被加载或修改的切片,如果事件里 dataTypesource 的,且事件与正在加载的切片相关。
coord(Coordinate?): 切片的坐标,如果事件里 dataTypesource 的,且事件与正在加载的切片相关。

MapWheelEventwheel 地图事件的事件类型。

Extends Object.

Instance Members