AntV L7入门教程

以下教程将系统地介绍 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 或 HTMLElement
  • map：必选，地图引擎实例（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 的：

1. 实例化：如何构造并传入地图引擎。
2. 视图控制：设置中心点、缩放、俯仰、旋转及自适应边界。
3. 图层管理：添加/移除/获取图层。
4. 渲染与导出：手动渲染、导出 PNG，并销毁场景。
5. 事件监听：捕获地图及鼠标交互事件。