首页 / MapLibre / API 文档

FullscreenControl

先看结论

一个按钮，把地图（或指定容器）铺满屏幕，退出时恢复原布局并触发地图重算尺寸。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文

map.addControl(new maplibregl.FullscreenControl({ container: document.body }), 'top-right')

参数

字段	默认	说明
`container`	地图容器	进入全屏的元素，必须是 HTMLElement
`pseudo`	false	为 true 时不调用浏览器全屏 API，改用 CSS 铺满视口

默认位置是右上角，图标随状态切换为「进入」与「退出」。浏览器不支持 requestFullscreen 时会走 CSS 方案， iframe 内嵌页面通常属于这种情况，pseudo 用来显式选择这条路。

成员与事件

成员	说明
`onAdd(map)`	创建按钮并绑定点击
`onRemove(map)`	解绑监听，移除按钮
`getDefaultPosition()`	返回 `'top-right'`
`fullscreenstart` 事件	进入全屏后触发
`fullscreenend` 事件	退出全屏后触发

示例

var fs = new maplibregl.FullscreenControl({
  container: document.querySelector('.map-shell')
});

map.addControl(fs, 'top-right');

map.on('fullscreenstart', function () {
  console.log('进入全屏');
});

map.on('fullscreenend', function () {
  /* 全屏期间容器尺寸变了，退出后重算一次 */
  map.resize();
});

注意事项

全屏元素是地图容器时，容器里的侧栏、图例一起被放大，布局按比例拉伸。只想放大地图本身，就把 container 指向包住地图画布的那层元素，而不是整个页面。

全屏切换后容器尺寸改变，MapLibre 会自行监听 resize，但在 iframe、弹窗等场景里可能收不到事件，退出全屏时手动 map.resize() 一次最稳。

与手势冲突。全屏期间控件的 cooperativeGestures 会被临时关闭，退出后恢复；如果页面自己改过这项配置，全屏进出后要重新确认状态。

引用本文

经纬志（2026）。《FullscreenControl》。https://www.jingweizhi.com/maplibre/api/fullscreen-control.html（访问日期 2026-11-03）。