# Cách tích hợp một bản đồ di chuyển vào trang web của bạn?

> Tích hợp bản đồ ROOTE vào trang web của bạn: iframe tự điều chỉnh, bộ lọc xe đạp, nhà vệ sinh, xe buýt và tàu điện, tìm kiếm thành phố và truyền tham số.

Source: https://www.roote.ai/vi/guides/cach-tich-hop-ban-do-di-chuyen-trong-trang-web/
Language: vi
Author: ROOTE

Để tích hợp một bản đồ di chuyển vào trang web của bạn mà không cần xây dựng toàn bộ giao diện, sử dụng iframe ROOTE. Embed này có thể nhận tìm kiếm thành phố và các bộ lọc phù hợp với trang: xe đạp cho hướng dẫn xe đạp, nhà vệ sinh cho hướng dẫn WC, xe buýt và tàu điện cho giao thông.

Các ví dụ trong hướng dẫn này sử dụng embed.roote.ai, tên miền được tích hợp trong các hướng dẫn ROOTE. Tài liệu chung cũng mô tả việc tích hợp map.roote.ai và phân biệt tham số camera với tham số tìm kiếm đầy đủ.

## Thêm một iframe tự điều chỉnh

Khối này mở một tìm kiếm xe đạp ở Bordeaux với mức thu phóng 15. URL được xây dựng trong mã; tiêu đề của iframe mô tả nội dung cho trình đọc màn hình. Điều chỉnh tiêu đề này phù hợp với ngôn ngữ của trang bạn.

```
<iframe
  title="Carte ROOTE — vélos à Bordeaux"
  src="https://embed.roote.ai/?q=Bordeaux&amp;modes=bicycle&amp;zoom=15"
  width="100%"
  height="480"
  loading="lazy"
  allow="geolocation"
  style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>
```

Trong một thuộc tính HTML, các dấu phân cách & được viết là &amp;. Chiều rộng 100% theo kích thước của phần chứa. Giữ chiều cao phù hợp sử dụng trên di động và tránh đặt các điều khiển quan trọng ra ngoài vùng nhìn thấy được.

## Chọn các chế độ phù hợp với trang

| Nhu cầu | Tham số của embed |
| --- | --- |
| Xe đạp | modes=bicycle |
| Nhà vệ sinh | modes=toilets |
| Xe buýt | modes=bus |
| Tàu điện | modes=tram |
| Xe buýt và tàu điện | modes=bus,tram |
| Xe đạp và nhà vệ sinh | modes=bicycle,toilets |

Những giá trị này thuộc phần embed ROOTE được kết nối với các nhóm di chuyển, dịch vụ và vận chuyển. Chúng không thay thế tham số REST: Services sử dụng types, còn Transit dùng modes. Một bản đồ được trung tâm trên một thành phố không đảm bảo mỗi nhóm đều có kết quả ở đó.

## Phân biệt camera và nguồn gốc tìm kiếm

lat và lon định vị camera. Chúng không đủ để tạo một tìm kiếm lân cận trong hợp đồng tài liệu của bản đồ. Để phục hồi một tìm kiếm đã biết, sử dụng search_lat, search_lon và search_label cùng với modes và mức thu phóng.

```
https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram
```

Tọa độ trên là một điểm tham chiếu tại Bordeaux, không phải vị trí người dùng. Nếu bạn cũng thêm tham số camera, bạn có thể hiển thị vùng khác trong khi vẫn giữ điểm dùng để tính khoảng cách. Chỉ làm điều này nếu muốn tách biệt hai phần đó.

[Tài liệu tham số của bản đồ ROOTE](https://doc.roote.ai/map)

## Xây dựng URL mà không mất các ký tự đặc biệt

Sử dụng URL và URLSearchParams thay vì nối chuỗi thủ công. Điều này mã hóa khoảng trắng, dấu và dấu phân cách. Đoạn mã này dành cho trình duyệt và tạo địa chỉ iframe dựa trên vị trí nhập vào.

```
const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();
```

## Giữ nguyên ngữ cảnh khi chuyển sang bản đồ đầy đủ

Liên kết tới map.roote.ai phải giữ trạng thái tìm kiếm hiện tại nếu bạn biết. Tạo lại URL mà không có tham số sẽ mất thành phố, chế độ hoặc mức thu phóng. Giữ một đối tượng URL chung trong các cập nhật trên trang của bạn.

```
const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';
```

Mã này giữ các tham số được trang cha biết. Nếu người dùng thay đổi tìm kiếm trong iframe, trang cha không thể đọc URL trực tiếp từ miền khác. Để lấy trạng thái này, cần một cơ chế triển khai rõ ràng và có tài liệu, ví dụ trao đổi postMessage với xác nhận nguồn gốc. Không tự nghĩ ra tên sự kiện không có trong embed.

## Quản lý vị trí và tương tác trên di động

allow="geolocation" cho phép iframe yêu cầu vị trí, tuân theo sự đồng ý và chính sách quyền của trang. Từ chối phải để tìm kiếm thành phố hoạt động bình thường. Không yêu cầu vị trí ngay khi người dùng vào trang nếu họ chưa chủ động chọn.

Trên bài viết, kích hoạt bản đồ thủ công giúp tránh việc cuộn hoặc thu phóng ảnh hưởng đến thao tác đọc. Điều khiển phải còn truy cập được bằng bàn phím và có tên rõ ràng. Kiểm tra thay đổi hướng màn hình và màn hình nhỏ, không chỉ phiên bản máy tính.

## Kiểm tra kết quả và tình trạng lỗi

Thử từng bộ lọc, một thành phố quen thuộc, vùng ít dữ liệu, tìm kiếm không hợp lệ và nhóm không có dữ liệu. Bản đồ không có đánh dấu không thể báo rằng tìm kiếm trống hay có lỗi. Giữ lại các tin nhắn từ embed và truy cập bản đồ đầy đủ dễ dàng.

[Phân biệt không có kết quả và lỗi API](https://www.roote.ai/vi/guides/khong-co-ket-qua-hay-loi-api-lam-the-nao-de-phan-biet/)

[Chọn giữa embed, API và MCP](https://www.roote.ai/vi/guides/api-hay-mcp-lua-chon-nao-de-tich-hop-du-lieu-di-chuyen/)

[Ví dụ hướng dẫn tìm nhà vệ sinh](https://www.roote.ai/vi/guides/cach-tim-nha-ve-sinh-cong-cong-mien-phi-xung-quanh/)

## Câu hỏi thường gặp

### Có cần đặt key API trong iframe không?

URL công khai hiện tại không có. Không đặt bí mật trong URL embed hay mã phía khách.

### zoom=15 có làm tăng bán kính tìm kiếm không?

Zoom điều khiển khung nhìn. Không coi đó là bán kính truy vấn API; kiểm tra tham số tìm kiếm của giao diện bạn dùng.

### Trang cha có biết các thay đổi trong iframe không?

Trang cha biết các tham số nó truyền. Thay đổi bên trong yêu cầu cơ chế trao đổi có tài liệu giữa hai miền.