以下教程将系统地介绍 AntV L7 的核心 Scene 类用法，涵盖实例化、地图配置、视图操作、图层管理、事件监听及资源销毁等常用 API，并为每个方法给出完整示例代码。所有示例均基于官方 API 文档 ([l7.antv.antgroup.com][1])。
一、安装与引入
# 安装 L7 主包
npm install @antv/l7 --save
# 或者使用 yarn
yarn add @antv/l7
// 在项目入口处引入
import { Scene } from '@antv/l7';
import { AMap } from '@antv/l7-maps'; // 如果使用高德地图
二、实例化 Scene
2.1 构造函数
new Scene(options: SceneOptions)
-
options
id：必选，容器的 DOM 元素 id 或 HTMLElementmap：必选，地图引擎实例（new AMap(...)、new Mapbox(...)等）logoPosition：可选，地图 logo 显示位置zoom：可选，初始缩放级别pitch：可选，初始俯仰角度rotation：可选，初始旋转角度mapStyle：可选，自定义底图样式doubleClickZoom、minZoom、maxZoom等其他地图项
2.2 示例
// 1. 高德地图实例
const amap = new AMap({center: [120.2, 30.3],zoom: 5,
});// 2. 构造 L7 Scene
const scene = new Scene({id: 'map', // 页面中 <div id="map"></div>map: amap, // 地图库实例logoPosition: 'bottomleft',zoom: 4,pitch: 45,rotation: 0,doubleClickZoom: false,minZoom: 2,maxZoom: 18,
});
([l7.antv.antgroup.com][1])
三、初始化与渲染
3.1 scene.on('loaded', callback)
- 作用：地图加载完成后触发，可在回调中添加图层。
scene.on('loaded', () => {console.log('地图与 WebGL 上下文已就绪');
});
3.2 scene.render()
- 作用：手动触发重绘（大多数情况下无需显式调用，L7 会自动在数据或参数变动后重绘）。
scene.render();
([l7.antv.antgroup.com][1])
四、地图视图操作
| 方法 | 说明 |
|---|---|
scene.setCenter(lngLat) | 设置地图中心点 |
scene.setZoom(zoom) | 设置地图缩放级别 |
scene.setPitch(pitch) | 设置地图俯仰角度 |
scene.setRotation(r) | 设置地图旋转角度 |
scene.fitBounds(bounds, padding?) | 将视图自适应到指定边界并添加内边距 |
4.1 示例
// 移动到北京
scene.setCenter([116.4, 39.9]);
// 缩放到 8 级
scene.setZoom(8);
// 改为俯视角 60°
scene.setPitch(60);
// 顺时针旋转 30°
scene.setRotation(30);
// 让视图自适应两个经纬度点的包围盒
scene.fitBounds([[116,39],[117,40]], { padding: [20, 20] });
([l7.antv.antgroup.com][1])
五、图层管理
5.1 scene.addLayer(layer)
- 作用：向场景中添加一个图层实例（如
new PointLayer()、new PolygonLayer()等）。
import { PointLayer } from '@antv/l7';const pointLayer = new PointLayer().source([{ lng: 120, lat: 30, value: 10 },{ lng: 121, lat: 31, value: 20 },]).size('value', [5, 20]).shape('circle').color('value', ['#f00', '#0f0']);scene.addLayer(pointLayer);
5.2 scene.removeLayer(layerOrId)
- 作用：移除指定图层。
scene.removeLayer(pointLayer); // 或者通过图层 id
scene.removeLayer('my-layer-id');
5.3 scene.getLayer(id)
- 作用：根据 id 获取已添加的图层实例。
const ly = scene.getLayer('my-layer-id');
console.log('该图层的所有数据：', ly.getSource().data);
([l7.antv.antgroup.com][1])
六、导出与销毁
6.1 scene.exportPng(callback)
- 作用：将当前画布导出为 PNG 图像。
scene.exportPng((base64) => {console.log('PNG Base64 数据：', base64);
});
6.2 scene.destroy()
- 作用：销毁场景，释放 WebGL 资源并移除所有事件监听。
scene.destroy();
([l7.antv.antgroup.com][1])
七、事件监听
L7 Scene 支持下列常用鼠标及地图交互事件：
| 事件名 | 说明 |
|---|---|
click | 点击地图空白 |
mousemove | 鼠标移动 |
mousedown | 鼠标按下 |
mouseup | 鼠标抬起 |
wheel | 鼠标滚轮 |
zoomstart/zoomend | 缩放开始/结束 |
movestart/moveend | 平移开始/结束 |
示例
scene.on('click', (e) => {console.log('地图点击事件，坐标：', e.lngLat);
});scene.on('zoomend', () => {console.log('地图缩放完成，当前级别：', scene.getZoom());
});
([l7.antv.antgroup.com][1])
八、小结
通过以上示例，你已掌握 L7 Scene 的：
- 实例化：如何构造并传入地图引擎。
- 视图控制：设置中心点、缩放、俯仰、旋转及自适应边界。
- 图层管理：添加/移除/获取图层。
- 渲染与导出：手动渲染、导出 PNG，并销毁场景。
- 事件监听：捕获地图及鼠标交互事件。
)
