Nhúng bản đồ cửa hàng vào website bằng một thẻ <vapp-map>

Trả lời nhanh: thêm một dòng <script> và một thẻ <vapp-map> vào trang của bạn là có bản đồ Việt Nam với danh sách cửa hàng, ô tìm và nút chỉ đường. Không cần cài thư viện, không cần bước build, không cần khoá API. Tệp script nén gzip dưới 10 KB; bản đồ là trang nhúng của map.vapp.vn, hiển thị đúng biên giới và chủ quyền Việt Nam, gồm Hoàng Sa và Trường Sa.

1. Bản đồ một cửa hàng

<script src="https://map.vapp.vn/embed/vapp-map.js" defer></script>
<vapp-map lat="10.7725" lng="106.698" zoom="16" marker label="Cửa hàng của bạn"></vapp-map>

Thẻ nhận tọa độ theo thứ tự vĩ độ (lat) rồi kinh độ (lng). Chưa có tọa độ? Đổi địa chỉ thành tọa độ bằng API geocode.

2. Trang "Hệ thống cửa hàng"

Truyền danh sách cửa hàng vào markers. Thẻ cắm từng cửa hàng lên bản đồ, vừa khung cho tất cả, và hiện cột danh sách bên trái (thẻ hẹp hơn 600px thì danh sách nằm dưới bản đồ). Bấm một cửa hàng, bản đồ bay tới đó và hiện tên.

<script src="https://map.vapp.vn/embed/vapp-map.js" defer></script>
<vapp-map markers='[{"lat":10.7725,"lng":106.698,"label":"Cửa hàng mẫu Bến Thành","address":"Gần chợ Bến Thành, TP.HCM"},{"lat":10.7798,"lng":106.699,"label":"Cửa hàng mẫu Nhà thờ Đức Bà","address":"Gần Nhà thờ Đức Bà, TP.HCM"},{"lat":10.7951,"lng":106.7218,"label":"Cửa hàng mẫu Landmark 81","address":"Gần Landmark 81, TP.HCM"},{"lat":10.8185,"lng":106.6588,"label":"Cửa hàng mẫu Tân Sơn Nhất","address":"Gần sân bay Tân Sơn Nhất, TP.HCM"}]' search directions style="height:420px"></vapp-map>

3. Các thuộc tính

Thuộc tínhGiá trịTác dụng
latsốVĩ độ tâm bản đồ (ví dụ 10.7725).
lngsốKinh độ tâm bản đồ (ví dụ 106.698).
zoomsốMức phóng to. Mặc định 16 khi có một điểm, 13 khi không có điểm; nhiều cửa hàng thì bản đồ tự vừa khung.
markerkhông cần giá trịCắm một điểm tại lat, lng.
labelchữNhãn hiện trên điểm đầu tiên, và là tên khung bản đồ cho trình đọc màn hình.
markersJSONDanh sách cửa hàng: [{"lat":…,"lng":…,"label":"…","address":"…"}]. Có danh sách thì thẻ hiện thêm cột cửa hàng; tối đa 200 cửa hàng, điểm sai tọa độ bị bỏ qua.
searchkhông cần giá trịThêm ô tìm trong danh sách, theo tên và địa chỉ, gõ có dấu hay không dấu đều được.
directionskhông cần giá trịThêm liên kết Chỉ đường cho từng cửa hàng, mở map.vapp.vn ở tab mới với điểm đến đã chọn.
langenGiao diện bản đồ bằng tiếng Anh. Mặc định tiếng Việt.

Đổi một thuộc tính bằng JavaScript (el.setAttribute("markers", …)) thì thẻ vẽ lại. Tên và địa chỉ cửa hàng được hiện dưới dạng chữ, không phải HTML, nên dữ liệu lấy từ hệ thống của bạn không chạy được mã trong trang.

4. Đổi màu cho hợp thương hiệu

Biến CSSMặc địnhTác dụng
--vapp-map-height400pxChiều cao cả thẻ (hoặc đặt style="height:…" trên thẻ).
--vapp-map-list-width300pxBề rộng cột cửa hàng khi thẻ rộng từ 600px.
--vapp-map-accent#0e7a5fMàu nhấn: cửa hàng đang chọn, liên kết, viền khi bấm phím Tab.
--vapp-map-text#1f2328Màu chữ.
--vapp-map-bg#fffNền danh sách và ô tìm.
--vapp-map-border#d8d2c4Màu viền.
--vapp-map-radius8pxBo góc khung.
--vapp-map-font14px/1.4 system-uiPhông chữ của danh sách.
vapp-map {
  --vapp-map-accent: #c2410c;
  --vapp-map-radius: 0;
  --vapp-map-height: 520px;
}
vapp-map::part(item) { padding: .75rem; }

Các phần có thể chỉnh bằng ::part(): frame, map, list, search, item, directions.

5. Biết khách bấm cửa hàng nào

Mỗi lần khách bấm một cửa hàng, thẻ phát sự kiện vapp-map-select; event.detail có index, lat, lng, label, address.

document.querySelector("vapp-map").addEventListener("vapp-map-select", (e) => {
  console.log("Khách xem", e.detail.label);
});

6. Không dùng được JavaScript? Dùng iframe

Thẻ <vapp-map> chỉ là lớp bọc quanh trang nhúng. Nơi chỉ cho dán iframe thì dán thẳng trang nhúng; nhiều điểm cách nhau bằng dấu chấm phẩy trong markers=kinh_độ,vĩ_độ;kinh_độ,vĩ_độ (iframe dùng thứ tự kinh độ trước).

<iframe src="https://map.vapp.vn/?embed=1&marker=106.698,10.7725&label=C%E1%BB%ADa%20h%C3%A0ng&zoom=16"
  width="100%" height="400" style="border:0" loading="lazy" title="Bản đồ"></iframe>

Bản đồ nhúng chỉ hiện bản đồ nền sáng và các điểm của bạn. Các lớp ngập lụt, thời tiết, không khí, xe buýt, tàu, trạm sạc đều tắt, kể cả khi khách đã bật chúng trên map.vapp.vn. Muốn bật một lớp, thêm vào cuối địa chỉ iframe: #flood=1 (ngập lụt), #w=1 (thời tiết), #aq=1 (không khí), #bus=1, #train=1, #ev=1, #d=1 (nền tối); nhiều lớp nối bằng &, ví dụ #flood=1&w=1. Nút Mở bản đồ lớn ↗ ở góc trên mở đúng chỗ đó (hoặc cửa hàng khách vừa chọn) trên map.vapp.vn, trong thẻ mới.

7. Cần biết trước khi dùng