MapLibre GL JS là thư viện bản đồ vector mã nguồn mở dùng để đưa bản đồ tương tác vào website hoặc ứng dụng webview. Nó bắt đầu là nhánh fork của mapbox-gl-js vào tháng 12/2020, khi Mapbox chuyển khỏi giấy phép mã nguồn mở. Điều đáng chú ý nhất: thư viện vẽ nhanh nhờ GPU, nhưng không phải dịch vụ bản đồ trọn gói, nên bạn cần chuẩn bị style và nguồn tile.
Thank you for reading this post, don't forget to subscribe!Vì sao MapLibre GL JS chọn WebGL và vector tiles?
README của MapLibre GL JS mô tả khả năng chính trong một câu: GPU-accelerated vector tile rendering. Nó không nhắc TypeScript hay WebGL, nhưng trong mã nguồn và tài liệu kỹ thuật của dự án, TypeScript là ngôn ngữ chính và WebGL là tầng render. Bản đồ không được tạo từ các tấm ảnh raster cố định. Thay vào đó, dữ liệu được chia thành vector tiles, mỗi tile chứa đường, điểm, vùng địa lý, và GPU tự vẽ lại theo từng mức zoom.
Cách thiết kế này giải thích vì sao thao tác xoay, nghiêng, phóng to trên MapLibre GL JS trông mượt hơn cách ghép ảnh truyền thống. Nó cũng giải thích vì sao thư viện phụ thuộc vào phần cứng. README không nêu cấu hình tối thiểu, cũng không mô tả điều gì xảy ra khi WebGL không khả dụng; đừng giả định thư viện có chế độ tự fallback sang tile ảnh kiểu Leaflet.
Nhúng MapLibre GL JS theo README cần mấy dòng code?
Bản demo trong README dùng CDN, không cần cài npm. Bạn cần ba thứ: tệp CSS, một thẻ div, và một script kiểu module. Các bước được rút thẳng từ README như sau.
- Thêm
<link href='https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css' rel='stylesheet' />vào thẻ<head>. - Đặt
<div id='map' style='width: 400px; height: 300px;'></div>vào thẻ<body>. - Nạp module và tạo map với option
container,style,center,zoom.
Phần script giữ nguyên theo README bắt đầu bằng dòng import * as maplibregl from 'https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.mjs';, sau đó khởi tạo: const map = new maplibregl.Map({ container: 'map', style: 'https://demotiles.maplibre.org/style.json', center: [-74.5, 40], zoom: 9 }); Đường dẫn .mjs cho thấy bản phân phối này dùng ES module, nên trình duyệt quá cũ không đọc được ví dụ trong README.
Style JSON là gì mà README gọi là stylesheet location?
Trong code mẫu, dòng style trỏ tới style.json và comment ghi "stylesheet location". Đây là điểm dễ gây hiểu lầm nhất: style không phải tệp CSS. Trong hệ sinh thái MapLibre, đây là một tài liệu JSON tuân theo MapLibre Style Specification. Tài liệu này mô tả nguồn dữ liệu tile, cách phối màu, layer nào nằm trên layer nào, font và icon đi kèm.
Muốn thay đổi giao diện bản đồ, bạn sửa file style JSON chứ không sửa mã JavaScript. Muốn thêm nguồn dữ liệu mới, bạn khai báo trong mục sources. Muốn đổi màu đường, bạn vào layer tương ứng trong mục layers. Nếu bạn chỉ import thư viện mà không cung cấp style hợp lệ, MapLibre GL JS không tự sinh ra một bản đồ.
Vì sao bản đồ trắng khi import MapLibre GL JS mà không báo lỗi?
Với MapLibre GL JS, phần lớn lỗi bản đồ trắng không nằm ở thư viện mà nằm ở chỗ không tải được style, tile, sprite hoặc glyphs. Cách gỡ lỗi khá giống nhau qua mọi phiên bản, dù README không đưa quy trình kiểm tra chính thức.
| Dấu hiệu | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Bản đồ không hiện trên trang | Thiếu file maplibre-gl.css hoặc import module sai đường dẫn | Mở tab Network và kiểm tra maplibre-gl.css cũng như maplibre-gl.mjs trả về 200 |
| Có khung bản đồ nhưng các ô tile trống | Style JSON tải được, nhưng nguồn vector tile không tới được do CORS hoặc URL sai | Mở URL của source trong style JSON bằng trình duyệt; kiểm tra console và phản hồi HTTP |
| Icon, chữ biến mất | Sprite hoặc glyphs trong style JSON trỏ sai, hoặc tile server không gửi đúng header | Đối chiếu từng URL sprite và glyphs với kiểu file đang dùng |
| Máy yếu bị giật khi zoom xoay | Thiết bị thiếu GPU hoặc trình duyệt không hỗ trợ WebGL | README không nêu cấu hình tối thiểu; hãy tự test trên thiết bị mục tiêu trước khi chọn |
Sau khi loại các lỗi trên, hãy thử đổi style JSON sang một nguồn khác. Nếu chỉ chạy mã demo, bạn sẽ khó biết đâu là dữ liệu demo và đâu là lỗi cấu hình của chính mình.
MapLibre GL JS hay Leaflet: cầu nối maplibre-gl-leaflet
MapLibre GL JS và Leaflet không nên đặt lên bàn cân như hai sản phẩm cùng loại. Leaflet vốn sinh ra để hiển thị ảnh tile và lớp phủ bằng DOM/SVG, nên nhẹ và dễ tiếp cận. MapLibre GL JS hướng tới vector tiles và kết xuất WebGL, nên đồ sộ hơn về khả năng, cũng nhạy cảm với GPU hơn. README của MapLibre GL JS không so sánh với Leaflet.
Trong cộng đồng, maplibre-gl-leaflet thường xuất hiện như một cầu nối cho phép đặt bản đồ MapLibre GL JS bên trong Leaflet, dù thư viện này không nằm trong README. Vì vậy bạn không bắt buộc phải chọn một trong hai trong mọi dự án. Bạn cũng có thể dùng React hoặc Angular thông qua các wrapper được README nhắc chung là bindings for React and Angular; với Angular, ngx-maplibre-gl là cái tên thường gặp trong các danh sách awesome-maplibre.
Ai đứng sau MapLibre GL JS và giấy phép BSD-3 có ý nghĩa gì?
MapLibre GL JS là dự án cộng đồng, không gắn với một công ty chủ quản duy nhất. README hướng người dùng tham gia kênh #maplibre trên Slack của OpenStreetMap US và đọc CONTRIBUTING.md. Phần tài trợ chia thành Gold, Silver, Backers and Supporters, và chương trình tài trợ có trang riêng. Vì không có công ty nào đứng sau để bảo đảm lộ trình, tốc độ phát triển phụ thuộc vào người đóng góp và nhà tài trợ định kỳ.
Tuyên bố giấy phép nằm cuối README: MapLibre GL JS phát hành theo BSD 3-Clause. Với sản phẩm thương mại, giấy phép này cho phép dùng và sửa đổi miễn là giữ thông báo bản quyền. Điều khoản ít người chú ý là cảnh báo unauthorized backports: không được đưa code từ mapbox-gl-js bản mới vào MapLibre, vì code Mapbox hiện tại không còn thuộc BSD-3 như thời mapbox-gl-js 1.x. Nếu bạn từng làm việc với code Mapbox và muốn đóng góp cho MapLibre, hãy rà soát kỹ nguồn gốc từng dòng code.
Câu hỏi thường gặp
MapLibre GL JS khác gì Mapbox GL JS?
MapLibre GL JS là nhánh fork của mapbox-gl-js 1.x, ra đời sau tháng 12/2020. Các bản 1.x gần như thay thế trực tiếp, càng về sau càng có thêm tính năng riêng. Điểm khác quyết định: MapLibre GL JS phát hành theo BSD-3, còn Mapbox mới không còn là phần mềm mã nguồn mở.
MapLibre GL JS có cần API key không?
README không yêu cầu API key từ Mapbox. Bạn cần cung cấp style JSON, còn bản đồ có dữ liệu hay không phụ thuộc vào nguồn tile trong style đó. Nếu bạn dùng tile server có thu phí, server đó có thể yêu cầu key, nhưng đó là việc của nhà cung cấp dữ liệu.
MapLibre GL JS thay thế được Leaflet không?
Tùy loại dữ liệu. Với bản đồ dùng ảnh tile chuẩn, Leaflet vẫn gọn và dễ học hơn. Với vector tiles và nhu cầu vẽ mượt bằng GPU, MapLibre GL JS phù hợp hơn. Thay vì chọn tuyệt đối, bạn có thể dùng maplibre-gl-leaflet để đặt MapLibre bên trong Leaflet.
Vì sao README MapLibre GL JS cấm backport code từ Mapbox?
Vì code trong mapbox-gl-js bản mới không còn thuộc giấy phép BSD-3 như phiên bản 1.x cũ. Nếu ai đó mang code đó vào MapLibre, dự án có thể vướng rắc rối pháp lý. README nói rõ nếu không chắc chắn, hãy hỏi trước.
Thử MapLibre GL JS trong buổi chiều: demo trước, style sau
Khởi động với README là đúng trình tự. Chạy bản đồ demo trước, rồi mở style.json trong tab mới và đọc cấu trúc layers để hiểu vì sao style quyết định mọi thứ. Kế đến, thay center và zoom bằng tọa độ quanh bạn, sau đó thay nguồn tile. Khi đưa lên production, đừng dùng @latest; hãy ghim một phiên bản cụ thể theo Semantic Versioning mà dự án đang áp dụng. Nếu bản đồ vẫn không lên, hãy kiểm tra theo bảng lỗi ở trên trước khi nghi ngờ code render.
