Source: https://maps.vietmap.vn/docs/vi/map-api/tilemap-leaflet/

# Tích hợp với Leaflet

Nếu đã có dự án Leaflet, gói [`@vietmap/vietmap-gl-leaflet`](https://www.npmjs.com/package/@vietmap/vietmap-gl-leaflet) bọc VIETMAP GL JS thành một layer của Leaflet — giữ nguyên API Leaflet và mọi plugin đang dùng, phần bản đồ nền vector do WebGL vẽ. Gói là bản chuyển thể từ [maplibre-gl-leaflet](https://github.com/maplibre/maplibre-gl-leaflet).

Thứ tự nhúng là bắt buộc: Leaflet → VIETMAP GL JS → plugin.

```html
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css" />
<link rel="stylesheet" href="https://unpkg.com/@vietmap/vietmap-gl-js/dist/vietmap-gl.css" />

<div id="map" style="height: 400px"></div>

<script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js"></script>
<script src="https://unpkg.com/@vietmap/vietmap-gl-js/dist/vietmap-gl.js"></script>
<script src="https://unpkg.com/@vietmap/vietmap-gl-leaflet/leaflet-vietmap-gl.js"></script>

<script>
  var VIETMAP_API_KEY = '{your-apikey}';

  var map = L.map('map', {
    maxBounds: [[180, -Infinity], [-180, Infinity]], // GL JS chặn vĩ độ chặt hơn Leaflet
    maxBoundsViscosity: 1,                           // chặn cứng, không cho kéo quá
    minZoom: 1                                       // tránh lệch đồng bộ ở mức zoom 0
  }).setView([10.762622, 106.660172], 13);

  var gl = L.vietmapGL({
    style: 'https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=' + VIETMAP_API_KEY
  }).addTo(map);

  L.marker([10.762622, 106.660172])
    .bindPopup('Xin chào <b>Leaflet GL</b>!')
    .addTo(map)
    .openPopup();
</script>
```

Đổi `tm` trong URL style sang `lm`, `dm` hoặc `hm` để dùng style khác — xem bảng [Style vector](https://maps.vietmap.vn/docs/vi/map-api/tilemap/#tich-hop-voi-vietmap-maps-sdk). Bản đồ tự tạo bằng [Map Editor](https://maps.vietmap.vn/docs/vi/map-api/map-editor/) cũng dùng được: dán link style vào `style`.

Dùng bundler thì cài qua npm, nhớ cài đủ peer dependency:

```bash
npm install leaflet @vietmap/vietmap-gl-js @vietmap/vietmap-gl-leaflet
```

**Tuỳ chọn của layer**

|Tuỳ chọn|Mặc định|Mô tả|
|--- |--- |--- |
|`style`|không|URL `style.json` của bản đồ nền, kèm `apikey`.|
|`pane`|`tilePane`|Pane của Leaflet để vẽ lớp GL. Mặc định nằm dưới marker và popup nên các lớp Leaflet của bạn luôn đè lên bản đồ nền.|
|`padding`|`0.1`|Mở rộng vùng vẽ so với khung nhìn, `0.1` là 10% mỗi phía.|
|`interactive`|`false`|Có gắn sự kiện chuột và bàn phím lên lớp GL hay không.|
|`updateInterval`|`32`|Giãn cách (ms) giữa các lần đồng bộ khi kéo bản đồ.|

`gl.getVietmapMap()` trả về đối tượng `Map` của VIETMAP GL JS, nên bạn gọi được API GL JS trên nó — ví dụ ghép [Lớp giao thông](https://maps.vietmap.vn/docs/vi/map-api/traffic-layer/). Đợi sự kiện `load` rồi mới thêm source và layer:

```js
var vietmapMap = gl.getVietmapMap();

vietmapMap.on('load', function () {
  vietmapMap.addSource('traffic', { /* sources lấy từ tf/style.json */ });
  vietmapMap.addLayer({ /* layer lấy từ tf/style.json */ });
});
```

!!! note "Đừng tắt attribution của Leaflet"
    Plugin tắt attribution control của bản đồ GL, đọc phần ghi công từ style rồi đẩy sang attribution control của Leaflet. Vì vậy đừng đặt `attributionControl: false` cho bản đồ Leaflet — làm vậy là bản đồ mất phần ghi công.

!!! warning "Đánh đổi khi dùng binding"
    - **Không xoay được bản đồ** — không có bearing, không có pitch.
    - **Chậm hơn dùng GL JS trực tiếp.** Lớp GL chạy ở chế độ không tương tác; Leaflet nhận sự kiện chuột/chạm rồi cập nhật bản đồ GL phía sau, mà GL JS vẽ lại chậm hơn Leaflet.
    - **Giữ nguyên `maxBounds`, `maxBoundsViscosity` và `minZoom: 1`** trong ví dụ: GL JS chặn vĩ độ tối đa chặt hơn Leaflet, còn mức zoom 0 gây lệch giữa hai bản đồ.

    Bù lại bạn dùng được toàn bộ plugin của Leaflet. Nếu không cần plugin nào của Leaflet, dùng thẳng [SDK Web](https://maps.vietmap.vn/docs/vi/sdk-web-gl/overview/) sẽ nhanh và đủ tính năng hơn.

Chỉ cần nền ảnh vệ tinh thì không cần plugin — dùng thẳng `L.tileLayer` với URL ở bảng **Tile raster** phía trên.