Cách Thêm Bản Đồ Tương Tác vào Trang Web Của Bạn | Hướng Dẫn

Mỗi bảng điều khiển logistics, danh sách bất động sản và ứng dụng giao hàng thực phẩm đều có một điều chung: một bản đồ. Nếu trang web của bạn chưa có, bạn đang để mất ngữ cảnh. Bối cảnh giúp người dùng hiểu vị trí, sự gần gũi và các mối quan hệ không gian trong nháy mắt.

Hướng dẫn này sẽ chỉ bạn cách thêm bản đồ hoàn toàn tương tác vào bất kỳ dự án JavaScript nào. Bạn sẽ bắt đầu với một bản đồ được hiển thị, thêm các điểm đánh dấu và cửa sổ bật lên, kết nối tìm kiếm địa chỉ với API Geocoding và kết thúc bằng một thành phần React sẵn sàng cho sản xuất có thể lắp vào Next.js một cách gọn gàng.

Đây là những gì bạn sẽ xây dựng vào cuối:

• Bản đồ vectơ trực tiếp được xác thực bằng khóa API của bạn
• Các điểm đánh dấu có thể nhấp với nội dung cửa sổ bật lên tùy chỉnh
• Chức năng tìm kiếm địa chỉ được hỗ trợ bằng địa mã hóa
• Thành phần React có thể tái sử dụng với dọn dẹp thích hợp và xử lý SSR Next.js
• Danh sách kiểm tra tối ưu hóa hiệu suất cho sản xuất

Điều Kiên Tiên Quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

• Khóa API MapAtlas (đăng ký miễn phí, không cần thẻ tín dụng). Khóa duy nhất này xác thực mọi dịch vụ MapAtlas: gạch, địa mã hóa và định tuyến.
• Một dự án JavaScript. HTML thuần, React, Vue hoặc Svelte đều hoạt động.
• Node.js 18+ nếu bạn cài đặt qua npm.

Bước 1: Cài Đặt SDK MapAtlas

Kéo SDK vào dự án của bạn bằng npm:

npm install @mapmetrics/mapmetrics-gl

Nếu bạn đang làm việc với một trang HTML thuần, hãy thả các liên kết CDN vào <head> của bạn:

<link rel="stylesheet" href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css" />
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>

Đừng bỏ qua nhập CSS. Không có nó, các điều khiển bản đồ và cửa sổ bật lên được hiển thị không có kiểu. Hoạt động, nhưng trông bị hỏng.

Bước 2: Tạo Vùng Chứa Bản Đồ

SDK điền vào bất kỳ phần tử nào bạn chỉ vào, vì vậy bạn cần một <div> có chiều cao rõ ràng. Đây là lỗi thiết lập phổ biến nhất: nếu vùng chứa có height: 0, bản đồ sẽ được khởi tạo nhưng vẫn không nhìn thấy được.

<div id="map" style="width: 100%; height: 500px;"></div>

Một giá trị pixel cố định hoặc đơn vị chế độ xem (100vh, 50vh) đều hoạt động. Chiều cao phần trăm chỉ hoạt động nếu phần tử cha cũng có chiều cao được xác định.

Bước 3: Hiển Thị Bản Đồ Tương Tác Đầu Tiên Của Bạn

Ba dòng cấu hình là tất cả những gì cần thiết: một vùng chứa, URL kiểu với khóa API của bạn và vị trí bắt đầu.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676],
  zoom: 12,
});

Mở trang và bạn sẽ thấy một bản đồ vectơ mà bạn có thể kéo, cuộn và chụm để điều hướng. Các gạch được tải theo yêu cầu từ các máy chủ MapAtlas, vì vậy không có tải xuống nặng ở phía trước.

Chọn Kiểu Bản Đồ

Kiểu bản đồ nằm trong tài khoản của bạn. Trong cổng MapMetrics, mở Styles, tạo hoặc tùy chỉnh một kiểu, lưu lại và sao chép Style URL của nó. URL này đã chứa token của bạn, nên có thể đưa thẳng vào tùy chọn style. Hãy giữ một kiểu cho mỗi giao diện bạn cần, ví dụ một kiểu sáng cho ứng dụng đa dụng và một kiểu tối cho dashboard, rồi chuyển đổi giữa chúng bằng map.setStyle().

Chiến thắng nhanh chóng: Sử dụng một kiểu tối cho các bảng điều khiển quản trị và các công cụ được sử dụng trong các môi trường ánh sáng yếu. Nhiều người dùng thích kiểu này trong phòng thiếu sáng, và nó làm cho các lớp dữ liệu như heatmap và đường tuyến nổi bật về mặt trực quan trên nền.

Bước 4: Thêm Điểm Đánh Dấu và Cửa Sổ Bật Lên vào Bản Đồ Của Bạn

Bản đồ mà không có điểm đánh dấu chỉ là một hình ảnh nền. Các điểm đánh dấu biến một chế độ xem tĩnh thành những gì người dùng có thể tương tác.

Một Điểm Đánh Dấu duy nhất với Cửa Sổ Bật Lên

const popup = new mapmetricsgl.Popup().setHTML(`
  <strong>Amsterdam Central</strong>
  <p>Stationsplein, 1012 AB Amsterdam</p>
`);

new mapmetricsgl.Marker({ color: '#97C70A' })
  .setLngLat([4.9001, 52.3791])
  .setPopup(popup)
  .addTo(map);

Nhấp vào điểm đánh dấu và cửa sổ bật lên mở ra. Bạn có thể đặt bất kỳ HTML nào bên trong: địa chỉ, hình nhỏ, nút CTA, bất cứ thứ gì UI của bạn yêu cầu.

Vẽ Nhiều Điểm Đánh Dấu từ Dữ Liệu

Hầu hết các ứng dụng thế giới thực cần nhiều hơn một pin. Lặp lại một mảng và tạo một điểm đánh dấu cho mỗi mục nhập:

const locations = [
  { name: 'Amsterdam', coords: [4.9041, 52.3676] },
  { name: 'Rotterdam', coords: [4.4777, 51.9244] },
  { name: 'Utrecht',   coords: [5.1214, 52.0907] },
];

locations.forEach(({ name, coords }) => {
  const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat(coords)
    .setPopup(popup)
    .addTo(map);
});

Ghi chú hiệu suất: Điểm đánh dấu HTML là phần tử DOM, nên chỉ vài trăm điểm cũng làm bản đồ chậm đi ở chế độ xem thu nhỏ. Khi đó, hãy chuyển các điểm vào một nguồn GeoJSON có phân cụm (SDK hỗ trợ sẵn) và vẽ chúng thành một lớp. Kiểm tra tài liệu SDK để cấu hình phân cụm.

Bước 5: Thêm Tìm Kiếm Địa Chỉ bằng API Địa Mã Hóa

API Geocoding chuyển đổi truy vấn văn bản (địa chỉ đường phố, tên thành phố hoặc điểm mốc) thành tọa độ mà bạn có thể bay tới, đánh dấu hoặc đưa vào yêu cầu định tuyến.

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', 'YOUR_API_KEY');
  const res  = await fetch(url);
  const data = await res.json();
  if (!data.features.length) return;
  const [lng, lat] = data.features[0].geometry.coordinates;
  const label      = data.features[0].properties.label;
  map.flyTo({ center: [lng, lat], zoom: 14 });
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat([lng, lat])
    .setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
    .addTo(map);
}
searchAddress('Rijksmuseum, Amsterdam');

Kết quả trở lại dưới dạng các tính năng GeoJSON, vì vậy chúng kết nối trực tiếp với bất kỳ lớp nào tương thích với GeoJSON, bảng dữ liệu hoặc lệnh gọi API hạ lưu.

Xây dựng thanh tìm kiếm trực tiếp trong dưới 30 dòng: Gắn searchAddress vào sự kiện input của trường văn bản, debounce trong 300ms và bạn có tìm kiếm bản đồ kiểu tự động hoàn thành mà không phụ thuộc bổ sung.

Tích Hợp Bản Đồ Tương Tác với React

Thành Phần Bản Đồ Có Thể Tái Sử Dụng

Bao bọc khởi tạo bản đồ trong useEffect để nó chạy sau khi DOM gắn và trả lại một chức năng dọn dẹp để ngăn chặn rò rỉ bộ nhớ khi ngắt kết nối:

import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

export function MapAtlasMap({ apiKey, center = [4.9041, 52.3676], zoom = 12 }) {
  const containerRef = useRef(null);
  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container: containerRef.current,
      style: `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center, zoom,
    });
    return () => map.remove();
  }, [apiKey]);
  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

Sử dụng nó ở bất kỳ đâu trong cây thành phần của bạn:

<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />

Xử Lý Kết Xuất Phía Máy Chủ Next.js

SDK bản đồ phụ thuộc vào các API trình duyệt (window, document) không tồn tại trong quá trình SSR. Nhập thành phần động với SSR bị vô hiệu hóa:

import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
  () => import('./MapAtlasMap').then(m => m.MapAtlasMap),
  { ssr: false, loading: () => (<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />) }
);

Trình giữ chỗ loading giữ cho bố cục của bạn ổn định khi tải xuống gói bản đồ, ngăn chặn cumulative layout shift (CLS), điều quan trọng đối với trải nghiệm người dùng và Core Web Vitals.

Danh Sách Kiểm Tra Hiệu Suất Sản Xuất

Trước khi vận chuyển, hãy chạy qua các tối ưu hóa này:

• Bản đồ tải chậm dưới đường gấp. Sử dụng IntersectionObserver để khởi tạo bản đồ chỉ khi vùng chứa của nó cuộn vào chế độ xem. Điều này hoãn khoảng 250 KB JavaScript đã nén từ tải trang ban đầu.
• Tuân thủ các gạch vectơ. Các gạch vectơ mở rộng sạch sẽ đến mật độ màn hình bất kỳ, cần ít yêu cầu hơn khi người dùng phóng to và có thể được đặt kiểu lại phía khách hàng mà không cần các yêu cầu máy chủ bổ sung. MapAtlas phục vụ các gạch vectơ theo mặc định.
• Phân cụm các bộ điểm đánh dấu lớn. Vài trăm điểm đánh dấu HTML trong chế độ xem thu nhỏ gây ra hiện tượng rớt khung hình rõ rệt. Một lớp GeoJSON có phân cụm giúp tránh điều này.
• Giới hạn khóa dùng trên trình duyệt. Một khóa dùng trên trình duyệt, kể cả khóa nằm trong biến môi trường NEXT_PUBLIC_, đều hiển thị với bất kỳ ai mở DevTools. Không bao giờ commit khóa vào kho lưu trữ công khai, giới hạn khóa trình duyệt chỉ cho các tên miền của bạn trong cổng quản lý, và proxy các yêu cầu qua backend của bạn cho các thao tác nhạy cảm.
• Đặt maxBounds cho các ứng dụng khu vực. Nếu người dùng của bạn chỉ quan tâm đến một địa lý, hãy hạn chế chế độ xem để gạch bên ngoài khu vực đó không bao giờ được yêu cầu. Ít hơn các cuộc gọi mạng, tải nhanh hơn.

Điều Gì Để Xây Dựng Tiếp Theo

Bạn có một bản đồ hiển thị, hiển thị các điểm đánh dấu, tìm kiếm địa chỉ và tích hợp với React. Đây là nơi để đi từ đây:

• Routing API: Yêu cầu hướng dẫn từng bước giữa hai tọa độ. Trả lại đường tuyến, tổng khoảng cách và thời gian di chuyển ước tính.
• Isochrone API: Tạo đa giác che phủ mọi điểm có thể truy cập trong n phút. Được sử dụng cho các vùng giao hàng, bản đồ cơ sở hạ tầng dịch vụ và phân tích khu vực bắt giữ.
• Matrix API: Tính thời gian di chuyển và khoảng cách giữa nhiều điểm xuất phát và điểm đến trong một yêu cầu duy nhất. Cần thiết cho gửi vận đội và tối ưu hóa logistics.

Tài liệu tham khảo SDK đầy đủ, tài liệu kiểu và hướng dẫn API có sẵn tại docs.mapatlas.xyz.

Câu Hỏi Thường Gặp

Tôi có thể thêm bản đồ tương tác vào trang web của mình miễn phí không?

Vâng. MapAtlas cung cấp một gói miễn phí mà không cần thẻ tín dụng khi đăng ký. Nó bao gồm kết xuất gạch vectơ, API Geocoding và API Routing. Đó là đủ cho phát triển và sử dụng sản xuất quy mô nhỏ.

Làm cách nào để nhúng bản đồ trong ứng dụng React hoặc Next.js?

Bao bọc khởi tạo bản đồ trong hook useEffect để nó chạy sau khi DOM gắn. Trong Next.js, sử dụng dynamic() với ssr: false để tránh lỗi kết xuất phía máy chủ. Cả hai cách tiếp cận được đề cập với các ví dụ copy-paste trong hướng dẫn này.

Các gạch vectơ là gì và tại sao tôi nên sử dụng chúng so với raster?

Các gạch vectơ mô tả các đặc điểm bản đồ (đường, tòa nhà, nhãn) dưới dạng hình học toán học thay vì hình ảnh pixel được kết xuất trước. Chúng mở rộng sắc nét đến độ phân giải bất kỳ, cần ít lượt tải hơn khi bạn phóng to và có thể được đặt kiểu lại hoàn toàn phía khách hàng mà không cần các vòng máy chủ bổ sung.

Tôi có thể thêm bao nhiêu điểm đánh dấu trước khi hiệu suất giảm?

Kết xuất thường chậm đi khi số điểm đánh dấu HTML lên tới vài trăm ở mức zoom thấp. Sửa chữa là phân cụm: SDK MapAtlas hỗ trợ phân cụm nguồn GeoJSON một cách tự nhiên, nhóm các điểm đánh dấu gần nhau ở mức zoom thấp và mở rộng khi người dùng phóng to.

Tôi có cần kinh nghiệm GIS để sử dụng MapAtlas không?

Không. SDK được thiết kế cho các nhà phát triển web, không phải là các chuyên gia GIS. Bạn khởi tạo bản đồ với tọa độ và mức zoom, thêm các điểm đánh dấu với các cặp kinh độ/vĩ độ và gọi API Geocoding bằng văn bản thuần. Không cần cơ sở dữ liệu không gian hoặc công cụ GIS.