以下教程將系統地介紹 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，并銷毀場景。
- 事件監聽：捕獲地圖及鼠標交互事件。
)
