SmartMapX JS
SmartMapX JS是一个使用WEBGL技术渲染地图的高性能JavaScript地图开发SDK。
Map
Map
对象代表页面上的地图,包含操作地图的一些相关的方法和属性,你能以程序方式修改地图,并在用户与之交互时触发事件。
你可以
指定一个div容器
和其它选项,然后通过Smartmapx JS API初始化页面上的地图并返回你的Map对象。
Extends Evented.
(Object)
Name | Description |
options.container(HTMLElement | string) | smartmapx GL js将呈现地图的HTML元素或元素的字符串
id,
指定的元素必须没有子项。
|
options.minZoomnumber (default 0 ) | 地图的最小缩放级别(0-22)。 |
options.maxZoomnumber (default 22 ) | 地图的最大缩放级别(0-22)。 |
options.style(Object | string)? | 地图的smartmapx样式。这必须是符合smartmapx样式规范中描述的JSON对象模式,
或者返回该JSON对象的URL。
|
options.hashboolean (default false ) | 当为
true时
,地图的位置(缩放,中心纬度,中心经度,方位和坡度)将与页面URL的哈希段同步。例如,
http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60
。
|
options.interactiveboolean (default true ) | 当为
false时
则没有鼠标,触摸或键盘监听器将被连接到地图上,因此它不会响应交互。
|
options.bearingSnapnumber (default 7 ) | 以度为单位的度量来确定地图的方位(旋转)何时会向北滑动。例如,
bearingsnap
7,如果用户在北方7度的范围内旋转地图,则地图将被自动旋转到正北方向。
|
options.pitchWithRotateboolean (default true ) | 当为
false时,
该地图的俯仰(倾斜)控制与拖动旋转的互动将被禁用。
|
options.attributionControlboolean (default true ) | 当为
true时,
AttributionControl
将被添加到地图上。
|
options.logoPositionstring (default 'bottom-left' ) | 表示smartmapx字标在地图上位置的字符串。有效的选项为
top-left
,
top-right
,
bottom-left
,
bottom-right
。
|
options.failIfMajorPerformanceCaveatboolean (default false ) | 当为
true时,
smartmapx地图创建GL JS的表现会比预期结果差(即软件渲染器将使用),地图会创建失败。
|
options.preserveDrawingBufferboolean (default false ) | 当为
true时,
映射的画布可以导出到PNG中使用。
map.getCanvas().toDataURL()
。当为
false时
为默认性能优化。
|
options.refreshExpiredTilesboolean (default true ) | 当为
false时,
地图不会试图在每次HTTP到期时重新请求瓦片。
|
options.maxBoundsLngLatBoundsLike? | 如果设置,地图将被限制到给定的边界。 |
options.scrollZoom(boolean | Object) (default true ) | 当为
true时,
启用了“滚动缩放”交互功能。一个
Object
值作为选项传递给
ScrollZoomHandler#enable
。
|
options.boxZoomboolean (default true ) | 当为
true时,
启用了“box zoom”交互功能(请参阅
BoxZoomHandler
)。
|
options.dragRotateboolean (default true ) | 当为
true时,
启用了“拖动-旋转”交互功能(请参阅
DragRotateHandler
)。
|
options.dragPanboolean (default true ) | 当为
true时,
启用了“拖动移动”交互功能(请参阅
DragPanHanller
)。
|
options.keyboardboolean (default true ) | 当为
true时,
启用了“键盘快捷键”交互功能(请参阅
KeyboardHandler
)。
|
options.doubleClickZoomboolean (default true ) | 当为
true时,
启用了“双击缩放”交互功能(请参阅
DoubleClickZoomHandler
)。
|
options.touchZoomRotate(boolean | Object) (default true ) | 当为
true时,
启用了“捏转和缩放”交互功能。一个
Object
值作为选项传递给
TouchZoomRotateHandler#enable
。
|
options.trackResizeboolean (default true ) | 当为
true时,
当浏览器窗口调整大小时,地图会自动调整大小。
|
options.centerLngLatLike (default [0,0] ) | 地图的初始地理中心点。如果
中心点不是在构造函数中指定的选项,则smartmapx GL JS会在地图的样式对象寻找它。如果样式中没有指定,则默认为
[ 0, 0 ]。
注:smartmapx GL使用经度、纬度坐标顺序(而不是纬度,经度)来匹配GeoJSON。
|
options.zoomnumber (default 0 ) | 地图的初始缩放级别。如果
zoom
未在构造函数选项中指定,则smartmapx GL JS将会在地图的样式对象寻找它。如果样式中没有指定,则默认为
0
。
|
options.bearingnumber (default 0 ) | 地图的初始方位(旋转),从正北向逆时针测量。如果
bearing
未在构造函数选项中指定,则smartmapx GL JS将会在地图的样式对象中寻找它,如果样式中没有指定,则默认为
0
。
|
options.pitchnumber (default 0 ) | 初始俯仰(倾斜)的地图,衡量度远离屏幕平面(0-60)。如果
pitch
是不是在构造函数中指定的选项,smartmapx GL JS会在地图的样式对象寻找它。如果样式中没有指定,则默认为
0
。
|
options.renderWorldCopiesboolean (default true ) | 当为
true时,
放大时将绘制world多个副本。
|
options.maxTileCacheSizenumber (default null ) | 存储在tile中给定源的最大高速缓存。如果省略,缓存将根据当前视口动态调整大小。 |
options.localIdeographFontFamilystring (default null ) | 如果指定,则定义一个CSS字体系列,用于在“CJK统一表意文字”和“韩语音节”范围内本地覆盖字形的生成。在这些范围内,除了字体权重关键字(light / regular / medium / bold)外,地图样式中的字体设置将被忽略。此选项的目的是避免带宽密集型字形服务器请求。(请参阅 使用本地生成的文字库 ) |
options.transformRequestRequestTransformFunction (default null ) | 在Map请求外部URL之前执行回调。该回调可用于修改url,设置标题或设置跨源请求的凭证属性。预计用返回一个对象
URL
属性和任选
headers
和
credentials
性能。
|
var map = new smartmapx.Map({
container: 'map',
center: [116.39738, 39.90579],
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
}
}
}
});
accessToken
获取并设置地图的访问令牌。
smartmapx.accesstoken = myaccesstoken;
supported
测试浏览器是否支持Smartmapx GL JS。
smartmapx.supported();
version
Smartmapx JS的版本号。
setRTLTextPlugin
设置地图的RTL文本插件。支持从右到左书写的语言,像阿拉伯语和希伯来语等。
smartmapx.setRTLTextPlugin('https://api.smartmapx.com/smartmapx-js/plugins/mapbox-gl-rtl-text/v0.1.1/mapbox-gl-rtl-text.js');
AnimationOptions
选择常见的涉及到动画的运动方法,比如Map#panBy和Map#easeTo控制动画的持续时间和缓动功能。所有属性都是可选的。
CameraOptions
Map#jumpTo,,Map#easeTo,和Map#flyTo共同的属性。用于控制摄像机的所需位置,缩放,方位和俯仰。所有属性都是可选的,当省略属性时,该属性的当前摄像机值将保持不变。
PaddingOptions
RequestParameters
一个RequestParameters
从Map.options.transformRequest回调中返回的对象。
lnglat
和lnglatbounds
矩形。Point
表示屏幕坐标中的点。
LngLat
一个lnglat
对象表示给定的经度和纬度坐标,单位为度。
smartmapx GL使用经度、纬度坐标(而不是纬度、经度)来匹配GeoJSON。
请注意,任何smartmapx GL方法接受lnglat
对象作为参数或选项,也可以接受两个数字的Array
,并执行隐式转换。这种灵活的类型被记录为lnglatlike。
var ll = new smartmapx.LngLat(116.39738, 39.90579);
LngLatLike
一个lnglat对象,表示经度和纬度的两个数字的数组,或带有lng
和lat
属性的对象。
var v1 = new smartmapx.LngLat(116.39738, 39.90579);
var v2 = [116.39738, 39.90579];
LngLatBounds
一个lnglatbounds
对象,表示地理边界,由经度和纬度的西南和东北点定义。
如果没有向构造函数提供参数,则创建一个null
边界框。
请注意,任何smartmapx GL方法接受lnglatbounds
对象作为参数或选项,也可以接受Array
两个lnglatlike构造,并将执行隐式转换。这种灵活的类型被记录为lnglatboundslike。
var sw = new smartmapx.LngLat(116.268087, 40.037287);
var ne = new smartmapx.LngLat(116.301213, 40.056536);
var llb = new smartmapx.LngLatBounds(sw, ne);
LngLatBoundsLike
一个lnglatbounds对象,一个[sw,ne]顺序的lnglatlike对象数组[sw, ne]或者[west, south, east, north]顺序的数组的数组。
var v1 = new smartmapx.LngLatBounds(
new smartmapx.LngLat(116.268087, 40.037287),
new smartmapx.LngLat(116.301213, 40.056536)
);
var v2 = new smartmapx.LngLatBounds([116.268087, 40.037287], [116.301213, 40.056536])
var v3 = [[116.268087, 40.037287], [116.301213, 40.056536]];
Point
一个Point
geometry对象,它具有x
和y
表示屏幕坐标的像素的属性。
PointLike
一个Point或一个由两个数字组成的数组,分别代表像素的x
和Y
屏幕坐标。
控制,标记,和弹出添加新的用户界面元素的地图。
IControl
添加到地图上的交互式控件的接口。这是实现模型的规范:它不是一个出口的方法或类。
控件必须实现onAdd
和onremove
并且必须拥有一个元素,它通常是DIV
元。使用smartmapx GL JS的默认控件样式,添加smartmapx Ctrl
类到控件的节点。
// Control implemented as ES6 class
class HelloWorldControl {
onAdd(map) {
this._map = map;
this._container = document.createElement('div');
this._container.className = 'smartmapx-ctrl';
this._container.textContent = 'Hello, world';
return this._container;
}
onRemove() {
this._container.parentNode.removeChild(this._container);
this._map = undefined;
}
}
// Control implemented as ES5 prototypical class
function HelloWorldControl() { }
HelloWorldControl.prototype.onAdd = function(map) {
this._map = map;
this._container = document.createElement('div');
this._container.className = 'smartmapx-ctrl';
this._container.textContent = 'Hello, world';
return this._container;
};
HelloWorldControl.prototype.onRemove = function () {
this._container.parentNode.removeChild(this._container);
this._map = undefined;
};
NavigationControl
一个NavigationControl
控件包含缩放按钮和指南针。
var nav = new smartmapx.NavigationControl();
map.addControl(nav, 'top-left');
GeolocateControl
一个geolocatecontrol
控制提供了一个按钮,使用浏览器的地理定位API在地图上找到用户。
不是所有的浏览器支持地理定位,一些用户可能会禁用该功能。对包括Chrome在内的现代浏览器的地理定位支持需要通过HTTPS提供站点。如果地理定位支持不可用,GeolocateControl将不可见。
应用缩放级别将取决于由该设备提供的地理定位精度。
有两种模式的geolocatecontrol。如果trackuserlocation
是false
(默认)控件充当按钮,按下时按钮将设置映射的摄像机以定位用户位置。如果用户移动,地图将不会更新。这是最适合桌面的。如果trackuserlocation
是true
控件充当切换按钮,当活跃用户的位置被积极监视更改时。在这种模式geolocatecontrol有三种状态:
- 活动-地图的相机会随着用户位置的变化而自动更新,并将位置点保持在中心位置。
- 被动-用户的位置点自动更新,但地图的相机没有更新。
- 禁用
Extends Evented.
(Object?)
Name | Description |
options.positionOptionsObject (default {enableHighAccuracy:false,timeout:6000} ) | 一个 Geolocation API PositionOptions 对象。 |
options.fitBoundsOptionsObject (default {maxZoom:15} ) |
fitbounds
当地图被平移并放大到用户位置时使用的选项对象。默认是使用
maxzoom
15来限制地图在非常精确的位置放大多远。
|
options.trackUserLocationObject (default false ) | 如果
true
的定位控制成为一个切换按钮,当活跃的地图将获得用户的位置更新,它的变化。
|
options.showUserLocationObject (default true ) | 默认情况下,将在用户位置上的地图上显示一个点。设置
false
禁用。
|
map.addControl(new smartmapx.GeolocateControl({
positionOptions: {
enableHighAccuracy: true
},
trackUserLocation: true
}));
AttributionControl
一个attributioncontrol
控件显示地图的attribution information。
var map = new smartmapx.Map({attributionControl: false})
.addControl(new smartmapx.AttributionControl({
compact: true
}));
ScaleControl
一个scalecontrol
控件显示地图上的距离与地面上相应的距离之比。
map.addControl(new smartmapx.ScaleControl({
maxWidth: 80,
unit: 'imperial'
}));
FullscreenControl
一个fullscreencontrol
控件包含一个切换地图和退出全屏模式按钮。
map.addControl(new smartmapx.FullscreenControl());
MeasureControl
测距插件
Name | Description |
options.linestringObject (default {} ) | 空的GeoJSON线对象 |
options.circleRadiusNumber (default 3.5 ) | 线连接点圆的半径 |
options.circleColorstring (default '#fff' ) | 线连接点圆的颜色 |
options.lineColorstring (default '#44bff0' ) | 线的颜色 |
options.lineWidthNumber (default 3 ) | 线的宽度 |
options.lineCapstring (default 'round' ) | 线结束的类型 |
options.lineJoinstring (default 'round' ) | 线连接的类型 |
Popup
弹出组件。
Extends Evented.
(Object?)
Name | Description |
options.closeButtonboolean (default true ) | 如果
true
在弹出窗口的右上角显示一个关闭按钮。
|
options.closeOnClickboolean (default true ) | 如果
true
当单击地图时弹出窗口将关闭。
|
options.anchorstring? | 一个字符串,指示弹出窗口相对于popup在地图指定点的位置。
Popup#setLngLat
。选项
'top'
,
'bottom'
,
'left'
,
'right'
,
'top-left'
,
'top-right'
,
'bottom-left
, and
'bottom-right'
。如果未设置将动态设置确保popup弹出框落在map窗口的可视区域内
'bottom'
。
|
options.offset(number | PointLike | Object)? | 应用于弹出位置的像素偏移量,指定为: |
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 smartmapx.Popup({offset:popupOffsets})
.setLngLat(e.lngLat)
.setHTML("<h1>Hello World!</h1>")
.addTo(map);
Marker
创建标记组件
var marker = new smartmapx.Marker()
.setLngLat([30.5, 50.5])
.addTo(map);
处理程序为地图-鼠标交互、触摸交互和其他手势添加不同类型的交互。
BoxZoomHandler
BoxZoomHandler
允许用户缩放地图以适应矩形边界框。边界框通过单击时按住shift
同时拖拽鼠标来定义。
ScrollZoomHandler
ScrollZoomHandler
允许用户通过滚动缩放地图。
DragPanHandler
DragPanHandler
允许用户通过单击和拖动光标来平移地图。
DragRotateHandler
DragRotateHandler
允许用户在按住鼠标右键同时拖动光标旋转地图,或按住ctrl
键同时拖动光标旋转地图。
KeyboardHandler
KeyboardHandler
允许用户使用下列快捷键缩放、旋转和平移地图:
=
/+
:将缩放级别提高1。Shift-=
/Shift-+
:将缩放级别提高2。—
:将缩放级别减少1。Shift--
:将缩放级别减少2。- 箭头键:平移100像素。
Shift +⇢
增加旋转15度。Shift +⇠
减少旋转15度。Shift +⇡
把pitch提高10度。Shift +⇣
把pitch降低10度。
DoubleClickZoomHandler
这个DoubleClickZoomHandler
允许用户双击一个点缩放地图。
TouchZoomRotateHandler
这个TouchZoomRotateHandler
允许用户通过在触摸屏上捏地图来缩放和旋转地图。
源指定要在地图上呈现的地理特征。源对象可以从Map#getSource
。
GeoJSONSource
包含GeoJSON的数据源。(见地图样式规范有关选项的详细文档。)
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 ]
}
}]
});
VideoSource
包含视频的数据源。(见地图样式规范有关选项的详细文档。)
// 添加数据
map.addSource('some id', {
type: 'video',
url: [
'http://www.smartmapx.com/blog/assets/baltimore-smoke.mp4',
'http://www.smartmapx.com/blog/assets/baltimore-smoke.webm'
],
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
ImageSource
包含图像的数据源。(见地图样式规范有关选项的详细文档。)
// add to map
map.addSource('some id', {
type: 'image',
url: 'http://www.smartmapx.com/images/foo.png',
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
CanvasSource
包含HTML画布内容的数据源。(见地图样式规范有关选项的详细文档。)
// 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
事件
是Smartmapx js的事件系统。它有时在执行时被扩展。icontrols和其他扩展。
Evented
SmartMapX各个类中用到的事件类。
MapMouseEvent
(MouseEvent)
MapTouchEvent
MapBoxZoomEvent
(MouseEvent)
MapDataEvent
mapdataevent
对象被Map.event:data和Map.event:dataloading事件提供。dataType
可能的值为:
'source'
:与数据源相关联的非tile数据'style'
:地图使用的地图样式
(Coordinate?)
: 瓦片的地理坐标,如果事件的
dataType
为
source
,加载瓦片数据时才包含该属性。