features*
nay trả {layer, props, geometry} thay vì đối tượng MapLibre thô —
đổi f.properties thành f.props, f.layer.id
thành f.layer. Chi tiết và cách giữ mã cũ: CHANGELOG.
Bản đồ offline Việt Nam. Nhúng một thẻ <script>, dùng như Google Maps.
<div id="map" style="height:400px"></div>
<script src="http://may-chu:32026/sdk/vnmap-3.0.0.js"></script>
<script>
VNMap.configure({ key: "vnmap_..." }); // khoá do bên cấp dịch vụ gửi
VNMap.create("#map", {
center: [105.8542, 21.0285], // [kinh độ, vĩ độ], ngược Google Maps
zoom: 13,
}).then(function (map) {
map.addMarker({ lng: 105.8542, lat: 21.0285, title: "Hồ Hoàn Kiếm" });
});
</script>
/sdk/vnmap-3.0.0.js gắn với số hiệu nên nội dung không bao giờ
đổi, trình duyệt cache thoải mái — nên dùng khi chạy thật.
/sdk/vnmap.js luôn trỏ bản mới nhất, cache 5 phút, hợp để thử nhanh.
npm install, không có bước build, không gọi ra Internet.
// Nạp động, không cần đóng gói vào bundle của bạn
await import(/* @vite-ignore */ "http://may-chu:32026/sdk/vnmap-3.0.0.js");
window.VNMap.configure({
origin: "http://may-chu:32026", // BẮT BUỘC khi nạp kiểu này
key: "vnmap_...",
});
const map = await window.VNMap.create("#map", { zoom: 13 });
origin. Nhúng bằng thẻ
<script> thì SDK tự tìm ra máy chủ nhờ đường dẫn của
chính thẻ đó. Nạp bằng import() thì
document.currentScript là null — SDK đành lấy thẻ
script cuối cùng trong trang, thường là một mảnh mã của Next.js, và mọi lời
gọi sẽ đi sai địa chỉ. SDK có in cảnh báo ra Console khi rơi vào tình huống
này, nhưng khai sẵn thì hơn.
Next.js dựng trang trên máy chủ trước, nơi không có window —
nên component bản đồ phải chạy chỉ ở phía trình duyệt.
// components/BanDo.tsx
"use client";
import { useEffect, useRef } from "react";
export default function BanDo() {
const oRef = useRef<HTMLDivElement>(null);
useEffect(() => {
let map: any = null;
let huy = false;
(async () => {
await import(/* webpackIgnore: true */ "http://may-chu:32026/sdk/vnmap-3.0.0.js");
if (huy) return;
const VNMap = (window as any).VNMap;
VNMap.configure({ origin: "http://may-chu:32026", key: "vnmap_..." });
map = await VNMap.create(oRef.current, { zoom: 13 });
})();
// Bắt buộc: React 18 ở chế độ Strict gọi effect hai lần khi dev
return () => { huy = true; if (map) map.remove(); };
}, []);
return <div ref={oRef} style={{ height: 400 }} />;
}
// app/page.tsx — tắt dựng phía máy chủ cho riêng component này
import dynamic from "next/dynamic";
const BanDo = dynamic(() => import("../components/BanDo"), { ssr: false });
export default function Page() { return <BanDo />; }
| Chỗ dễ vấp | Xử lý |
|---|---|
window is not defined |
Component chưa tắt SSR. Bọc bằng dynamic(..., { ssr: false }) |
| Bản đồ hiện hai cái khi chạy dev | React Strict Mode gọi useEffect hai lần.
map.remove() trong hàm dọn là bắt buộc |
| Gọi sai địa chỉ máy chủ | Khai origin như trên |
TypeScript báo không biết VNMap |
Chưa có file .d.ts. Khai
declare global { interface Window { VNMap: any } } |
| Tuỳ chọn | Mặc định | Ý nghĩa |
|---|---|---|
center | [106.0, 16.0] | [kinh độ, vĩ độ] |
zoom | 5.2 | Mức phóng ban đầu |
style | "standard" |
"standard" | "light" | "voyager" |
"bright" | "transport" | "dark" |
"toner"
— xem bảng ở mục 3 |
controls | true | Nút zoom + thước tỉ lệ |
minZoom / maxZoom | 3 / — | Giới hạn phóng |
bounds | — | Khoá khung nhìn [[tây,nam],[đông,bắc]] |
| Gọi | Trả về |
|---|---|
map.search(q, {limit}) | [{name, lng, lat, type, address}] — nhận cả toạ độ "21.03, 105.85" |
map.reverse(lng, lat) | {name, address} |
map.route([[lng,lat],…], {profile, steps}) |
{geometry, distanceM, durationS, steps} — steps
rỗng nếu không truyền steps: true |
map.drawRoute(route) · map.clearRoute() |
Vẽ tuyến lên bản đồ, tự zoom khít |
map.addMarker({lng, lat, …}) |
Marker. Xem bảng tuỳ chọn ngay dưới |
map.clearMarkers() | — |
map.addGeoJSONLayer(id, geojson, {color, label, onClick}) | Lớp dữ liệu của bạn |
map.setBaseStyle(kiểu) |
Đổi nền sang một trong bảy kiểu ở bảng dưới, dựng lại mọi lớp SDK đã thêm |
map.flyTo(lng, lat, zoom) · map.fitGeometry(geom) | — |
map.on(event, fn) |
Bắt sự kiện MapLibre: click, moveend,
zoomend, load… |
map.once(event, fn) |
Nghe đúng MỘT lần rồi tự gỡ. Lưu ý "idle" chỉ bắn khi bản
đồ đang bận rồi rảnh — đang rảnh sẵn thì nó không bao giờ tới |
map.off(event, fn) |
Gỡ trình nghe đã gắn |
map.remove() |
Huỷ bản đồ và dọn marker. Bắt buộc gọi khi component bị gỡ, nếu không sẽ rò bộ nhớ và ngữ cảnh WebGL |
map.map | Đối tượng MapLibre gốc — dùng khi cần nâng cao |
Bộ tile theo lược đồ OpenMapTiles, nên ngoài ba nền riêng của SDK còn có bốn nền dựng theo lối các style chuẩn quốc tế.
| Kiểu | Trông thế nào | Dùng khi |
|---|---|---|
"standard"Chuẩn |
Nền kem sáng, đường trắng viền xám, trục chính vàng, cao tốc cam. Mặt đất tô theo 29 loại — dân cư, trường, bệnh viện, nghĩa trang… | Mặc định. Hợp với hầu hết trường hợp |
"light"Trung tính |
Toàn bộ lùi về xám: đường trắng viền xám, đất phẳng một màu, nước xám xanh rất nhạt. Theo lối Positron của CARTO | Khi bạn đổ dữ liệu của mình lên. Bản đồ nhường hết màu, điểm và vùng của bạn là thứ duy nhất nổi lên |
"voyager"Dịu màu |
Nền ấm, màu dịu, nhãn dễ đọc. Theo lối Voyager của CARTO — nằm giữa Chuẩn và Trung tính | Bản đồ dùng chung, cần có màu nhưng không muốn chói |
"bright"Sáng rõ |
Bảng màu quen thuộc của openstreetmap.org: xanh lá rõ, nước xanh dương, quốc lộ vàng cam. Theo lối OSM Bright | Bản đồ tra cứu, người dùng quen nhìn OSM |
"toner"Đen trắng |
Chỉ đen và trắng, tương phản tối đa. Theo lối Toner của Stamen | In ra giấy, hoặc bản đồ chuyên đề cần để dành toàn bộ màu cho dữ liệu |
"transport"Giao thông |
Nền xám nhạt, đường dày gấp 1,7 lần và tô đậm: cao tốc đỏ, quốc lộ cam, tỉnh lộ vàng | Bản đồ nói về đường sá — theo dõi xe, giao hàng, quy hoạch tuyến. Nền lùi lại để đường nổi lên |
"dark"Tối |
Xám trung tính rất tối, chữ sáng. Theo lối Dark Matter — bản song sinh của Positron | Màn hình trực ban, phòng điều hành, xem ban đêm |
// Chọn lúc tạo
VNMap.create("#map", { style: "transport" });
// Hoặc đổi bất cứ lúc nào
map.setBaseStyle("transport");
addMarker| Tuỳ chọn | Ý nghĩa |
|---|---|
lng · lat | Bắt buộc |
title | Popup chữ thường, tự thoát ký tự HTML |
html | Popup HTML — dùng khi cần ảnh, bảng, nút bấm.
Ưu tiên hơn title |
color | Màu ghim mặc định, bỏ qua nếu có element |
element | Node DOM của riêng bạn thay cho ghim mặc định |
anchor | center · bottom · top…
— điểm neo của phần tử vào toạ độ |
draggable | Cho kéo thả |
onClick | function(opts, marker).
Đã chặn nổi bọt, nên không kích hoạt map.on("click") |
popup. Popup sinh ra từ
title hoặc html.
| Hàm | Số điểm hợp lý | Đặc điểm |
|---|---|---|
addMarker | < 50 | Ghim DOM, popup sẵn, style CSS, element tuỳ biến, draggable |
addMarkerLayer(id, gj, o) | 50 – 500 | Marker quản theo lớp |
addGeoJSONLayer(id, gj, o) | 500 – 5.000 | WebGL, có nhãn tên, tô màu theo thuộc tính |
addClusterLayer(id, gj, o) | > 5.000 | Gom cụm, bấm cụm để tách |
addPolygonLayer(id, gj, o) | vùng | Ranh giới, colorBy tô theo thuộc tính |
Dùng chung cho mọi kiểu: map.setLayerVisible(id, false) ·
map.removeLayer(id) — hàm này gỡ bất kể lớp thuộc kiểu nào,
nên bạn không cần nhớ đã thêm bằng hàm gì. Muốn gỡ đúng một kiểu thì có
removeGeoJSONLayer · removeMarkerLayer ·
removePolygonLayer · removeClusterLayer.
beforeId, nên muốn vùng nằm dưới điểm thì thêm vùng trước.
Lỡ thứ tự thì removeLayer rồi thêm lại, hoặc chèn tay qua
map.map.addLayer(spec, beforeId).
map.startDraw("polygon", { // point | line | polygon | circle | rectangle
color: "#2563eb",
onUpdate: function (gj, m) { /* m.pointCount, m.lengthM, m.areaM2 */ },
onFinish: function (gj, m) { saveToServer(gj); },
});
map.finishDraw(); map.cancelDraw(); map.clearDraw();
| Gọi | Trả về |
|---|---|
map.findProvince(name) |
{tenTinh, props, geometry, bbox} — 34 tỉnh, thành phố |
map.drawProvinceBoundary(name, o) |
Vẽ đường bao và zoom khít |
map.findWard(name, provinceHint) |
{tenXa, tenTinh, lng, lat, sapNhap, tenCu} — 3.321 xã, phường |
map.drawWardBoundary(name, o) |
Vẽ đường bao xã, phường |
map.clearBoundary(id) | — |
map.showOnly(area, o) |
Chỉ hiển thị một hoặc nhiều tỉnh, xã — phần ngoài bị
che kín. Nhận {provinces, wards, province, geojson}.
Promise → {tim, khongTim, bbox}.opacity hạ xuống là thành làm mờ thay vì che kín;
lock khoá không cho kéo ra ngoài vùng |
map.clearShowOnly(id) |
Bỏ lớp che, trả bản đồ về bình thường |
map.wardAt([lng, lat]) |
Promise → thuộc tính xã, phường chứa điểm đó, hoặc null.
Đọc tile đã tải, không gọi mạng |
VNMap.wardAddress(props) |
{text, former} — ghép "Phường Hoa Lư, Tỉnh Ninh Bình"
kèm tên trước sắp xếp 2025 |
// Bấm bản đồ → ra tên xã, phường
map.on("click", async (e) => {
const p = await map.wardAt([e.lngLat.lng, e.lngLat.lat]);
if (!p) return;
const dc = VNMap.wardAddress(p);
console.log(dc.text); // Phường Hoa Lư, Tỉnh Ninh Bình
if (dc.former) console.log("Trước đây:", dc.former);
});
const ds = map.nearbyPlaces([105.85, 21.02], {
classes: ["supermarket", "convenience"], // bỏ trống là lấy mọi loại
radius: 1500, // mét, mặc định 1500
limit: 20,
});
// [{ name, lng, lat, distanceM, category: {label, group, class}, props }]
VNMap.placeCategory("supermarket"); // { label: "Siêu thị", group: "shopping" }
nearbyPlaces đọc dữ liệu đang có trong khung nhìn,
không phải truy vấn toàn quốc. Muốn tìm ở nơi khác thì flyTo tới
đó trước rồi hãy gọi.
findWard tra được cả tên trước đợt sắp xếp 2025:
gõ "Hồng Thuận" ra "Xã Giao Hòa", kèm tenCu để bạn hiển thị cho
người dùng biết.
// Mặc định đã bật. Chỉ gọi khi muốn đổi khoảng zoom hoặc màu chữ.
map.addAdminLabels({
provinces: true,
wards: true,
provinceZoom: [5, 11],
wardZoom: 11,
});
map.removeAdminLabels();
// Không gọi mạng — đọc thẳng tile đã tải
map.featuresAtPoint([lng, lat], { layers: ["lop-camera"], radius: 6 });
map.featuresInView({ layers: ["lop-camera"] });
map.featuresFromSource("vnward-src", { sourceLayer: "wards" });
Chỉ thấy phần đã tải ở mức zoom hiện tại, không phải truy vấn cơ sở dữ liệu.
Tra toàn quốc thì dùng findProvince và findWard.
VNMap.distance([lng,lat], [lng,lat]); // mét, công thức haversine
VNMap.lineLength([[lng,lat], [lng,lat]]); // mét
VNMap.area([[lng,lat], [lng,lat], [lng,lat]]); // m², thuật toán shoelace
VNMap.circle([lng,lat], 500); // đa giác 64 cạnh, bán kính 500 m
VNMap.formatLength(1500); // "1.50 km"
VNMap.formatArea(25000); // "2.50 ha"
map.getCenter() · map.getZoom() · map.getBounds() |
Đọc trạng thái — gửi getBounds() lên máy chủ để chỉ tải dữ liệu trong khung |
map.fitBounds([tây,nam,đông,bắc], {padding}) |
Zoom khít. padding mặc định 60 px.
Chú ý mảng phẳng bốn số, khác tuỳ chọn
bounds lúc khởi tạo vốn lồng hai cặp |
map.locate({ zoom, fly }) |
{lng, lat, accuracyM} — chỉ chạy trên HTTPS
hoặc localhost |
map.screenshot() | Ảnh PNG dataURL — phải tạo map với { screenshot: true } |
// Ví dụ: ô nhập địa chỉ trong form, không hiển thị bản đồ
const kq = await VNMap.search("Phường Hoa Lư");
const dc = await VNMap.reverse(105.9719, 20.2572);
VNMap| Gọi | Trả về |
|---|---|
VNMap.version | Số hiệu SDK, ví dụ "3.0.0" |
VNMap.errors |
{ mã: "câu giải thích" } — bảng mã lỗi khoá, để bạn
tự hiển thị thay vì chép cứng |
VNMap.withKey(url) |
Gắn khoá vào URL bạn tự fetch. Ví dụ tải danh sách 34
tỉnh đổ vào dropdown mà không vẽ gì |
VNMap.getConfig() | Bản sao cấu hình đang dùng |
VNMap.buildStyle("dark") |
Đối tượng style MapLibre — dùng khi bạn tự dựng
new maplibregl.Map() thay vì qua SDK |
VNMap.load() |
Nạp sẵn MapLibre trước khi cần, để lúc mở bản đồ không phải chờ |
// Tự fetch dữ liệu, khoá do SDK gắn
const r = await fetch(VNMap.withKey(MAY_CHU + "/data/vn-province-points.geojson"));
const tinh = await r.json();
const map = await VNMap.create("#map", { center: [105.85, 21.03], zoom: 13 });
// Tìm rồi cắm marker
const kq = await map.search("Hồ Hoàn Kiếm");
if (kq.length) {
map.addMarker({ lng: kq[0].lng, lat: kq[0].lat, title: kq[0].name });
map.flyTo(kq[0].lng, kq[0].lat, 16);
}
// Chỉ đường
const r = await map.route([[105.85, 21.03], [105.80, 21.00]]);
map.drawRoute(r);
console.log((r.distanceM / 1000).toFixed(1) + " km");
// Lớp dữ liệu riêng — dùng layer WebGL, hàng chục nghìn điểm vẫn mượt
map.addGeoJSONLayer("camera", geojsonCamera, {
color: "#2563eb", label: "name",
onClick: (f) => alert(f.properties.name),
});
// Nhấn bản đồ -> ra địa chỉ
map.on("click", async (e) => {
const dc = await map.reverse(e.lngLat.lng, e.lngLat.lat);
console.log(dc?.name);
});
Gọi trước VNMap.create():
VNMap.configure({
key: "vnmap_...", // bắt buộc, trừ khi cùng máy chủ
// Bốn dòng dưới chỉ cần khi SDK đoán sai máy chủ — thường là khi bạn chép
// vnmap.js về máy mình thay vì nhúng thẳng từ máy chủ bản đồ.
tiles: "http://may-chu:32026/tiles",
osrm: "http://may-chu:32026/osrm",
nominatim: "http://may-chu:32026/nominatim",
dataUrl: "http://may-chu:32026/data",
provinceLabels: true, // vẽ tên tỉnh, mặc định bật
wardLabels: true, // vẽ tên xã, phường, mặc định bật
poi: true, // địa điểm trên nền, mặc định bật
worldBackground: true, // biển và viền nước láng giềng khi zoom xa
landTint: "full", // tô khối lãnh thổ khi zoom xa: full | soft | off
railwayNames: true, // tên tuyến đường sắt, file 94 KB
buildingNames: false, // tên toà nhà, file 3,1 MB — bật khi thật sự cần
attribution: "© OpenStreetMap contributors", // dòng ghi nguồn góc bản đồ
});
worldBackground thì kéo ra ngoài biên giới là trắng trơn —
không thấy biển, không thấy Lào hay Campuchia. Hai file Natural Earth nhẹ,
chỉ tải khi zoom nhỏ hơn 9. Tắt được khi bản đồ luôn khoá trong phạm vi
Việt Nam ở mức zoom sâu.
Siêu thị, chợ, quán ăn, ngân hàng, cây xăng, trường học, bệnh viện, khách sạn — lấy từ dữ liệu OpenStreetMap, vẽ sẵn trên nền. Icon tròn có ký hiệu theo nhóm, hiện từ zoom 13; tên hiện từ zoom 15.
| Nhóm | Gồm |
|---|---|
| Mua sắm | siêu thị, tạp hoá, chợ, trung tâm thương mại, cửa hàng |
| Ăn uống | nhà hàng, quán ăn nhanh, cà phê, quán bar |
| Ngân hàng | chi nhánh, cây ATM |
| Y tế | bệnh viện, phòng khám, nhà thuốc |
| Giáo dục | trường, đại học, thư viện, mầm non |
| Khác | cây xăng, bến xe, nhà ga, sân bay, khách sạn |
VNMap.configure({ poi: false }).
Để cả hai, điểm của OSM tranh chỗ với điểm của bạn, bản đồ giấu bớt nhãn
và trông như bị lỗi.
origin là lối tắt: đặt một lần thay cho cả bốn dòng trên. Khai
riêng từng đường dẫn vẫn được ưu tiên hơn.
tileSource và wardSource đổi tên bộ tile nếu máy
chủ của bạn đặt tên khác. VNMap.getConfig() trả bản sao cấu
hình đang dùng.
attribution.
| Câu hỏi | Trả lời |
|---|---|
| Hệ toạ độ nào? | Vào ra đều là WGS 84 (EPSG:4326), độ thập phân. Bản đồ hiển thị theo Web Mercator. Dữ liệu VN-2000 phải chuyển trước khi đưa vào |
| Khung chứa bản đồ đổi kích thước, bản đồ méo | Gọi map.map.resize(). Hay gặp khi bản đồ nằm trong
tab ẩn, panel co giãn, hoặc modal — lúc tạo thì khung cao 0 px |
| Dùng trong React / Angular / Vue | Tạo trong useEffect / ngAfterViewInit, và
bắt buộc gọi map.remove() lúc dọn.
Không gọi thì mỗi lần vào ra route lại bỏ lại một ngữ cảnh WebGL —
trình duyệt chỉ cho khoảng 16 cái |
| Hai bản đồ trên cùng một trang | Được. Nhưng VNMap.configure() là toàn cục —
hai bản đồ dùng chung khoá và chung máy chủ, không đặt riêng được |
| Có file định nghĩa TypeScript không? | Chưa có .d.ts. Trong dự án TS, khai
declare const VNMap: any; hoặc tự viết typing cho
phần bạn dùng |
| SDK có gọi ra Internet không? | Không. MapLibre, CSS, font, tile, dữ liệu — tất cả lấy từ máy chủ bản đồ của bạn. Chạy được trong mạng kín |
| Đổi nền xong lớp của tôi còn không? | Còn. setBaseStyle dựng lại mọi lớp SDK đã thêm —
điểm, vùng, gom cụm, ranh giới, nhãn. Lớp bạn tự thêm thẳng qua
map.map.addLayer thì không, phải tự thêm lại trong
sự kiện styledata |
| Ranh giới xã không hiện ở mức zoom xa | Bộ tile xã bắt đầu từ zoom 6, và nhãn xã từ zoom 11.
drawWardBoundary tự bay tới zoom 12 vì lý do đó |
Không nạp được vnmap.js thì lấy thẳng style JSON.
Mọi client tương thích MapLibre đều đọc được: MapLibre Native, MapLibre GL
Flutter, QGIS, và cả MapLibre GL JS nếu bạn tự khởi tạo.
GET http://may-chu:32026/sdk/style/standard.json?key=vnmap_...
| Đường dẫn | Nền |
|---|---|
/sdk/style/index.json | Danh mục toàn bộ nền có sẵn |
/sdk/style/standard.json | Chuẩn |
/sdk/style/light.json | Trung tính |
/sdk/style/voyager.json | Dịu màu |
/sdk/style/bright.json | Sáng rõ |
/sdk/style/transport.json | Giao thông |
/sdk/style/dark.json | Tối |
/sdk/style/toner.json | Đen trắng |
Máy chủ tự thay địa chỉ và khoá vào mọi URL bên trong — tile, font, dữ liệu ranh giới. Bạn chỉ cần đưa URL đó cho thư viện, không phải sửa gì thêm.
MapLibreMap(
styleString: "http://may-chu:32026/sdk/style/standard.json?key=vnmap_...",
)
mapView.setStyle("http://may-chu:32026/sdk/style/light.json?key=vnmap_...")
Layer → Add Layer → Add Vector Tile Layer, chọn Style URL rồi dán đường dẫn kèm khoá.
*.
Ràng buộc tên miền dựa vào header Origin mà trình duyệt gửi —
ứng dụng native không có thứ đó, nên khoá gắn tên miền cụ thể sẽ bị chặn với
mã DOMAIN_NOT_ALLOWED. Báo bên cấp dịch vụ là bạn dùng cho ứng
dụng di động để họ cấp đúng loại khoá.
| Vấn đề | Xử lý |
|---|---|
Toạ độ là [kinh độ, vĩ độ] | Ngược thói quen lat, lng của Google Maps. Riêng reverse(lng, lat) theo thứ tự này |
| Chỉ đường trả lỗi "đang khởi động" | OSRM nạp graph 4.5 GB, mất ~1 phút sau khi bật máy chủ |
| Bản đồ trắng | Ba khả năng: máy chủ chưa chạy · sai địa chỉ trong configure() · chưa khai khoá. Bắt bằng catch rồi đọc e.code |
Mã lỗi DOMAIN_NOT_ALLOWED | Khoá đúng nhưng tên miền của trang chưa được khai. Đổi cổng cũng phải báo lại |
| Nhiều điểm (>500) | Dùng addGeoJSONLayer, KHÔNG dùng addMarker — marker tạo 1 DOM node mỗi điểm |
| Trang chạy HTTPS | Máy chủ bản đồ cũng phải HTTPS, nếu không trình duyệt chặn (mixed content) |