地图
该对象代表您页面上的地图。它公开了一些方法和属性,使您能够以编程方式更改地图,并在用户与其交互时触发事件。Map
您可以通过指定 和其他选项来创建一个 Map。然后,Mapbox GL JS 会在页面上初始化地图并返回您的对象。MapcontainerMap
扩展了 Evented。
参数
选项 | 类型 | 默认值 | 描述 |
---|---|---|---|
options | Object | ||
options.accessToken | string | null | 如果指定,地图将使用这个 token 而不是 mapboxgl.accessToken 中定义的那个。 |
options.antialias | boolean | false | 如果设为 true ,gl 上下文将使用 MSAA antialiasing 创建。默认为 false 是出于性能优化的考虑。 |
options.attributionControl | boolean | true | 如果设为 true ,将添加 AttributionControl 到地图。 |
options.bearing | number | 0 | 地图的初始 bearing(旋转),以逆时针方向从北方度量。如果在构造函数选项中未指定 bearing ,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 0 。 |
options.bearingSnap | number | 7 | 阈值,以度为单位,用于确定地图的方位何时会对齐到正北方向。例如,bearingSnap 为 7 时,如果用户将地图旋转到距北方 7 度以内,地图将自动对齐到正北方向。 |
options.bounds | LngLatBoundsLike | null | 地图的初始边界。如果指定了 bounds ,它将覆盖 center 和 zoom 构造函数选项。 |
options.boxZoom | boolean | true | 如果设为 true ,将启用"框选缩放"交互(参见 BoxZoomHandler)。 |
options.center | LngLatLike | [0,0] | 地图的初始地理 中心点。如果在构造函数选项中未指定 center ,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 [0, 0] 。注意:Mapbox GL 使用经度、纬度坐标顺序(而不是纬度、经度)以匹配 GeoJSON。 |
options.clickTolerance | number | 3 | 用户在点击过程中可以移动鼠标指针的最大像素数,以使其被视为有效点击(而不是鼠标拖动)。 |
options.collectResourceTiming | boolean | false | 如果设为 true ,将收集 GeoJSON 和 Vector Tile web workers 发出的请求的资源计时 API 信息(这些信息通常无法从主 JavaScript 线程访问)。信息将在相关 data 事件的 resourceTiming 属性中返回。 |
options.config | Object | null | 样式片段的初始配置选项。对象中的每个键是片段 ID(例如 basemap ),每个值是配置对象。 |
options.container | HTMLElement | string | Mapbox GL JS 将在其中渲染地图的 HTML 元素,或该元素的字符串 id 。指定的元素必须没有子元素。 | |
options.cooperativeGestures | boolean? | 如果设为 true ,滚动缩放将需要按住 ctrl 或 ⌘ 键同时滚动才能缩放地图,触摸平移将需要使用两个手指才能移动地图。如果启用,触摸倾斜将需要三个手指才能激活。 | |
options.crossSourceCollisions | boolean | true | 如果设为 true ,在碰撞检测期间,来自多个源的符号可以相互碰撞。如果设为 false ,则对每个源的符号单独运行碰撞检测。 |
options.customAttribution | string | Array<string> | null | 在 AttributionControl 中显示的字符串或字符串数组。仅在 options.attributionControl 为 true 时适用。 |
options.doubleClickZoom | boolean | true | 如果设为 true ,将启用"双击缩放"交互(参见 DoubleClickZoomHandler)。 |
options.dragRotate | boolean | true | 如果设为 true ,将启用"拖动旋转"交互(参见 DragRotateHandler)。 |
options.fadeDuration | number | 300 | 控制标签碰撞的淡入/淡出动画持续时间,以毫秒为单位。此设置影响所有符号层。此设置不影响运行时样式转换或栅格瓦片交叉淡入淡出的持续时间。 |
options.failIfMajorPerformanceCaveat | boolean | false | 如果设为 true ,当 Mapbox GL JS 的性能将大幅低于预期(将使用软件渲染器)时,地图创建将会失败。 |
options.fitBoundsOptions | Object | null | 一个 Map#fitBounds 选项对象,仅用于适配上面提供的初始 bounds 。 |
options.hash | boolean | string | false | 如果设为 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.interactive | boolean | true | 如果设为 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.locale | Object | null | 对 UI 字符串的默认本地化表进行补丁的对象,例如控件提示。locale 对象将命名空间 UI 字符串 ID 映射到目标语言中的翻译字符串;有关所有支持的字符串 ID 的示例,请参见 src/ui/default_locale.js 。该对象可以指定所有 UI 字符串(从而添加对新翻译的支持)或仅一部分字符串(从而为默认翻译表打补丁)。 |
options.localFontFamily | string | null | 定义一个 CSS font-family,用于本地覆盖所有字形的生成。将忽略地图样式中的字体设置,但字体粗细关键字(light/regular/medium/bold)除外。如果设置,此选项将覆盖 localIdeographFontFamily 中的设置。 |
options.localIdeographFontFamily | string | 'sans-serif' | 定义一个 CSS font-family,用于本地覆盖"CJK 统一表意文字"、"平假名"、"片假名"、"朝鲜文音节"和"CJK 符号和标点符号"范围内的字形生成。在这些范围内,将忽略地图样式中的字体设置,但字体粗细关键字(light/regular/medium/bold)除外。设置为false ,以便为这些字形范围启用地图样式中的字体设置。请注意,Mapbox Studio 默认将此值设置为false 。此选项的目的是避免带宽密集型的字形服务器请求。有关此选项使用的示例,请参见使用本地生成的表意文字。 |
options.logoPosition | string | 'bottom-left' | 表示 Mapbox 文字标志在地图上位置的字符串。有效选项为top-left 、top-right 、bottom-left 、bottom-right 。 |
options.maxBounds | LngLatBoundsLike | null | 如果设置,地图将被限制在给定的边界内。 |
options.maxPitch | number | 85 | 地图的最大倾斜度(0-85)。 |
options.maxTileCacheSize | number | null | 为给定源存储在瓦片缓存中的最大瓦片数。如果省略,缓存将根据当前视口动态调整大小。 |
options.maxZoom | number | 22 | 地图的最大缩放级别(0-24)。 |
options.minPitch | number | 0 | 地图的最小倾斜度(0-85)。 |
options.minTileCacheSize | number | null | 为给定源存储在瓦片缓存中的最小瓦片数。较大的视口使用更多的瓦片并需要更大的缓存。较大的视口更可能出现在内存更多的设备上以及地图更重要的页面上。如果省略,缓存将根据当前视口动态调整大小。 |
options.minZoom | number | 0 | 地图的最小缩放级别(0-24)。 |
options.performanceMetricsCollection | boolean | true | 如果为true ,mapbox-gl 将收集并发送性能指标。 |
options.pitch | number | 0 | 地图的初始倾斜度(倾斜),以远离屏幕平面的度数测量(0-85)。如果在构造函数选项中未指定pitch ,Mapbox GL JS 将在地图的样式对象中查找它。如果在样式中也未指定,则默认为0 。 |
options.pitchRotateKey | ("Control" |"Alt" |"Shift" |"Meta") | 'Control' | 允许将用于倾斜/旋转交互的键盘修饰键从Control 更改为另一个修饰键。 |
options.pitchWithRotate | boolean | true | 如果为false ,则将禁用具有"拖拽旋转"交互的地图倾斜(倾斜)控制。 |
options.preserveDrawingBuffer | boolean | false | 如果为true ,则可以使用map.getCanvas().toDataURL() 将地图的画布导出为 PNG。默认情况下,这是false ,以作为性能优化。 |
options.projection | ProjectionSpecification | 'mercator' | 地图应该渲染的投影。支持的投影有:
|
options.refreshExpiredTiles | boolean | true | 如果为false ,一旦瓦片根据其 HTTPcacheControl /expires 头过期,地图将不会尝试重新请求它们。 |
options.renderWorldCopies | boolean | true | 如果为true ,超过 -180 和 180 度经度将并排渲染多个世界副本。如果设置为false :
|
options.respectPrefersReducedMotion | boolean | true | 如果设置为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.testMode | boolean | false | 静默由无效的 accessToken 生成的错误和警告,在编写单元测试时很有用。 |
options.touchPitch | (boolean | Object) | true | 如果为true ,则启用"拖拽倾斜"交互。Object 值作为选项传递给 TouchPitchHandler。 |
options.touchZoomRotate | (boolean | Object) | true | 如果为true ,则启用"捏合旋转和缩放"交互。Object 值作为选项传递给 TouchZoomRotateHandler#enable。 |
options.trackResize | boolean | true | 如果为true ,当浏览器窗口调整大小时,地图将自动调整大小。 |
options.transformRequest | RequestTransformFunction | null | 在地图请求外部 URL 之前运行的回调。回调可用于修改 url、设置头信息或设置跨域请求的凭据属性。期望返回具有url 属性的 RequestParameters 对象,以及可选的headers 和credentials 属性。 |
options.worldview | string | null | 设置地图的世界视图。世界视图决定了某些有争议边界的渲染方式。默认情况下,GL JS 不会设置世界视图,因此 Mapbox 瓦片的世界视图将由矢量瓦片源的 TileJSON 确定。有效的世界视图字符串必须是 ISO alpha-2 国家代码。不支持的 ISO alpha-2 代码将回退到 TileJSON 的默认世界视图。无效代码将导致可恢复的错误。 |
options.keyboard | boolean | true | 如果为true ,启用键盘快捷键(参见 KeyboardHandler)。 |
options.dragPan | boolean | Object | true | 如果设置为true ,则启用"拖动平移"交互。Object 值作为选项传递给DragPanHandler#enable。 |
options.zoom | number | 0 | 地图的初始 zoom 级别。如果在构造函数选项中未指定 zoom ,Mapbox GL JS 将在地图样式对象中查找它。如果在样式中也未指定,则默认为 0 。 |