经纬志
首页 / MapLibre / API 文档

flyTo

先看结论

带缩放的平滑飞行:先拉远、平移、再拉近,适合跨城市或跨层级的视角跳转。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-29 · 引用本文
map.flyTo(options) → this

参数

参数默认说明
center不变目标中心,[lng, lat] 或 LngLat
zoom不变目标缩放级别
bearing不变目标方位角,正北为 0
pitch不变目标倾斜角,0–60
padding0视口内边距,用于避开侧边面板
offset[0, 0]中心点偏移,单位像素
speed1.2飞行速度,越大越快
curve1.42缩放曲线的弯曲程度,越大越晚拉近
easing内置曲线缓动函数或预设名
essentialfalse为真时忽略系统的「减少动态效果」偏好

flyTo 不接受 duration,时长由距离、speed 与 curve 共同决定。 需要固定时长时用 easeTo。

基本用法

map.flyTo({
  center: [116.391263, 39.907359],
  zoom: 13,
  bearing: 0,
  pitch: 0
});

给侧边面板留位置

/* 左侧面板宽 320 像素,把目标点推到剩余区域中心 */
map.flyTo({
  center: [121.4737, 31.2304],
  zoom: 14,
  padding: { left: 320, right: 0, top: 0, bottom: 0 }
});

padding 参与视野计算,目标点不会简单偏移半个面板宽度, 而是按可用区域重新取中心,缩放到合适级别。

与 fitBounds 的关系

需要「把一组要素全部装进视野」时,fitBounds 更省事; 需要同时控制方位角、倾斜角与观看节奏时,用 flyTo 自己算中心与级别。

打断飞行

飞行过程中用户拖动地图会中断动画,地图停在当前状态。 代码里连续触发两次 flyTo,后一次从当前帧位置继续, 不会先跳回起点。

减少动态效果

系统开启「减少动态效果」时,flyTo 默认退化为直接跳转。 产品需要保留飞行动画时显式传 essential: true; 无障碍场景反过来,保持默认更合适。

跨大洲飞行会很慢。 speed 与距离共同决定时长,几千公里的跳转可能持续数秒。 要么提高 speed,要么先用 jumpTo 到附近级别再飞。 另外 curve 过小会让缩放过早完成,看起来像先跳后平移。

引用本文

经纬志(2026)。《flyTo》。https://www.jingweizhi.com/maplibre/api/fly-to.html(访问日期 2026-11-03)。