Mapbox相机动画整理（2）API整理

API 整理

Geography 和 geometry

LngLatLike（经纬度坐标）

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

PointLike（像素坐标）

var p1 = new mapboxgl.Point(-77, 38); // a PointLike which is a Point
var p2 = [-77, 38]; // a PointLike which is an array of two numbers

MercatorCoordinate（墨卡托坐标）

MercatorCoordinate是一种3D投影坐标。
MercatorCoordinate使用web墨卡托投影(EPSG:3857)，其单位略有不同:

• 投影世界的最大宽度为1个单位。
• 坐标轴的原点在西北角而不是中间。

例如，MercatorCoordinate(0,0,0)是mercator世界的西北角，而MercatorCoordinate(1,1,0)是东南角。
MercatorCoordinate的z维是垂直于平面的。在墨卡托坐标空间中的立方体将被渲染为立方体。

new MercatorCoordinate(x: number, y: number, z: number)

静态方法：

fromLngLat(lngLatLike: LngLatLike, altitude: number)

将经纬度坐标转换成3D墨卡托投影坐标

var coord = mapboxgl.MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
coord; // MercatorCoordinate(0.5, 0.5, 0)

实例方法：

meterInMercatorCoordinateUnits(): number

返回在这个纬度下，以墨卡托坐标单位表示的1米的距离。

var coord = new mapboxgl.MercatorCoordinate(0, 1, 0.02);
coord.meterInMercatorCoordinateUnits(); // 2.895799898894401e-7

toAltitude(): number

将该墨卡托坐标转换为对应的海拔高度，单位为米。

var coord = new mapboxgl.MercatorCoordinate(0, 0, 0.02);
coord.toAltitude(); // 6914.281956295339

toLngLat(): LngLat

将该墨卡托坐标转换为经纬度坐标。

var coord = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
var lngLat = coord.toLngLat(); // LngLat(0, 0)

Properties 和 Options

PaddingOptions内边距属性

可以统一设置各边的内边距，也可以分别设置各边的内边距。所有的属性必须是非负整数。

var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});
var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
  padding: 20
});

AnimationOptions动画属性

• duration(number): 动画的持续时间，单位为毫秒（ms）；
• easing(Function): 可以返回一个0到1之间的数字的方法，其中0是初始状态，1是最终状态；
• offset(PointLike): 在动画结束时，目标中心相对于真实地图容器中心的偏移量，单位是像素值；
• animate(boolean): 如果为false，将没有动画发生；
• essential(boolean): 如果为真，则认为动画是必要的，不会受到preferred-reduced-motion的影响。

CameraOptions相机属性

• center(LngLatLike): 中心点
• zoom(number): 缩放层级
• bearing(number): 方位角，正北方向为0度
• pitch(number): 竖直方向的倾斜角，范围在0 - 60度之间，竖直方向为0度
• around(LngLatLike): 如果指定了zoom，则around确定缩放的居中点
• padding(PaddingOptions): 用于移动消失点的视口两侧的像素尺寸。

FreeCameraOptions自由相机属性

用于访问底层摄像机实体的物理属性的选项。直接访问这些属性允许更灵活和精确的控制相机，同时也完全兼容CameraOptions。所有字段都是可选的。

new FreeCameraOptions(position: MercatorCoordinate, orientation: quat)

position(MercatorCoordinate)

实例方法

lookAtPoint(location, up)

通过在地图上定义一个焦点来设置相机方向的辅助函数。
location(LngLatLike)

setPitchBearing(pitch, bearing)

设置相机方向为倾斜角和方位角的辅助函数。
pitch(number)
bearing(number)

Map

easeTo(options, eventData?)

缓慢移动到某处
options可以使用CameraOptions和AnimationOptions的属性；

fitBounds(bounds, options?, eventData?)

缩放地图到对应的地理边界范围内
bounds矩形边界范围，表示方式可以是[sw, ne]，也可以是[west, south, east, north]

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]];
var v4 = [-73.9876, 40.7661, -73.9397, 40.8002];

options可以使用CameraOptions和AnimationOptions的属性；
其它属性：

属性名称	描述
options.linear: boolean 默认为false	如果为真，地图切换的过渡类似于使用了 Map#easeTo 方法；如果为否，类似于使用了 Map#flyTo 方法；
options.maxZoom: number	当地图缩放时，允许的最大缩放层级

var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});

flyTo(options, eventData?)

移动到某处。动画无缝地结合了缩放和平移，帮助用户在穿越很远的距离后仍然保持自己的方向。
options可以使用CameraOptions和AnimationOptions的属性；
其它属性：
options.speed(number)：速度
options.maxDuration(number)：最大持续时间，单位为毫秒（ms）

// 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;
  }
});

jumpTo(options, eventData?)

跳跃到某处。没有动画过渡。
options可以使用CameraOptions的属性；（注意，没有AnimationOptions属性）

// jump to coordinates at current zoom
map.jumpTo({center: [0, 0]});
// jump with zoom, pitch, and bearing options
map.jumpTo({
  center: [0, 0],
  zoom: 8,
  pitch: 45,
  bearing: 90
});

panBy(offset, options?, eventData?)

地图平移
offset(PointLike)地图在x轴和y轴平移的距离。
options(AnimationOptions?)

var deltaDistance = 100;
// up
map.panBy([0, -deltaDistance], {
	easing: easing
});
// down
map.panBy([0, deltaDistance], {
	easing: easing
});

panTo(lnglat, options?, eventData?)

地图漫游
lnglat(LngLatLike)地图漫游到某处。
options(AnimationOptions?)

// Specify that the panTo animation should last 5000 milliseconds.
map.panTo([-74, 38], {duration: 5000});

rotateTo(bearing, options?, eventData?)

地图旋转，伴有过渡动画
bearing(number)方位角
options(AnimationOptions?)

map.rotateTo(65);

getBearing()

获取地图方位角

setBearing(bearing, eventData?)

设置地图方位角
bearing(number)方位角

// rotate the map to 90 degrees
map.setBearing(90);

getCenter()

获取地图中心点

setCenter(center)

设置地图中心点

map.setCenter([-74, 38]);

getFreeCameraOptions()

获取相机的位置和朝向

setFreeCameraOptions(options, eventData)

设置相机的位置和朝向
options(FreeCameraOptions)

var camera = map.getFreeCameraOptions();
var cameraAltitude = 4000;

// set the position and altitude of the camera
camera.position = mapboxgl.MercatorCoordinate.fromLngLat(
	{
		lng: alongCamera[0],
		lat: alongCamera[1]
	},
	cameraAltitude
);
 
// tell the camera to look at a point along the route
camera.lookAtPoint({
	lng: alongRoute[0],
	lat: alongRoute[1]
});
 
map.setFreeCameraOptions(camera);

getZoom()

获取地图缩放层级

setZoom(zoom, eventData?)

设置地图缩放层级

map.setZoom(5);

zoomIn(options?, eventData?)

放大一级
options(AnimationOptions?)

// zoom the map in one level with a custom animation duration
map.zoomIn({duration: 1000});

zoomOut(options?, eventData?)

缩小一级
options(AnimationOptions?)

// zoom the map out one level with a custom animation offset
map.zoomOut({offset: [80, 60]});

zoomTo(zoom, options?, eventData?)

缩放到某个层级
zoom(number)
options(AnimationOptions?)

// Zoom to the zoom level 5 without an animated transition
map.zoomTo(5);
// Zoom to the zoom level 8 with an animated transition
map.zoomTo(8, {
  duration: 2000,
  offset: [100, 50]
});