Tích hợp với Leaflet

Nếu đã có dự án Leaflet, gói @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.

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

<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 ở trên.

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

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 Traffic theo note Cách dùng lớp Traffic ở trên. Đợi sự kiện load rồi mới thêm source và layer:

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 */ });
});

Đừ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.

Đá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 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.