首页 / deck.gl / API 文档
Viewport
先看结论
视口基类。把某个视图在屏幕上的位置、尺寸和投影状态封装起来， 并提供经纬度与像素坐标互转的方法。
new deck.Viewport({ id, x, y, width, height })
构造参数
| 参数 | 默认 | 说明 |
|---|---|---|
id | 'default-viewport' | 视口标识，多视图时用于区分 |
x | 0 | 左上角横坐标，像素 |
y | 0 | 左上角纵坐标，像素 |
width | 1 | 视口宽度，像素 |
height | 1 | 视口高度，像素 |
属性
| 属性 | 说明 |
|---|---|
id | 视口标识 |
x / y | 屏幕位置 |
width / height | 屏幕尺寸 |
方法
| 方法 | 返回 | 说明 |
|---|---|---|
project(xyz) | [x, y] | 经纬度转屏幕像素 |
unproject(xyz) | [lng, lat, z] | 屏幕像素转经纬度 |
projectFlat(lngLat) | [x, y] | 经纬度转投影平面坐标 |
unprojectFlat(xy) | [lng, lat] | 投影平面坐标转经纬度 |
containsPixel({x, y}) | Boolean | 像素是否落在视口内 |
getDistanceScales() | Object | 当前视口的米与像素换算比例 |
getProjectionMatrix() | Array | 投影矩阵，自定义渲染时使用 |
示例：屏幕坐标转经纬度
// 点击位置换算成地理坐标
deckgl.on('click', function (info) {
var viewport = deckgl.getViewports()[0];
var lngLat = viewport.unproject([info.x, info.y]);
console.log(lngLat);
});
// 反过来，把经纬度投影成像素，用于自定义 DOM 覆盖层
var viewport = deckgl.getViewports()[0];
var pixel = viewport.project([116.391, 39.907]);
overlay.style.left = pixel[0] + 'px';
overlay.style.top = pixel[1] + 'px';像素坐标的原点
视口的 x、y 是视口左上角在画布中的位置，
但 project 返回的像素坐标以画布左上角为原点。
多视图布局时，把 project 的结果减去视口偏移，
才能与视口内部的 DOM 元素对齐。
与 View 的区别
View 描述视角参数（经纬度、缩放、俯仰、方位角），
Viewport 是它在某一帧、某个画布尺寸下算出来的结果。
一个 View 在不同尺寸下会生成不同的 Viewport，
所以投影计算要以 Viewport 为准。
改动后要重新取视口。视口对象是某一帧的快照，窗口尺寸变化、
视图参数调整后旧对象已经过期。deckgl.getViewports()
每次调用都会返回当前帧的实例，不要在模块初始化时缓存。
经纬志（2026）。《Viewport》。https://www.jingweizhi.com/deckgl/api/viewport.html（访问日期 2026-11-03）。