Skip to content

地图

该对象代表您页面上的地图。它公开了一些方法和属性,使您能够以编程方式更改地图,并在用户与其交互时触发事件。Map

您可以通过指定 和其他选项来创建一个 Map。然后,Mapbox GL JS 会在页面上初始化地图并返回您的对象。MapcontainerMap

扩展了 Evented。

参数

选项类型默认值描述
optionsObject
options.accessTokenstringnull如果指定,地图将使用这个 token 而不是 mapboxgl.accessToken 中定义的那个。
options.antialiasbooleanfalse如果设为 true,gl 上下文将使用 MSAA antialiasing 创建。默认为 false 是出于性能优化的考虑。
options.attributionControlbooleantrue如果设为 true,将添加 AttributionControl 到地图。
options.bearingnumber0地图的初始 bearing(旋转),以逆时针方向从北方度量。如果在构造函数选项中未指定 bearing,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 0
options.bearingSnapnumber7阈值,以度为单位,用于确定地图的方位何时会对齐到正北方向。例如,bearingSnap 为 7 时,如果用户将地图旋转到距北方 7 度以内,地图将自动对齐到正北方向。
options.boundsLngLatBoundsLikenull地图的初始边界。如果指定了 bounds,它将覆盖 centerzoom 构造函数选项。
options.boxZoombooleantrue如果设为 true,将启用"框选缩放"交互(参见 BoxZoomHandler)。
options.centerLngLatLike[0,0]地图的初始地理 中心点。如果在构造函数选项中未指定 center,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 [0, 0]。注意:Mapbox GL 使用经度、纬度坐标顺序(而不是纬度、经度)以匹配 GeoJSON。
options.clickTolerancenumber3用户在点击过程中可以移动鼠标指针的最大像素数,以使其被视为有效点击(而不是鼠标拖动)。
options.collectResourceTimingbooleanfalse如果设为 true,将收集 GeoJSON 和 Vector Tile web workers 发出的请求的资源计时 API 信息(这些信息通常无法从主 JavaScript 线程访问)。信息将在相关 data 事件的 resourceTiming 属性中返回。
options.configObjectnull样式片段的初始配置选项。对象中的每个键是片段 ID(例如 basemap),每个值是配置对象。
options.containerHTMLElement | stringMapbox GL JS 将在其中渲染地图的 HTML 元素,或该元素的字符串 id。指定的元素必须没有子元素。
options.cooperativeGesturesboolean?如果设为 true,滚动缩放将需要按住 ctrl 或 ⌘ 键同时滚动才能缩放地图,触摸平移将需要使用两个手指才能移动地图。如果启用,触摸倾斜将需要三个手指才能激活。
options.crossSourceCollisionsbooleantrue如果设为 true,在碰撞检测期间,来自多个源的符号可以相互碰撞。如果设为 false,则对每个源的符号单独运行碰撞检测。
options.customAttributionstring | Array<string>nullAttributionControl 中显示的字符串或字符串数组。仅在 options.attributionControltrue 时适用。
options.doubleClickZoombooleantrue如果设为 true,将启用"双击缩放"交互(参见 DoubleClickZoomHandler)。
options.dragRotatebooleantrue如果设为 true,将启用"拖动旋转"交互(参见 DragRotateHandler)。
options.fadeDurationnumber300控制标签碰撞的淡入/淡出动画持续时间,以毫秒为单位。此设置影响所有符号层。此设置不影响运行时样式转换或栅格瓦片交叉淡入淡出的持续时间。
options.failIfMajorPerformanceCaveatbooleanfalse如果设为 true,当 Mapbox GL JS 的性能将大幅低于预期(将使用软件渲染器)时,地图创建将会失败。
options.fitBoundsOptionsObjectnull一个 Map#fitBounds 选项对象,用于适配上面提供的初始 bounds
options.hashboolean | stringfalse如果设为 true,地图的 位置(缩放、中心纬度、中心经度、方位和倾斜)将与页面 URL 的哈希片段同步。例如 http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60。还可以选择提供一个附加字符串来表示参数样式的哈希,例如 http://path/to/my/page.html#map=2.59/39.26/53.07/-24.1/60&foo=bar,其中 foo 是自定义参数,bar 是与地图哈希不同的任意哈希。
options.interactivebooleantrue如果设为 false,不会将任何鼠标、触摸或键盘监听器附加到地图,因此它不会响应交互。
options.language("auto" | string | Array<string>)null带有 BCP 47 语言标签的字符串,或这样的字符串数组,表示地图标签和 UI 组件所需的语言。语言只能在 Mapbox 矢量瓦片源上设置。默认情况下,GL JS 不会设置语言,因此 Mapbox 瓦片的语言将由矢量瓦片源的 TileJSON 确定。有效的语言字符串必须是 BCP-47 语言代码。不支持的 BCP-47 代码将不包含任何翻译。无效代码将导致可恢复的错误。如果标签没有所选语言的翻译,它将以标签的本地语言显示。如果选项设置为auto,GL JS 将选择浏览器的 window.navigator.language 属性确定的用户首选语言。如果未单独设置locale 属性,此语言也将用于本地化支持的语言的 UI。
options.localeObjectnull对 UI 字符串的默认本地化表进行补丁的对象,例如控件提示。locale 对象将命名空间 UI 字符串 ID 映射到目标语言中的翻译字符串;有关所有支持的字符串 ID 的示例,请参见 src/ui/default_locale.js。该对象可以指定所有 UI 字符串(从而添加对新翻译的支持)或仅一部分字符串(从而为默认翻译表打补丁)。
options.localFontFamilystringnull定义一个 CSS font-family,用于本地覆盖所有字形的生成。将忽略地图样式中的字体设置,但字体粗细关键字(light/regular/medium/bold)除外。如果设置,此选项将覆盖 localIdeographFontFamily 中的设置。
options.localIdeographFontFamilystring'sans-serif'定义一个 CSS font-family,用于本地覆盖"CJK 统一表意文字"、"平假名"、"片假名"、"朝鲜文音节"和"CJK 符号和标点符号"范围内的字形生成。在这些范围内,将忽略地图样式中的字体设置,但字体粗细关键字(light/regular/medium/bold)除外。设置为false,以便为这些字形范围启用地图样式中的字体设置。请注意,Mapbox Studio 默认将此值设置为false。此选项的目的是避免带宽密集型的字形服务器请求。有关此选项使用的示例,请参见使用本地生成的表意文字
options.logoPositionstring'bottom-left'表示 Mapbox 文字标志在地图上位置的字符串。有效选项为top-lefttop-rightbottom-leftbottom-right
options.maxBoundsLngLatBoundsLikenull如果设置,地图将被限制在给定的边界内。
options.maxPitchnumber85地图的最大倾斜度(0-85)。
options.maxTileCacheSizenumbernull为给定源存储在瓦片缓存中的最大瓦片数。如果省略,缓存将根据当前视口动态调整大小。
options.maxZoomnumber22地图的最大缩放级别(0-24)。
options.minPitchnumber0地图的最小倾斜度(0-85)。
options.minTileCacheSizenumbernull为给定源存储在瓦片缓存中的最小瓦片数。较大的视口使用更多的瓦片并需要更大的缓存。较大的视口更可能出现在内存更多的设备上以及地图更重要的页面上。如果省略,缓存将根据当前视口动态调整大小。
options.minZoomnumber0地图的最小缩放级别(0-24)。
options.performanceMetricsCollectionbooleantrue如果为true,mapbox-gl 将收集并发送性能指标。
options.pitchnumber0地图的初始倾斜度(倾斜),以远离屏幕平面的度数测量(0-85)。如果在构造函数选项中未指定pitch,Mapbox GL JS 将在地图的样式对象中查找它。如果在样式中也未指定,则默认为0
options.pitchRotateKey("Control" |"Alt" |"Shift" |"Meta")'Control'允许将用于倾斜/旋转交互的键盘修饰键从Control 更改为另一个修饰键。
options.pitchWithRotatebooleantrue如果为false,则将禁用具有"拖拽旋转"交互的地图倾斜(倾斜)控制。
options.preserveDrawingBufferbooleanfalse如果为true,则可以使用map.getCanvas().toDataURL() 将地图的画布导出为 PNG。默认情况下,这是false,以作为性能优化。
options.projectionProjectionSpecification'mercator'地图应该渲染的投影。支持的投影有:
  • Albers 等面积圆锥投影albers
  • Equal Earth 等面积伪圆柱投影equalEarth
  • Equirectangular(平板正切/WGS84)equirectangular
  • 3D 地球仪globe
  • Lambert Conformal ConiclambertConformalConic
  • Mercator 圆柱地图投影mercator
  • Natural Earth 伪圆柱地图投影naturalEarth
  • Winkel Tripel 方位地图投影winkelTripel。圆锥投影(如 Albers 和 Lambert)具有可配置的centerparallels 属性,使开发人员能够定义投影失真最小的区域;有关如何配置这些属性,请参见示例。
options.refreshExpiredTilesbooleantrue如果为false,一旦瓦片根据其 HTTPcacheControl/expires 头过期,地图将不会尝试重新请求它们。
options.renderWorldCopiesbooleantrue如果为true,超过 -180 和 180 度经度将并排渲染多个世界副本。如果设置为false
  • 当地图缩小到单个世界的表示不能填满地图的整个容器时,-180 和 180 度经度以外将会有空白。
  • 跨越 180 和 -180 度经度的要素将在每个缩放级别被分成两部分(一部分在地图的右边缘,另一部分在地图的左边缘)。
options.respectPrefersReducedMotionbooleantrue如果设置为true,地图将尊重用户的prefers-reduced-motion 浏览器设置并应用减少运动模式,最小化动画和过渡。设置为false 时,地图将始终忽略prefers-reduced-motion 设置,无论用户的偏好如何,使所有动画都是必不可少的。
options.scrollZoom(boolean | Object)true如果为true,则启用"滚动缩放"交互。Object 值作为选项传递给 ScrollZoomHandler#enable
options.spriteFormat("raster" |"icon_set" |"auto")'auto'要使用的图像精灵的格式。如果设置为'auto',对于所有 mapbox 托管的精灵将使用矢量图标集,对于所有自定义 URL 将使用栅格精灵。
options.testModebooleanfalse静默由无效的 accessToken 生成的错误和警告,在编写单元测试时很有用。
options.touchPitch(boolean | Object)true如果为true,则启用"拖拽倾斜"交互。Object 值作为选项传递给 TouchPitchHandler
options.touchZoomRotate(boolean | Object)true如果为true,则启用"捏合旋转和缩放"交互。Object 值作为选项传递给 TouchZoomRotateHandler#enable
options.trackResizebooleantrue如果为true,当浏览器窗口调整大小时,地图将自动调整大小。
options.transformRequestRequestTransformFunctionnull在地图请求外部 URL 之前运行的回调。回调可用于修改 url、设置头信息或设置跨域请求的凭据属性。期望返回具有url 属性的 RequestParameters 对象,以及可选的headerscredentials 属性。
options.worldviewstringnull设置地图的世界视图。世界视图决定了某些有争议边界的渲染方式。默认情况下,GL JS 不会设置世界视图,因此 Mapbox 瓦片的世界视图将由矢量瓦片源的 TileJSON 确定。有效的世界视图字符串必须是 ISO alpha-2 国家代码。不支持的 ISO alpha-2 代码将回退到 TileJSON 的默认世界视图。无效代码将导致可恢复的错误。
options.keyboardbooleantrue如果为true,启用键盘快捷键(参见 KeyboardHandler)。
options.dragPanboolean | Objecttrue如果设置为true,则启用"拖动平移"交互。Object值作为选项传递给DragPanHandler#enable
options.zoomnumber0地图的初始 zoom 级别。如果在构造函数选项中未指定 zoom,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 0