Commands (Lệnh điều khiển)

Để tương tác với bản đồ, người dùng SDK sử dụng các phương thức từ instance VGMMap. Các lệnh này sẽ được App bên trong iframe xử lý và phản hồi thông qua cầu nối postMessage.

1. Điều khiển Khung nhìn (View)

setView

Thay đổi vị trí trung tâm, mức zoom và tầng hiển thị của bản đồ.

sdk.setView({
  lng: 105.7960,
  lat: 21.0069,
  zoom: 19,
  floor: 2 // Tùy chọn: Chuyển tầng sau khi di chuyển
});

• Tham số:
  • lng, lat (number): Tọa độ địa lý.
  • zoom (number, optional): Mức zoom (mặc định 19).
  • floor (number, optional): ID tầng muốn hiển thị.

2. Điều khiển Tương tác (Interaction)

enableInteraction

Bật hoặc tắt khả năng điều khiển của người dùng trên bản đồ (di chuyển, zoom, xoay).

// Vô hiệu hóa tương tác để làm "bản đồ tĩnh"
sdk.enableInteraction(false);

• Tham số: enable (boolean). Nếu false, bản đồ sẽ không phản hồi với chuột hoặc thao tác cảm ứng.

3. Quản lý Site

setSite

Chuyển đổi giữa các site (cơ sở dữ liệu bản đồ) khác nhau trong cùng một instance.

sdk.setSite(5); // Chuyển sang Site có ID là 5

• Tham số: siteId (number). Lệnh này sẽ kích hoạt việc tải lại style và các danh mục POI của site mới.

4. Quản lý Layer (Lớp bản đồ động)

SDK hỗ trợ thêm các lớp dữ liệu trực tiếp từ trang host mà không cần cấu hình trên server bản đồ.

Đây là phần cập nhật cho trang api/commands.md để người dùng hiểu rõ cấu trúc của một Layer khi gọi sdk.addLayer().

addLayer

Thêm một lớp mới vào bản đồ.

sdk.addLayer({
  id: "my-heatmap-layer",
  source: {
    type: "geojson",
    data: { /* GeoJSON object hoặc URL */ }
  },
  layer: {
    type: "heatmap",
    paint: { /* Cấu hình hiển thị */ }
  },
  floor: 1 // Hiển thị trên tầng 1
});

Cấu trúc VgmLayerConfig

Đây là định dạng đối tượng mà bạn cần truyền vào lệnh addLayer:

Thuộc tính	Kiểu dữ liệu	Mô tả
id	string	Định danh duy nhất cho lớp.
source	Object	Nguồn dữ liệu (GeoJSON hoặc Vector).
source.type	'geojson' | 'vector'	Loại nguồn dữ liệu.
source.data	Object | string	Dữ liệu thô (nếu là geojson) hoặc URL.
layer	Object	Cấu hình hiển thị (tương đương MapLibre Layer).
layer.type	'heatmap' | 'line' | 'fill' | ...	Loại hiển thị.
layer.paint	Object	Thuộc tính vẽ (màu sắc, độ mờ, v.v.).
layer.layout	Object	Thuộc tính bố cục (visibility, icon, v.v.).
floor	number	Tùy chọn: Chỉ định tầng hiển thị của layer.

Các phương thức Layer khác

• removeLayer(id): Xóa lớp khỏi bản đồ dựa trên id.
• toggleLayer(id, visible): Ẩn hoặc hiện lớp (visible: boolean).
• clearLayers(): Xóa toàn bộ các lớp động đã thêm qua SDK.

---

Ví dụ về Heatmap Layer:

sdk.addLayer({
  id: "heatmap-v1",
  source: {
    type: "geojson",
    data: "https://example.com/data.json"
  },
  layer: {
    type: "heatmap",
    paint: {
      "heatmap-weight": ["get", "mag"],
      "heatmap-intensity": 1
    }
  },
  floor: 2
});

---

Tại sao cần dùng floor? Khi bạn truyền thuộc tính floor trong VgmLayerConfig, SDK sẽ tự động xử lý logic ẩn/hiện lớp dữ liệu này khi người dùng chuyển tầng, giúp bạn không cần phải tự viết code lọc dữ liệu theo tầng trong trang host.

sdk.addLayer({
  id: "my-custom-layer",
  type: "symbol",
  source: { /* GeoJSON hoặc Vector Tile source */ },
  layout: { /* Layout configuration */ }
});

removeLayer

Xóa lớp khỏi bản đồ.

sdk.removeLayer("my-custom-layer");

toggleLayer

Ẩn hoặc hiện một lớp đã tồn tại.

sdk.toggleLayer("my-custom-layer", false); // Ẩn layer

clearLayers

Xóa toàn bộ các lớp động đã được thêm qua SDK.

sdk.clearLayers();

5. Truy vấn trạng thái

getState

Lấy thông tin trạng thái hiện tại của bản đồ.

sdk.getState("MY_REPLY_EVENT");

// Lắng nghe kết quả trả về
sdk.on("MY_REPLY_EVENT", (data) => {
  console.log("Center:", data.center);
  console.log("Current Floor:", data.floor);
});

---

Ghi chú cho lập trình viên

• Hàng đợi lệnh (Queueing): SDK tự động đưa các lệnh vào hàng đợi nếu được gọi trước khi sự kiện APP_READY xảy ra. Bạn không cần lo lắng về việc lệnh bị mất nếu gọi ngay khi trang vừa tải.
• Tính an toàn: Mọi lệnh đều được chuyển đổi thành postMessage gửi đến iframe. Do đó, các lệnh này không ảnh hưởng đến bảo mật và phạm vi truy cập của trang host.