Source: https://maps.vietmap.vn/docs/vi/sdk-web-gl/overview/

# Tổng quan SDK Web
![SDK WEB Overview]

[SDK WEB Overview]: https://maps.vietmap.vn/docs/assets/sdk-web.webp  

## Giới thiệu

VietMap GL JS là thư viện JavaScript hiển thị bản đồ vector bằng WebGL trên trình duyệt. Bản đồ render phía client nên chuyển cảnh mượt, đổi được màu, nhãn, icon ngay lúc chạy, và dùng chung API key, style với các dịch vụ khác của VIETMAP.

### Tính năng chính
- **Tùy chỉnh style bản đồ**: đổi giao diện bản đồ cho hợp với ứng dụng của bạn.
- **Bản đồ vector**: hiển thị nhanh, phóng to thu nhỏ mượt nhờ vector tile.
- **Tương thích**: dùng cùng các API và công cụ khác của VIETMAP.

---

## Bắt đầu nhanh

Các bước để đưa VietMap GL JS vào dự án:

### 1. Thêm thư viện

- Với HTML
Thêm file JavaScript và CSS vào thẻ `<head>` của trang:

```html
    <script src="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.js"></script>
    <link href="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.css" rel="stylesheet" />
```  
- Với React
Cài package VietMap GL JS qua npm:

```bash
  npm install @vietmap/vietmap-gl-js
```  

### 2. Thêm khung chứa bản đồ

Đặt một thẻ `<div>` trong `<body>` làm khung chứa bản đồ, và đặt kích thước cho nó:

```html
<div id="map" style="width: 400px; height: 300px;"></div>
```  

### 3. Khởi tạo bản đồ

Khởi tạo và cấu hình bản đồ bằng đoạn JavaScript sau:

```html
<script>
  var map = new vietmapgl.Map({
    container: "map", // ID of the map container
    style: "https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=your-apikey", // Map style URL (replace "your-apikey" with your actual API key)
    center: [10, 106], // Initial map center coordinates [longitude, latitude]
    zoom: 9, // Initial zoom level
  });
</script>
```  


Muốn dùng màu và icon riêng, tạo bản đồ trong [Map Editor](https://tools.vietmap.vn/map-editor/) rồi thay URL style ở trên bằng link style của bản đồ đó.

Xong các bước trên, bản đồ hiện trên trang và dùng được ngay.

---

## Tài liệu chi tiết

Tài liệu VietMap GL JS chia thành các phần sau:

### 1. **Map**
Đối tượng `Map` đại diện cho bản đồ trên trang. Qua nó bạn có thể:
- **Đổi style**: thay style và các lớp bản đồ lúc đang chạy.
- **Xử lý sự kiện**: phản hồi khi người dùng bấm, kéo hoặc phóng to thu nhỏ.
- **Điều khiển camera**: đổi góc nhìn, có hiệu ứng chuyển cảnh.

---

### 2. **Marker và control**
Cách thêm các thành phần tương tác và nút điều khiển lên bản đồ:
- **Marker**: đánh dấu một điểm trên bản đồ.
- **Control**: nút phóng to, xoay bản đồ hoặc control tự làm, nằm ngoài vùng vẽ bản đồ.
- **Popup**: hiện thông tin khi người dùng bấm vào marker hoặc đối tượng trên bản đồ.
- **Đường và vùng**: vẽ polyline, polygon lên bản đồ.

---

### 3. **Toạ độ và hình học**
Các tiện ích làm việc với dữ liệu địa lý, ví dụ:
- Chuyển đổi toạ độ.
- Tạo và sửa các hình như polygon, đường.

 ---

### 4. **Sự kiện**
Hệ thống sự kiện của VietMap GL JS, ví dụ:
- **Map load**: biết khi bản đồ đã tải xong.
- **Click**: phản hồi khi người dùng bấm vào đối tượng hoặc marker.
- **Zoom và kéo**: chạy logic riêng khi người dùng thao tác với bản đồ.

---

## Lưu ý

1. **API key**: thay `"your-apikey"` trong URL style bằng API key thật — [đăng ký miễn phí trên VIETMAP Console](https://maps.vietmap.vn/console-v2/register) để lấy key.

Ví dụ, tuỳ chọn cấu hình và cách dùng nâng cao xem ở các trang tiếp theo trong mục SDK Web.